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