1[GoGo Protobuf looking for new ownership](https://github.com/gogo/protobuf/issues/691) 2 3# Protocol Buffers for Go with Gadgets 4 5[](https://github.com/gogo/protobuf/actions) 6[](http://godoc.org/github.com/gogo/protobuf) 7 8gogoprotobuf is a fork of <a href="https://github.com/golang/protobuf">golang/protobuf</a> with extra code generation features. 9 10This code generation is used to achieve: 11 12 - fast marshalling and unmarshalling 13 - more canonical Go structures 14 - goprotobuf compatibility 15 - less typing by optionally generating extra helper code 16 - peace of mind by optionally generating test and benchmark code 17 - other serialization formats 18 19Keeping track of how up to date gogoprotobuf is relative to golang/protobuf is done in this 20<a href="https://github.com/gogo/protobuf/issues/191">issue</a> 21 22## Release v1.3.0 23 24The 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>. 25 26With 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. 27 28Please 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. 29 30Our upstream repo, golang/protobuf, also had to go through this process in order to update their library version. 31Here is a link explaining <a href="https://github.com/golang/protobuf/issues/763#issuecomment-442434870">hermetic builds</a>. 32 33 34## Users 35 36These projects use gogoprotobuf: 37 38 - <a href="http://godoc.org/github.com/coreos/etcd">etcd</a> - <a href="https://blog.gopheracademy.com/advent-2015/etcd-distributed-key-value-store-with-grpc-http2/">blog</a> - <a href="https://github.com/coreos/etcd/blob/master/etcdserver/etcdserverpb/etcdserver.proto">sample proto file</a> 39 - <a href="https://www.spacemonkey.com/">spacemonkey</a> - <a href="https://www.spacemonkey.com/blog/posts/go-space-monkey">blog</a> 40 - <a href="http://badoo.com">badoo</a> - <a href="https://github.com/badoo/lsd/blob/32061f501c5eca9c76c596d790b450501ba27b2f/proto/lsd.proto">sample proto file</a> 41 - <a href="https://github.com/mesos/mesos-go">mesos-go</a> - <a href="https://github.com/mesos/mesos-go/blob/f9e5fb7c2f50ab5f23299f26b6b07c5d6afdd252/api/v0/mesosproto/authentication.proto">sample proto file</a> 42 - <a href="https://github.com/mozilla-services/heka">heka</a> - <a href="https://github.com/mozilla-services/heka/commit/eb72fbf7d2d28249fbaf8d8dc6607f4eb6f03351">the switch from golang/protobuf to gogo/protobuf when it was still on code.google.com</a> 43 - <a href="https://github.com/cockroachdb/cockroach">cockroachdb</a> - <a href="https://github.com/cockroachdb/cockroach/blob/651d54d393e391a30154e9117ab4b18d9ee6d845/roachpb/metadata.proto">sample proto file</a> 44 - <a href="https://github.com/jbenet/go-ipfs">go-ipfs</a> - <a href="https://github.com/ipfs/go-ipfs/blob/2b6da0c024f28abeb16947fb452787196a6b56a2/merkledag/pb/merkledag.proto">sample proto file</a> 45 - <a href="https://github.com/philhofer/rkive">rkive-go</a> - <a href="https://github.com/philhofer/rkive/blob/e5dd884d3ea07b341321073882ae28aa16dd11be/rpbc/riak_dt.proto">sample proto file</a> 46 - <a href="https://www.dropbox.com">dropbox</a> 47 - <a href="https://srclib.org/">srclib</a> - <a href="https://github.com/sourcegraph/srclib/blob/6538858f0c410cac5c63440317b8d009e889d3fb/graph/def.proto">sample proto file</a> 48 - <a href="http://www.adyoulike.com/">adyoulike</a> 49 - <a href="http://www.cloudfoundry.org/">cloudfoundry</a> - <a href="https://github.com/cloudfoundry/bbs/blob/d673710b8c4211037805129944ee4c5373d6588a/models/events.proto">sample proto file</a> 50 - <a href="http://kubernetes.io/">kubernetes</a> - <a href="https://github.com/kubernetes/kubernetes/tree/88d8628137f94ee816aaa6606ae8cd045dee0bff/cmd/libs/go2idl">go2idl built on top of gogoprotobuf</a> 51 - <a href="https://dgraph.io/">dgraph</a> - <a href="https://github.com/dgraph-io/dgraph/releases/tag/v0.4.3">release notes</a> - <a href="https://discuss.dgraph.io/t/gogoprotobuf-is-extremely-fast/639">benchmarks</a></a> 52 - <a href="https://github.com/centrifugal/centrifugo">centrifugo</a> - <a href="https://forum.golangbridge.org/t/centrifugo-real-time-messaging-websocket-or-sockjs-server-v1-5-0-released/2861">release notes</a> - <a href="https://medium.com/@fzambia/centrifugo-protobuf-inside-json-outside-21d39bdabd68#.o3icmgjqd">blog</a> 53 - <a href="https://github.com/docker/swarmkit">docker swarmkit</a> - <a href="https://github.com/docker/swarmkit/blob/63600e01af3b8da2a0ed1c9fa6e1ae4299d75edb/api/objects.proto">sample proto file</a> 54 - <a href="https://nats.io/">nats.io</a> - <a href="https://github.com/nats-io/go-nats-streaming/blob/master/pb/protocol.proto">go-nats-streaming</a> 55 - <a href="https://github.com/pingcap/tidb">tidb</a> - Communication between <a href="https://github.com/pingcap/tipb/blob/master/generate-go.sh#L4">tidb</a> and <a href="https://github.com/pingcap/kvproto/blob/master/generate_go.sh#L3">tikv</a> 56 - <a href="https://github.com/AsynkronIT/protoactor-go">protoactor-go</a> - <a href="https://github.com/AsynkronIT/protoactor-go/blob/master/protobuf/protoc-gen-protoactor/main.go">vanity command</a> that also generates actors from service definitions 57 - <a href="https://containerd.io/">containerd</a> - <a href="https://github.com/containerd/containerd/tree/master/cmd/protoc-gen-gogoctrd">vanity command with custom field names</a> that conforms to the golang convention. 58 - <a href="https://github.com/heroiclabs/nakama">nakama</a> 59 - <a href="https://github.com/src-d/proteus">proteus</a> 60 - <a href="https://github.com/go-graphite">carbonzipper stack</a> 61 - <a href="https://sendgrid.com/">sendgrid</a> 62 - <a href="https://github.com/zero-os/0-stor">zero-os/0-stor</a> 63 - <a href="https://github.com/spacemeshos/go-spacemesh">go-spacemesh</a> 64 - <a href="https://github.com/weaveworks/cortex">cortex</a> - <a href="https://github.com/weaveworks/cortex/blob/fee02a59729d3771ef888f7bf0fd050e1197c56e/pkg/ingester/client/cortex.proto">sample proto file</a> 65 - <a href="http://skywalking.apache.org/">Apache SkyWalking APM</a> - Istio telemetry receiver based on Mixer bypass protocol 66 - <a href="https://github.com/hyperledger/burrow">Hyperledger Burrow</a> - a permissioned DLT framework 67 - <a href="https://github.com/iov-one/weave">IOV Weave</a> - a blockchain framework - <a href="https://github.com/iov-one/weave/tree/23f9856f1e316f93cb3d45d92c4c6a0c4810f6bf/spec/gogo">sample proto files</a> 68 69Please let us know if you are using gogoprotobuf by posting on our <a href="https://groups.google.com/forum/#!topic/gogoprotobuf/Brw76BxmFpQ">GoogleGroup</a>. 70 71### Mentioned 72 73 - <a href="http://www.slideshare.net/albertstrasheim/serialization-in-go">Cloudflare - go serialization talk - Albert Strasheim</a> 74 - <a href="https://youtu.be/4xB46Xl9O9Q?t=557">GopherCon 2014 Writing High Performance Databases in Go by Ben Johnson</a> 75 - <a href="https://github.com/alecthomas/go_serialization_benchmarks">alecthomas' go serialization benchmarks</a> 76 - <a href="http://agniva.me/go/2017/11/18/gogoproto.html">Go faster with gogoproto - Agniva De Sarker</a> 77 - <a href="https://www.youtube.com/watch?v=CY9T020HLP8">Evolution of protobuf (Gource Visualization) - Landon Wilkins</a> 78 - <a href="https://fosdem.org/2018/schedule/event/gopherjs/">Creating GopherJS Apps with gRPC-Web - Johan Brandhorst</a> 79 - <a href="https://jbrandhorst.com/post/gogoproto/">So you want to use GoGo Protobuf - Johan Brandhorst</a> 80 - <a href="https://jbrandhorst.com/post/grpc-errors/">Advanced gRPC Error Usage - Johan Brandhorst</a> 81 - <a href="https://www.udemy.com/grpc-golang/?couponCode=GITHUB10">gRPC Golang Course on Udemy - Stephane Maarek</a> 82 83## Getting Started 84 85There are several ways to use gogoprotobuf, but for all you need to install go and protoc. 86After that you can choose: 87 88 - Speed 89 - More Speed and more generated code 90 - Most Speed and most customization 91 92### Installation 93 94To 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](http://golang.org/doc/install)). 95Latest patch versions of 1.12 and 1.15 are continuously tested. 96 97Next, install the standard protocol buffer implementation from [https://github.com/google/protobuf](https://github.com/google/protobuf). 98Most versions from 2.3.1 should not give any problems, but 2.6.1, 3.0.2 and 3.14.0 are continuously tested. 99 100### Speed 101 102Install the protoc-gen-gofast binary 103 104 go get github.com/gogo/protobuf/protoc-gen-gofast 105 106Use it to generate faster marshaling and unmarshaling go code for your protocol buffers. 107 108 protoc --gofast_out=. myproto.proto 109 110This does not allow you to use any of the other gogoprotobuf [extensions](https://github.com/gogo/protobuf/blob/master/extensions.md). 111 112### More Speed and more generated code 113 114Fields without pointers cause less time in the garbage collector. 115More code generation results in more convenient methods. 116 117Other binaries are also included: 118 119 protoc-gen-gogofast (same as gofast, but imports gogoprotobuf) 120 protoc-gen-gogofaster (same as gogofast, without XXX_unrecognized, less pointer fields) 121 protoc-gen-gogoslick (same as gogofaster, but with generated string, gostring and equal methods) 122 123Installing any of these binaries is easy. Simply run: 124 125 go get github.com/gogo/protobuf/proto 126 go get github.com/gogo/protobuf/{binary} 127 go get github.com/gogo/protobuf/gogoproto 128 129These binaries allow you to use gogoprotobuf [extensions](https://github.com/gogo/protobuf/blob/master/extensions.md). You can also use your own binary. 130 131To generate the code, you also need to set the include path properly. 132 133 protoc -I=. -I=$GOPATH/src -I=$GOPATH/src/github.com/gogo/protobuf/protobuf --{binary}_out=. myproto.proto 134 135To use proto files from "google/protobuf" you need to add additional args to protoc. 136 137 protoc -I=. -I=$GOPATH/src -I=$GOPATH/src/github.com/gogo/protobuf/protobuf --{binary}_out=\ 138 Mgoogle/protobuf/any.proto=github.com/gogo/protobuf/types,\ 139 Mgoogle/protobuf/duration.proto=github.com/gogo/protobuf/types,\ 140 Mgoogle/protobuf/struct.proto=github.com/gogo/protobuf/types,\ 141 Mgoogle/protobuf/timestamp.proto=github.com/gogo/protobuf/types,\ 142 Mgoogle/protobuf/wrappers.proto=github.com/gogo/protobuf/types:. \ 143 myproto.proto 144 145Note that in the protoc command, {binary} does not contain the initial prefix of "protoc-gen". 146 147### Most Speed and most customization 148 149Customizing 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. 150gogoprotobuf also offers more serialization formats and generation of tests and even more methods. 151 152Please visit the [extensions](https://github.com/gogo/protobuf/blob/master/extensions.md) page for more documentation. 153 154Install protoc-gen-gogo: 155 156 go get github.com/gogo/protobuf/proto 157 go get github.com/gogo/protobuf/jsonpb 158 go get github.com/gogo/protobuf/protoc-gen-gogo 159 go get github.com/gogo/protobuf/gogoproto 160 161## GRPC 162 163It works the same as golang/protobuf, simply specify the plugin. 164Here is an example using gofast: 165 166 protoc --gofast_out=plugins=grpc:. my.proto 167 168See [https://github.com/gogo/grpc-example](https://github.com/gogo/grpc-example) for an example of using gRPC with gogoprotobuf and the wider grpc-ecosystem. 169 170 171## License 172This software is licensed under the 3-Clause BSD License 173("BSD License 2.0", "Revised BSD License", "New BSD License", or "Modified BSD License"). 174 175 176
){kind=link}
){kind=link}