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