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