• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Go support for Protocol Buffers
2
3[![Build Status](https://travis-ci.org/golang/protobuf.svg?branch=master)](https://travis-ci.org/golang/protobuf)
4
5Google's data interchange format.
6Copyright 2010 The Go Authors.
7https://github.com/golang/protobuf
8
9This package and the code it generates requires at least Go 1.4.
10
11This software implements Go bindings for protocol buffers.  For
12information about protocol buffers themselves, see
13	https://developers.google.com/protocol-buffers/
14
15## Installation ##
16
17To use this software, you must:
18- Install the standard C++ implementation of protocol buffers from
19	https://developers.google.com/protocol-buffers/
20- Of course, install the Go compiler and tools from
21	https://golang.org/
22  See
23	https://golang.org/doc/install
24  for details or, if you are using gccgo, follow the instructions at
25	https://golang.org/doc/install/gccgo
26- Grab the code from the repository and install the proto package.
27  The simplest way is to run `go get -u github.com/golang/protobuf/protoc-gen-go`.
28  The compiler plugin, protoc-gen-go, will be installed in $GOBIN,
29  defaulting to $GOPATH/bin.  It must be in your $PATH for the protocol
30  compiler, protoc, to find it.
31
32This software has two parts: a 'protocol compiler plugin' that
33generates Go source files that, once compiled, can access and manage
34protocol buffers; and a library that implements run-time support for
35encoding (marshaling), decoding (unmarshaling), and accessing protocol
36buffers.
37
38There is support for gRPC in Go using protocol buffers.
39See the note at the bottom of this file for details.
40
41There are no insertion points in the plugin.
42
43
44## Using protocol buffers with Go ##
45
46Once the software is installed, there are two steps to using it.
47First you must compile the protocol buffer definitions and then import
48them, with the support library, into your program.
49
50To compile the protocol buffer definition, run protoc with the --go_out
51parameter set to the directory you want to output the Go code to.
52
53	protoc --go_out=. *.proto
54
55The generated files will be suffixed .pb.go.  See the Test code below
56for an example using such a file.
57
58
59The package comment for the proto library contains text describing
60the interface provided in Go for protocol buffers. Here is an edited
61version.
62
63==========
64
65The proto package converts data structures to and from the
66wire format of protocol buffers.  It works in concert with the
67Go source code generated for .proto files by the protocol compiler.
68
69A summary of the properties of the protocol buffer interface
70for a protocol buffer variable v:
71
72  - Names are turned from camel_case to CamelCase for export.
73  - There are no methods on v to set fields; just treat
74  	them as structure fields.
75  - There are getters that return a field's value if set,
76	and return the field's default value if unset.
77	The getters work even if the receiver is a nil message.
78  - The zero value for a struct is its correct initialization state.
79	All desired fields must be set before marshaling.
80  - A Reset() method will restore a protobuf struct to its zero state.
81  - Non-repeated fields are pointers to the values; nil means unset.
82	That is, optional or required field int32 f becomes F *int32.
83  - Repeated fields are slices.
84  - Helper functions are available to aid the setting of fields.
85	Helpers for getting values are superseded by the
86	GetFoo methods and their use is deprecated.
87		msg.Foo = proto.String("hello") // set field
88  - Constants are defined to hold the default values of all fields that
89	have them.  They have the form Default_StructName_FieldName.
90	Because the getter methods handle defaulted values,
91	direct use of these constants should be rare.
92  - Enums are given type names and maps from names to values.
93	Enum values are prefixed with the enum's type name. Enum types have
94	a String method, and a Enum method to assist in message construction.
95  - Nested groups and enums have type names prefixed with the name of
96  	the surrounding message type.
97  - Extensions are given descriptor names that start with E_,
98	followed by an underscore-delimited list of the nested messages
99	that contain it (if any) followed by the CamelCased name of the
100	extension field itself.  HasExtension, ClearExtension, GetExtension
101	and SetExtension are functions for manipulating extensions.
102  - Oneof field sets are given a single field in their message,
103	with distinguished wrapper types for each possible field value.
104  - Marshal and Unmarshal are functions to encode and decode the wire format.
105
106When the .proto file specifies `syntax="proto3"`, there are some differences:
107
108  - Non-repeated fields of non-message type are values instead of pointers.
109  - Enum types do not get an Enum method.
110
111Consider file test.proto, containing
112
113```proto
114	package example;
115
116	enum FOO { X = 17; };
117
118	message Test {
119	  required string label = 1;
120	  optional int32 type = 2 [default=77];
121	  repeated int64 reps = 3;
122	  optional group OptionalGroup = 4 {
123	    required string RequiredField = 5;
124	  }
125	}
126```
127
128To create and play with a Test object from the example package,
129
130```go
131	package main
132
133	import (
134		"log"
135
136		"github.com/golang/protobuf/proto"
137		"path/to/example"
138	)
139
140	func main() {
141		test := &example.Test {
142			Label: proto.String("hello"),
143			Type:  proto.Int32(17),
144			Reps:  []int64{1, 2, 3},
145			Optionalgroup: &example.Test_OptionalGroup {
146				RequiredField: proto.String("good bye"),
147			},
148		}
149		data, err := proto.Marshal(test)
150		if err != nil {
151			log.Fatal("marshaling error: ", err)
152		}
153		newTest := &example.Test{}
154		err = proto.Unmarshal(data, newTest)
155		if err != nil {
156			log.Fatal("unmarshaling error: ", err)
157		}
158		// Now test and newTest contain the same data.
159		if test.GetLabel() != newTest.GetLabel() {
160			log.Fatalf("data mismatch %q != %q", test.GetLabel(), newTest.GetLabel())
161		}
162		// etc.
163	}
164```
165
166## Parameters ##
167
168To pass extra parameters to the plugin, use a comma-separated
169parameter list separated from the output directory by a colon:
170
171
172	protoc --go_out=plugins=grpc,import_path=mypackage:. *.proto
173
174
175- `import_prefix=xxx` - a prefix that is added onto the beginning of
176  all imports. Useful for things like generating protos in a
177  subdirectory, or regenerating vendored protobufs in-place.
178- `import_path=foo/bar` - used as the package if no input files
179  declare `go_package`. If it contains slashes, everything up to the
180  rightmost slash is ignored.
181- `plugins=plugin1+plugin2` - specifies the list of sub-plugins to
182  load. The only plugin in this repo is `grpc`.
183- `Mfoo/bar.proto=quux/shme` - declares that foo/bar.proto is
184  associated with Go package quux/shme.  This is subject to the
185  import_prefix parameter.
186
187## gRPC Support ##
188
189If a proto file specifies RPC services, protoc-gen-go can be instructed to
190generate code compatible with gRPC (http://www.grpc.io/). To do this, pass
191the `plugins` parameter to protoc-gen-go; the usual way is to insert it into
192the --go_out argument to protoc:
193
194	protoc --go_out=plugins=grpc:. *.proto
195
196## Compatibility ##
197
198The library and the generated code are expected to be stable over time.
199However, we reserve the right to make breaking changes without notice for the
200following reasons:
201
202- Security. A security issue in the specification or implementation may come to
203  light whose resolution requires breaking compatibility. We reserve the right
204  to address such security issues.
205- Unspecified behavior.  There are some aspects of the Protocol Buffers
206  specification that are undefined.  Programs that depend on such unspecified
207  behavior may break in future releases.
208- Specification errors or changes. If it becomes necessary to address an
209  inconsistency, incompleteness, or change in the Protocol Buffers
210  specification, resolving the issue could affect the meaning or legality of
211  existing programs.  We reserve the right to address such issues, including
212  updating the implementations.
213- Bugs.  If the library has a bug that violates the specification, a program
214  that depends on the buggy behavior may break if the bug is fixed.  We reserve
215  the right to fix such bugs.
216- Adding methods or fields to generated structs.  These may conflict with field
217  names that already exist in a schema, causing applications to break.  When the
218  code generator encounters a field in the schema that would collide with a
219  generated field or method name, the code generator will append an underscore
220  to the generated field or method name.
221- Adding, removing, or changing methods or fields in generated structs that
222  start with `XXX`.  These parts of the generated code are exported out of
223  necessity, but should not be considered part of the public API.
224- Adding, removing, or changing unexported symbols in generated code.
225
226Any breaking changes outside of these will be announced 6 months in advance to
227protobuf@googlegroups.com.
228
229You should, whenever possible, use generated code created by the `protoc-gen-go`
230tool built at the same commit as the `proto` package.  The `proto` package
231declares package-level constants in the form `ProtoPackageIsVersionX`.
232Application code and generated code may depend on one of these constants to
233ensure that compilation will fail if the available version of the proto library
234is too old.  Whenever we make a change to the generated code that requires newer
235library support, in the same commit we will increment the version number of the
236generated code and declare a new package-level constant whose name incorporates
237the latest version number.  Removing a compatibility constant is considered a
238breaking change and would be subject to the announcement policy stated above.
239
240The `protoc-gen-go/generator` package exposes a plugin interface,
241which is used by the gRPC code generation. This interface is not
242supported and is subject to incompatible changes without notice.
243