github.com/gogo/protobuf@v1.3.2/Readme.md (about)

     1  [GoGo Protobuf looking for new ownership](https://github.com/gogo/protobuf/issues/691)
     2  
     3  # Protocol Buffers for Go with Gadgets
     4  
     5  [![Build Status](https://github.com/gogo/protobuf/workflows/Continuous%20Integration/badge.svg)](https://github.com/gogo/protobuf/actions)
     6  [![GoDoc](https://godoc.org/github.com/gogo/protobuf?status.svg)](http://godoc.org/github.com/gogo/protobuf)
     7  
     8  gogoprotobuf is a fork of <a href="https://github.com/golang/protobuf">golang/protobuf</a> with extra code generation features.
     9  
    10  This 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  
    19  Keeping 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  
    24  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>.
    25  
    26  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.
    27  
    28  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.
    29  
    30  Our upstream repo, golang/protobuf, also had to go through this process in order to update their library version.
    31  Here is a link explaining <a href="https://github.com/golang/protobuf/issues/763#issuecomment-442434870">hermetic builds</a>.
    32  
    33  
    34  ## Users
    35  
    36  These 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  
    69  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>.
    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  
    85  There are several ways to use gogoprotobuf, but for all you need to install go and protoc.
    86  After that you can choose:
    87  
    88    - Speed
    89    - More Speed and more generated code
    90    - Most Speed and most customization
    91  
    92  ### Installation
    93  
    94  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](http://golang.org/doc/install)).
    95  Latest patch versions of 1.12 and 1.15 are continuously tested.
    96  
    97  Next, install the standard protocol buffer implementation from [https://github.com/google/protobuf](https://github.com/google/protobuf).
    98  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.
    99  
   100  ### Speed
   101  
   102  Install the protoc-gen-gofast binary
   103  
   104      go get github.com/gogo/protobuf/protoc-gen-gofast
   105  
   106  Use it to generate faster marshaling and unmarshaling go code for your protocol buffers.
   107  
   108      protoc --gofast_out=. myproto.proto
   109  
   110  This 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  
   114  Fields without pointers cause less time in the garbage collector.
   115  More code generation results in more convenient methods.
   116  
   117  Other 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  
   123  Installing 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  
   129  These binaries allow you to use gogoprotobuf [extensions](https://github.com/gogo/protobuf/blob/master/extensions.md). You can also use your own binary.
   130  
   131  To 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  
   135  To 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  
   145  Note that in the protoc command, {binary} does not contain the initial prefix of "protoc-gen".
   146  
   147  ### Most Speed and most customization
   148  
   149  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.
   150  gogoprotobuf also offers more serialization formats and generation of tests and even more methods.
   151  
   152  Please visit the [extensions](https://github.com/gogo/protobuf/blob/master/extensions.md) page for more documentation.
   153  
   154  Install 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  
   163  It works the same as golang/protobuf, simply specify the plugin.
   164  Here is an example using gofast:
   165  
   166      protoc --gofast_out=plugins=grpc:. my.proto
   167  
   168  See [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
   172  This 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