|
| 1 | +# Go support for Protocol Buffers |
| 2 | + |
| 3 | +Google's data interchange format. |
| 4 | +Copyright 2010 The Go Authors. |
| 5 | +https://github.com/golang/protobuf |
| 6 | + |
| 7 | +This package and the code it generates requires at least Go 1.4. |
| 8 | + |
| 9 | +This software implements Go bindings for protocol buffers. For |
| 10 | +information about protocol buffers themselves, see |
| 11 | + https://developers.google.com/protocol-buffers/ |
| 12 | + |
| 13 | +## Installation ## |
| 14 | + |
| 15 | +To 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 | + |
| 30 | +This software has two parts: a 'protocol compiler plugin' that |
| 31 | +generates Go source files that, once compiled, can access and manage |
| 32 | +protocol buffers; and a library that implements run-time support for |
| 33 | +encoding (marshaling), decoding (unmarshaling), and accessing protocol |
| 34 | +buffers. |
| 35 | + |
| 36 | +There is support for gRPC in Go using protocol buffers. |
| 37 | +See the note at the bottom of this file for details. |
| 38 | + |
| 39 | +There are no insertion points in the plugin. |
| 40 | + |
| 41 | + |
| 42 | +## Using protocol buffers with Go ## |
| 43 | + |
| 44 | +Once the software is installed, there are two steps to using it. |
| 45 | +First you must compile the protocol buffer definitions and then import |
| 46 | +them, with the support library, into your program. |
| 47 | + |
| 48 | +To compile the protocol buffer definition, run protoc with the --go_out |
| 49 | +parameter set to the directory you want to output the Go code to. |
| 50 | + |
| 51 | + protoc --go_out=. *.proto |
| 52 | + |
| 53 | +The generated files will be suffixed .pb.go. See the Test code below |
| 54 | +for an example using such a file. |
| 55 | + |
| 56 | + |
| 57 | +The package comment for the proto library contains text describing |
| 58 | +the interface provided in Go for protocol buffers. Here is an edited |
| 59 | +version. |
| 60 | + |
| 61 | +========== |
| 62 | + |
| 63 | +The proto package converts data structures to and from the |
| 64 | +wire format of protocol buffers. It works in concert with the |
| 65 | +Go source code generated for .proto files by the protocol compiler. |
| 66 | + |
| 67 | +A summary of the properties of the protocol buffer interface |
| 68 | +for 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 | + |
| 104 | +When 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 | + |
| 110 | +Consider 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 | + |
| 127 | +To 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 | + |
| 167 | +To pass extra parameters to the plugin, use a comma-separated |
| 168 | +parameter 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 | + |
| 188 | +If a proto file specifies RPC services, protoc-gen-go can be instructed to |
| 189 | +generate code compatible with gRPC (http://www.grpc.io/). To do this, pass |
| 190 | +the `plugins` parameter to protoc-gen-go; the usual way is to insert it into |
| 191 | +the --go_out argument to protoc: |
| 192 | + |
| 193 | + protoc --go_out=plugins=grpc:. *.proto |
| 194 | + |
| 195 | +## Compatibility ## |
| 196 | + |
| 197 | +The library and the generated code are expected to be stable over time. |
| 198 | +However, we reserve the right to make breaking changes without notice for the |
| 199 | +following 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 | + |
| 225 | +Any breaking changes outside of these will be announced 6 months in advance to |
| 226 | +protobuf@googlegroups.com. |
| 227 | + |
| 228 | +You should, whenever possible, use generated code created by the `protoc-gen-go` |
| 229 | +tool built at the same commit as the `proto` package. The `proto` package |
| 230 | +declares package-level constants in the form `ProtoPackageIsVersionX`. |
| 231 | +Application code and generated code may depend on one of these constants to |
| 232 | +ensure that compilation will fail if the available version of the proto library |
| 233 | +is too old. Whenever we make a change to the generated code that requires newer |
| 234 | +library support, in the same commit we will increment the version number of the |
| 235 | +generated code and declare a new package-level constant whose name incorporates |
| 236 | +the latest version number. Removing a compatibility constant is considered a |
| 237 | +breaking change and would be subject to the announcement policy stated above. |
| 238 | + |
| 239 | +The `protoc-gen-go/generator` package exposes a plugin interface, |
| 240 | +which is used by the gRPC code generation. This interface is not |
| 241 | +supported and is subject to incompatible changes without notice. |
0 commit comments