Google's data interchange format. Copyright 2010 The Go Authors. https://github.com/golang/protobuf
This package and the code it generates requires at least Go 1.6.
This software implements Go bindings for protocol buffers. For information about protocol buffers themselves, see https://developers.google.com/protocol-buffers/
To use this software, you must:
go get -u github.com/golang/protobuf/protoc-gen-go
. The compiler plugin, protoc-gen-go, will be installed in $GOBIN, defaulting to $GOPATH/bin. It must be in your $PATH for the protocol compiler, protoc, to find it.This software has two parts: a ‘protocol compiler plugin’ that generates Go source files that, once compiled, can access and manage protocol buffers; and a library that implements run-time support for encoding (marshaling), decoding (unmarshaling), and accessing protocol buffers.
There is support for gRPC in Go using protocol buffers. See the note at the bottom of this file for details.
There are no insertion points in the plugin.
Once the software is installed, there are two steps to using it. First you must compile the protocol buffer definitions and then import them, with the support library, into your program.
To compile the protocol buffer definition, run protoc with the --go_out parameter set to the directory you want to output the Go code to.
protoc --go_out=. *.proto
The generated files will be suffixed .pb.go. See the Test code below for an example using such a file.
The protocol buffer language has a concept of “packages” which does not correspond well to the Go notion of packages. In generated Go code, each source .proto
file is associated with a single Go package. The name and import path for this package is specified with the go_package
proto option:
option go_package = "github.com/golang/protobuf/ptypes/any";
The protocol buffer compiler will attempt to derive a package name and import path if a go_package
option is not present, but it is best to always specify one explicitly.
There is a one-to-one relationship between source .proto
files and generated .pb.go
files, but any number of .pb.go
files may be contained in the same Go package.
The output name of a generated file is produced by replacing the .proto
suffix with .pb.go
(e.g., foo.proto
produces foo.pb.go
). However, the output directory is selected in one of two ways. Let us say we have inputs/x.proto
with a go_package
option of github.com/golang/protobuf/p
. The corresponding output file may be:
protoc --go_out=. inputs/x.proto # writes ./github.com/golang/protobuf/p/x.pb.go
(This can work well with --go_out=$GOPATH
.)
protoc --go_out=paths=source_relative:. inputs/x.proto # generate ./inputs/x.pb.go
The package comment for the proto library contains text describing the interface provided in Go for protocol buffers. Here is an edited version.
The proto package converts data structures to and from the wire format of protocol buffers. It works in concert with the Go source code generated for .proto files by the protocol compiler.
A summary of the properties of the protocol buffer interface for a protocol buffer variable v:
When the .proto file specifies syntax="proto3"
, there are some differences:
Consider file test.proto, containing
syntax = "proto2"; package example; enum FOO { X = 17; }; message Test { required string label = 1; optional int32 type = 2 [default=77]; repeated int64 reps = 3; }
To create and play with a Test object from the example package,
package main import ( "log" "github.com/golang/protobuf/proto" "path/to/example" ) func main() { test := &example.Test{ Label: proto.String("hello"), Type: proto.Int32(17), Reps: []int64{1, 2, 3}, } data, err := proto.Marshal(test) if err != nil { log.Fatal("marshaling error: ", err) } newTest := &example.Test{} err = proto.Unmarshal(data, newTest) if err != nil { log.Fatal("unmarshaling error: ", err) } // Now test and newTest contain the same data. if test.GetLabel() != newTest.GetLabel() { log.Fatalf("data mismatch %q != %q", test.GetLabel(), newTest.GetLabel()) } // etc. }
To pass extra parameters to the plugin, use a comma-separated parameter list separated from the output directory by a colon:
protoc --go_out=plugins=grpc,import_path=mypackage:. *.proto
paths=(import | source_relative)
- specifies how the paths of generated files are structured. See the “Packages and imports paths” section above. The default is import
.plugins=plugin1+plugin2
- specifies the list of sub-plugins to load. The only plugin in this repo is grpc
.Mfoo/bar.proto=quux/shme
- declares that foo/bar.proto is associated with Go package quux/shme. This is subject to the import_prefix parameter.The following parameters are deprecated and should not be used:
import_prefix=xxx
- a prefix that is added onto the beginning of all imports.import_path=foo/bar
- used as the package if no input files declare go_package
. If it contains slashes, everything up to the rightmost slash is ignored.If a proto file specifies RPC services, protoc-gen-go can be instructed to generate code compatible with gRPC (http://www.grpc.io/). To do this, pass the plugins
parameter to protoc-gen-go; the usual way is to insert it into the --go_out argument to protoc:
protoc --go_out=plugins=grpc:. *.proto
The library and the generated code are expected to be stable over time. However, we reserve the right to make breaking changes without notice for the following reasons:
XXX
. These parts of the generated code are exported out of necessity, but should not be considered part of the public API.Any breaking changes outside of these will be announced 6 months in advance to protobuf@googlegroups.com.
You should, whenever possible, use generated code created by the protoc-gen-go
tool built at the same commit as the proto
package. The proto
package declares package-level constants in the form ProtoPackageIsVersionX
. Application code and generated code may depend on one of these constants to ensure that compilation will fail if the available version of the proto library is too old. Whenever we make a change to the generated code that requires newer library support, in the same commit we will increment the version number of the generated code and declare a new package-level constant whose name incorporates the latest version number. Removing a compatibility constant is considered a breaking change and would be subject to the announcement policy stated above.
The protoc-gen-go/generator
package exposes a plugin interface, which is used by the gRPC code generation. This interface is not supported and is subject to incompatible changes without notice.