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