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