Home

Awesome

GoGo Protobuf is Deprecated

[Deprecated] Protocol Buffers for Go with Gadgets

<a href="https://www.youtube.com/watch?v=HTIltI0NuNg&list=PLYwF9EIrl42T3ml_ANaNifOuTQtLxaZgQ&index=3" target="_blank"> <img src="https://img.youtube.com/vi/HTIltI0NuNg/maxres1.jpg" alt="Watch the video" width="480" border="10" /> </a>

Build Status GoDoc

gogoprotobuf is a fork of <a href="https://github.com/golang/protobuf">golang/protobuf</a> with extra code generation features.

This code generation is used to achieve:

Keeping track of how up to date gogoprotobuf is relative to golang/protobuf is done in this <a href="https://github.com/gogo/protobuf/issues/191">issue</a>

Release v1.3.0

The project has updated to release v1.3.0. Check out the release notes <a href="https://github.com/gogo/protobuf/releases/tag/v1.3.0">here</a>.

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 <a href="https://github.com/golang/protobuf/issues/763#issuecomment-442434870">hermetic builds</a>.

Users

These projects use gogoprotobuf:

Please let us know if you are using gogoprotobuf by posting on our <a href="https://groups.google.com/forum/#!topic/gogoprotobuf/Brw76BxmFpQ">GoogleGroup</a>.

Mentioned

Preparing for GopherCon UK 2022

<a href="https://www.youtube.com/watch?v=8kL7_KTsIoc" target="_blank"> <img src="https://img.youtube.com/vi/8kL7_KTsIoc/maxres3.jpg" alt="Preparing for GopherCon UK 2022 video" width="480" border="10" /> </a>

Getting Started

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

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.12 and 1.15 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.14.0 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").