README

Protocol Buffers for Go with Gadgets

Build Status GoDoc

gogoprotobuf is a fork of golang/protobuf with extra code generation features.

This code generation is used to achieve:

  • fast marshalling and unmarshalling
  • more canonical Go structures
  • goprotobuf compatibility
  • less typing by optionally generating extra helper code
  • peace of mind by optionally generating test and benchmark code
  • other serialization formats

Keeping track of how up to date gogoprotobuf is relative to golang/protobuf is done in this issue

Release v1.3.0

The project has updated to release v1.3.0. Check out the release notes here.

With this new release comes a new internal library version. This means any newly generated *pb.go files generated with the v1.3.0 library will not be compatible with the old library version (v1.2.1). However, current *pb.go files (generated with v1.2.1) should still work with the new library.

Please make sure you manage your dependencies correctly when upgrading your project. If you are still using v1.2.1 and you update your dependencies, one of which could include a new *pb.go (generated with v1.3.0), you could get a compile time error.

Our upstream repo, golang/protobuf, also had to go through this process in order to update their library version. Here is a link explaining hermetic builds.

Users

These projects use gogoprotobuf:

Please let us know if you are using gogoprotobuf by posting on our GoogleGroup.

Mentioned

Getting Started

There are several ways to use gogoprotobuf, but for all you need to install go and protoc. After that you can choose:

  • Speed
  • More Speed and more generated code
  • Most Speed and most customization
Installation

