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