Repository files navigation

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.4.

This software implements Go bindings for protocol buffers. Forinformation about protocol buffers themselves, seehttps://developers.google.com/protocol-buffers/

To use this software, you must:

• Install the standard C++ implementation of protocol buffers fromhttps://developers.google.com/protocol-buffers/
• Of course, install the Go compiler and tools fromhttps://golang.org/Seehttps://golang.org/doc/installfor details or, if you are using gccgo, follow the instructions athttps://golang.org/doc/install/gccgo
• Grab the code from the repository and install the proto package.The simplest way is to rungo 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 protocolcompiler, protoc, to find it.

This software has two parts: a 'protocol compiler plugin' thatgenerates Go source files that, once compiled, can access and manageprotocol buffers; and a library that implements run-time support forencoding (marshaling), decoding (unmarshaling), and accessing protocolbuffers.

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 importthem, with the support library, into your program.

To compile the protocol buffer definition, run protoc with the --go_outparameter 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 belowfor an example using such a file.

The package comment for the proto library contains text describingthe interface provided in Go for protocol buffers. Here is an editedversion.

==========

The proto package converts data structures to and from thewire format of protocol buffers. It works in concert with theGo source code generated for .proto files by the protocol compiler.

A summary of the properties of the protocol buffer interfacefor a protocol buffer variable v:

• Names are turned from camel_case to CamelCase for export.
• There are no methods on v to set fields; just treatthem as structure fields.
• There are getters that return a field's value if set,and return the field's default value if unset.The getters work even if the receiver is a nil message.
• The zero value for a struct is its correct initialization state.All desired fields must be set before marshaling.
• A Reset() method will restore a protobuf struct to its zero state.
• Non-repeated fields are pointers to the values; nil means unset.That is, optional or required field int32 f becomes F *int32.
• Repeated fields are slices.
• Helper functions are available to aid the setting of fields.Helpers for getting values are superseded by theGetFoo methods and their use is deprecated.msg.Foo = proto.String("hello") // set field
• Constants are defined to hold the default values of all fields thathave them. They have the form Default_StructName_FieldName.Because the getter methods handle defaulted values,direct use of these constants should be rare.
• Enums are given type names and maps from names to values.Enum values are prefixed with the enum's type name. Enum types havea String method, and a Enum method to assist in message construction.
• Nested groups and enums have type names prefixed with the name ofthe surrounding message type.
• Extensions are given descriptor names that start with E_,followed by an underscore-delimited list of the nested messagesthat contain it (if any) followed by the CamelCased name of theextension field itself. HasExtension, ClearExtension, GetExtensionand SetExtension are functions for manipulating extensions.
• Oneof field sets are given a single field in their message,with distinguished wrapper types for each possible field value.
• Marshal and Unmarshal are functions to encode and decode the wire format.

When the .proto file specifiessyntax="proto3", there are some differences:

• Non-repeated fields of non-message type are values instead of pointers.
• Enum types do not get an Enum method.

Consider file test.proto, containing

syntax="proto2";packageexample;enumFOO {X=17; };messageTest {requiredstringlabel=1;optionalint32type=2 [default=77];repeatedint64reps=3;optionalgroupOptionalGroup=4 {    required string RequiredField = 5;  }}

To create and play with a Test object from the example package,

package mainimport ("log""github.com/golang/protobuf/proto""path/to/example")funcmain() {test:=&example.Test {Label:proto.String("hello"),Type:proto.Int32(17),Reps:  []int64{1,2,3},Optionalgroup:&example.Test_OptionalGroup {RequiredField:proto.String("good bye"),},}data,err:=proto.Marshal(test)iferr!=nil {log.Fatal("marshaling error: ",err)}newTest:=&example.Test{}err=proto.Unmarshal(data,newTest)iferr!=nil {log.Fatal("unmarshaling error: ",err)}// Now test and newTest contain the same data.iftest.GetLabel()!=newTest.GetLabel() {log.Fatalf("data mismatch %q != %q",test.GetLabel(),newTest.GetLabel())}// etc.}

To pass extra parameters to the plugin, use a comma-separatedparameter list separated from the output directory by a colon:

protoc --go_out=plugins=grpc,import_path=mypackage:. *.proto

• import_prefix=xxx - a prefix that is added onto the beginning ofall imports. Useful for things like generating protos in asubdirectory, or regenerating vendored protobufs in-place.
• import_path=foo/bar - used as the package if no input filesdeclarego_package. If it contains slashes, everything up to therightmost slash is ignored.
• plugins=plugin1+plugin2 - specifies the list of sub-plugins toload. The only plugin in this repo isgrpc.
• Mfoo/bar.proto=quux/shme - declares that foo/bar.proto isassociated with Go package quux/shme. This is subject to theimport_prefix parameter.

If a proto file specifies RPC services, protoc-gen-go can be instructed togenerate code compatible with gRPC (http://www.grpc.io/). To do this, passtheplugins parameter to protoc-gen-go; the usual way is to insert it intothe --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 thefollowing reasons:

• Security. A security issue in the specification or implementation may come tolight whose resolution requires breaking compatibility. We reserve the rightto address such security issues.
• Unspecified behavior. There are some aspects of the Protocol Buffersspecification that are undefined. Programs that depend on such unspecifiedbehavior may break in future releases.
• Specification errors or changes. If it becomes necessary to address aninconsistency, incompleteness, or change in the Protocol Buffersspecification, resolving the issue could affect the meaning or legality ofexisting programs. We reserve the right to address such issues, includingupdating the implementations.
• Bugs. If the library has a bug that violates the specification, a programthat depends on the buggy behavior may break if the bug is fixed. We reservethe right to fix such bugs.
• Adding methods or fields to generated structs. These may conflict with fieldnames that already exist in a schema, causing applications to break. When thecode generator encounters a field in the schema that would collide with agenerated field or method name, the code generator will append an underscoreto the generated field or method name.
• Adding, removing, or changing methods or fields in generated structs thatstart withXXX. These parts of the generated code are exported out ofnecessity, but should not be considered part of the public API.
• Adding, removing, or changing unexported symbols in generated code.

Any breaking changes outside of these will be announced 6 months in advance toprotobuf@googlegroups.com.

You should, whenever possible, use generated code created by theprotoc-gen-gotool built at the same commit as theproto package. Theproto packagedeclares package-level constants in the formProtoPackageIsVersionX.Application code and generated code may depend on one of these constants toensure that compilation will fail if the available version of the proto libraryis too old. Whenever we make a change to the generated code that requires newerlibrary support, in the same commit we will increment the version number of thegenerated code and declare a new package-level constant whose name incorporatesthe latest version number. Removing a compatibility constant is considered abreaking change and would be subject to the announcement policy stated above.

Theprotoc-gen-go/generator package exposes a plugin interface,which is used by the gRPC code generation. This interface is notsupported and is subject to incompatible changes without notice.