To install it, you must first have Go (at least version 1.6.3 or 1.9 if you are using gRPC) installed (see http://golang.org/doc/install). Latest patch versions of 1.10 and 1.11 are continuously tested.

Next, install the standard protocol buffer implementation from https://github.com/google/protobuf. Most versions from 2.3.1 should not give any problems, but 2.6.1, 3.0.2 and 3.6.1 are continuously tested.

Speed

Install the protoc-gen-gofast binary

go get github.com/gogo/protobuf/protoc-gen-gofast

Use it to generate faster marshaling and unmarshaling go code for your protocol buffers.

protoc --gofast_out=. myproto.proto

This does not allow you to use any of the other gogoprotobuf extensions.

More Speed and more generated code

Fields without pointers cause less time in the garbage collector. More code generation results in more convenient methods.

Other binaries are also included:

protoc-gen-gogofast (same as gofast, but imports gogoprotobuf)
protoc-gen-gogofaster (same as gogofast, without XXX_unrecognized, less pointer fields)
protoc-gen-gogoslick (same as gogofaster, but with generated string, gostring and equal methods)

Installing any of these binaries is easy. Simply run:

go get github.com/gogo/protobuf/proto
go get github.com/gogo/protobuf/{binary}
go get github.com/gogo/protobuf/gogoproto

These binaries allow you to use gogoprotobuf extensions. You can also use your own binary.

To generate the code, you also need to set the include path properly.

protoc -I=. -I=$GOPATH/src -I=$GOPATH/src/github.com/gogo/protobuf/protobuf --{binary}_out=. myproto.proto

To use proto files from "google/protobuf" you need to add additional args to protoc.

protoc -I=. -I=$GOPATH/src -I=$GOPATH/src/github.com/gogo/protobuf/protobuf --{binary}_out=\
Mgoogle/protobuf/any.proto=github.com/gogo/protobuf/types,\
Mgoogle/protobuf/duration.proto=github.com/gogo/protobuf/types,\
Mgoogle/protobuf/struct.proto=github.com/gogo/protobuf/types,\
Mgoogle/protobuf/timestamp.proto=github.com/gogo/protobuf/types,\
Mgoogle/protobuf/wrappers.proto=github.com/gogo/protobuf/types:. \
myproto.proto

Note that in the protoc command, {binary} does not contain the initial prefix of "protoc-gen".

Most Speed and most customization

Customizing the fields of the messages to be the fields that you actually want to use removes the need to copy between the structs you use and structs you use to serialize. gogoprotobuf also offers more serialization formats and generation of tests and even more methods.

Please visit the extensions page for more documentation.

Install protoc-gen-gogo:

go get github.com/gogo/protobuf/proto
go get github.com/gogo/protobuf/jsonpb
go get github.com/gogo/protobuf/protoc-gen-gogo
go get github.com/gogo/protobuf/gogoproto

GRPC

It works the same as golang/protobuf, simply specify the plugin. Here is an example using gofast:

protoc --gofast_out=plugins=grpc:. my.proto

See https://github.com/gogo/grpc-example for an example of using gRPC with gogoprotobuf and the wider grpc-ecosystem.

License

This software is licensed under the 3-Clause BSD License ("BSD License 2.0", "Revised BSD License", "New BSD License", or "Modified BSD License").

Expand ▾ Collapse ▴

Directories

Path Synopsis
codec
conformance conformance implements the conformance test subprocess protocol as documented in conformance.proto.
conformance/internal/conformance_proto
gogoproto Package gogoproto provides extensions for protocol buffers to achieve: - fast marshalling and unmarshalling.
gogoreplace
io
jsonpb Package jsonpb provides marshaling and unmarshaling between protocol buffers and JSON.
jsonpb/jsonpb_test_proto
plugin/compare
plugin/defaultcheck The defaultcheck plugin is used to check whether nullable is not used incorrectly.
plugin/description The description (experimental) plugin generates a Description method for each message.
plugin/embedcheck The embedcheck plugin is used to check whether embed is not used incorrectly.
plugin/enumstringer The enumstringer (experimental) plugin generates a String method for each enum.
plugin/equal The equal plugin generates an Equal and a VerboseEqual method for each message.
plugin/face The face plugin generates a function will be generated which can convert a structure which satisfies an interface (face) to the specified structure.
plugin/gostring The gostring plugin generates a GoString method for each message.
plugin/marshalto The marshalto plugin generates a Marshal and MarshalTo method for each message.
plugin/oneofcheck The oneofcheck plugin is used to check whether oneof is not used incorrectly.
plugin/populate The populate plugin generates a NewPopulated function.
plugin/size The size plugin generates a Size or ProtoSize method for each message.
plugin/stringer The stringer plugin generates a String method for each message.
plugin/testgen The testgen plugin generates Test and Benchmark functions for each message.
plugin/union The onlyone plugin generates code for the onlyone extension.
plugin/unmarshal The unmarshal plugin generates a Unmarshal method for each message.
proto Package proto converts data structures to and from the wire format of protocol buffers.
proto/proto3_proto
proto/test_proto
protoc-gen-combo
protoc-gen-gofast
protoc-gen-gogo/descriptor Package descriptor provides functions for obtaining protocol buffer descriptors for generated Go types.
protoc-gen-gogo/generator The code generator for the plugin for the Google protocol buffer compiler.
protoc-gen-gogo/generator/internal/remap Package remap handles tracking the locations of Go tokens in a source text across a rewrite by the Go formatter.
protoc-gen-gogo/grpc Package grpc outputs gRPC service descriptions in Go code.
protoc-gen-gogo/plugin
protoc-gen-gogofast
protoc-gen-gogofaster
protoc-gen-gogoslick
protoc-gen-gogotypes
protoc-gen-gostring
protoc-min-version
sortkeys
test
test/asymetric-issue125
test/cachedsize
test/casttype
test/casttype/combos/both
test/casttype/combos/marshaler
test/casttype/combos/neither
test/casttype/combos/unmarshaler
test/castvalue
test/castvalue/combos/both
test/castvalue/combos/marshaler
test/castvalue/combos/unmarshaler
test/combos/both
test/combos/marshaler
test/combos/unmarshaler
test/custom Package custom contains custom types for test and example purposes.
test/custom-dash-type Package custom contains custom types for test and example purposes.
test/custombytesnonstruct
test/dashfilename
test/data
test/defaultconflict
test/deterministic
test/embedconflict
test/empty-issue70
test/enumcustomname
test/enumdecl
test/enumdecl_all
test/enumprefix
test/enumstringer
test/example
test/filedotname
test/fuzztests
test/group
test/importcustom-issue389/imported
test/importcustom-issue389/importing
test/importdedup
test/importdedup/subpkg
test/importduplicate
test/importduplicate/proto
test/importduplicate/sortkeys
test/indeximport-issue72
test/indeximport-issue72/index
test/int64support
test/issue260
test/issue261
test/issue262
test/issue270
test/issue312
test/issue312/events
test/issue322
test/issue330
test/issue34
test/issue411
test/issue42order
test/issue435
test/issue438
test/issue444
test/issue449
test/issue498
test/issue503
test/issue530
test/issue617
test/issue620
test/issue630
test/issue8
test/jsonpb-gogo
test/mapdefaults Package mapdefaults is a generated protocol buffer package.
test/mapdefaults/combos/both
test/mapdefaults/combos/marshaler
test/mapdefaults/combos/neither
test/mapdefaults/combos/unmarshaler
test/mapsproto2
test/mapsproto2/combos/both
test/mapsproto2/combos/marshaler
test/mapsproto2/combos/neither
test/mapsproto2/combos/unmarshaler
test/merge
test/mixbench
test/moredefaults
test/nopackage
test/oneof
test/oneof/combos/both
test/oneof/combos/marshaler
test/oneof/combos/neither
test/oneof/combos/unmarshaler
test/oneof3
test/oneof3/combos/both
test/oneof3/combos/marshaler
test/oneof3/combos/neither
test/oneof3/combos/unmarshaler
test/oneofembed
test/packed
test/proto3extension
test/protobuffer
test/protosize
test/required
test/setextensionbytes
test/sizerconflict
test/sizeunderscore
test/stdtypes
test/tags
test/theproto3
test/theproto3/combos/both
test/theproto3/combos/marshaler
test/theproto3/combos/neither
test/theproto3/combos/unmarshaler
test/typedecl
test/typedecl_all
test/typedeclimport Package typedeclimport is a generated protocol buffer package.
test/typedeclimport/subpkg Package subpkg is a generated protocol buffer package.
test/types/combos/both
test/types/combos/marshaler
test/types/combos/neither
test/types/combos/unmarshaler
test/unmarshalmerge
test/unrecognized
test/unrecognizedgroup
test/xxxfields
types Package types contains code for interacting with well-known types.
vanity
vanity/command
vanity/test
vanity/test/fast
vanity/test/faster
vanity/test/slick
version