vendor/github.com/gogo/protobuf/README

   1 GoGoProtobuf http://github.com/gogo/protobuf extends
   2 GoProtobuf http://github.com/golang/protobuf
   3
   4 # Go support for Protocol Buffers
   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.4.
  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/{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
  33 This software has two parts: a 'protocol compiler plugin' that
  34 generates Go source files that, once compiled, can access and manage
  35 protocol buffers; and a library that implements run-time support for
  36 encoding (marshaling), decoding (unmarshaling), and accessing protocol
  37 buffers.
  38
  39 There is support for gRPC in Go using protocol buffers.
  40 See the note at the bottom of this file for details.
  41
  42 There are no insertion points in the plugin.
  43
  44 GoGoProtobuf provides extensions for protocol buffers and GoProtobuf
  45 see http://github.com/gogo/protobuf/gogoproto/doc.go
  46
  47 ## Using protocol buffers with Go ##
  48
  49 Once the software is installed, there are two steps to using it.
  50 First you must compile the protocol buffer definitions and then import
  51 them, with the support library, into your program.
  52
  53 To compile the protocol buffer definition, run protoc with the --gogo_out
  54 parameter set to the directory you want to output the Go code to.
  55
  56         protoc --gogo_out=. *.proto
  57
  58 The generated files will be suffixed .pb.go.  See the Test code below
  59 for an example using such a file.
  60
  61 The package comment for the proto library contains text describing
  62 the interface provided in Go for protocol buffers. Here is an edited
  63 version.
  64
  65 If you are using any gogo.proto extensions you will need to specify the
  66 proto_path to include the descriptor.proto and gogo.proto.
  67 gogo.proto is located in github.com/gogo/protobuf/gogoproto
  68 This should be fine, since your import is the same.
  69 descriptor.proto is located in either github.com/gogo/protobuf/protobuf
  70 or code.google.com/p/protobuf/trunk/src/
  71 Its 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
  77 The proto package converts data structures to and from the
  78 wire format of protocol buffers.  It works in concert with the
  79 Go source code generated for .proto files by the protocol compiler.
  80
  81 A summary of the properties of the protocol buffer interface
  82 for 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
 118 When 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
 124 Consider 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
 141 To 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
 182 To pass extra parameters to the plugin, use a comma-separated
 183 parameter 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
 203 If a proto file specifies RPC services, protoc-gen-go can be instructed to
 204 generate code compatible with gRPC (http://www.grpc.io/). To do this, pass
 205 the `plugins` parameter to protoc-gen-go; the usual way is to insert it into
 206 the --go_out argument to protoc:
 207
 208         protoc --gogo_out=plugins=grpc:. *.proto
 209
 210 ## Compatibility ##
 211
 212 The library and the generated code are expected to be stable over time.
 213 However, we reserve the right to make breaking changes without notice for the
 214 following 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
 240 Any breaking changes outside of these will be announced 6 months in advance to
 241 protobuf@googlegroups.com.
 242
 243 You should, whenever possible, use generated code created by the `protoc-gen-go`
 244 tool built at the same commit as the `proto` package.  The `proto` package
 245 declares package-level constants in the form `ProtoPackageIsVersionX`.
 246 Application code and generated code may depend on one of these constants to
 247 ensure that compilation will fail if the available version of the proto library
 248 is too old.  Whenever we make a change to the generated code that requires newer
 249 library support, in the same commit we will increment the version number of the
 250 generated code and declare a new package-level constant whose name incorporates
 251 the latest version number.  Removing a compatibility constant is considered a
 252 breaking change and would be subject to the announcement policy stated above.
 253
 254 ## Plugins ##
 255
 256 The `protoc-gen-go/generator` package exposes a plugin interface,
 257 which is used by the gRPC code generation. This interface is not
 258 supported and is subject to incompatible changes without notice.