Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
github.com/gogo/protobuf
Protocol Buffers for Go with Gadgets
GoGoProtobuf http://github.com/gogo/protobuf extends GoProtobuf http://github.com/golang/protobuf
Copyright (c) 2013, The GoGo Authors. All rights reserved.
Google's data interchange format. Copyright 2010 The Go Authors. https://github.com/golang/protobuf
This package and the code it generates requires at least Go 1.6.
This software implements Go bindings for protocol buffers. For information about protocol buffers themselves, see https://developers.google.com/protocol-buffers/
To use this software, you must:
proto
package.
The simplest way is to run go get -u github.com/golang/protobuf/protoc-gen-go
.
The compiler plugin, protoc-gen-go
, will be installed in $GOPATH/bin
unless $GOBIN
is set. It must be in your $PATH
for the protocol
compiler, protoc
, to find it.protoc-gen-go
(e.g., to match your
proto
package version), one option is
GIT_TAG="v1.2.0" # change as needed
go get -d -u github.com/golang/protobuf/protoc-gen-go
git -C "$(go env GOPATH)"/src/github.com/golang/protobuf checkout $GIT_TAG
go install github.com/golang/protobuf/protoc-gen-go
This software has two parts: a 'protocol compiler plugin' that generates Go source files that, once compiled, can access and manage protocol buffers; and a library that implements run-time support for encoding (marshaling), decoding (unmarshaling), and accessing protocol buffers.
There is support for gRPC in Go using protocol buffers. See the note at the bottom of this file for details.
There are no insertion points in the plugin.
GoGoProtobuf provides extensions for protocol buffers and GoProtobuf see http://github.com/gogo/protobuf/gogoproto/doc.go
Once the software is installed, there are two steps to using it. First you must compile the protocol buffer definitions and then import them, with the support library, into your program.
To compile the protocol buffer definition, run protoc with the --gogo_out parameter set to the directory you want to output the Go code to.
protoc --gogo_out=. *.proto
The generated files will be suffixed .pb.go. See the Test code below for an example using such a file.
The protocol buffer language has a concept of "packages" which does not
correspond well to the Go notion of packages. In generated Go code,
each source .proto
file is associated with a single Go package. The
name and import path for this package is specified with the go_package
proto option:
option go_package = "github.com/gogo/protobuf/types";
The protocol buffer compiler will attempt to derive a package name and
import path if a go_package
option is not present, but it is
best to always specify one explicitly.
There is a one-to-one relationship between source .proto
files and
generated .pb.go
files, but any number of .pb.go
files may be
contained in the same Go package.
The output name of a generated file is produced by replacing the
.proto
suffix with .pb.go
(e.g., foo.proto
produces foo.pb.go
).
However, the output directory is selected in one of two ways. Let
us say we have inputs/x.proto
with a go_package
option of
github.com/golang/protobuf/p
. The corresponding output file may
be:
Relative to the import path:
protoc --gogo_out=. inputs/x.proto
(This can work well with --gogo_out=$GOPATH
.)
Relative to the input file:
protoc --gogo_out=paths=source_relative:. inputs/x.proto
The package comment for the proto library contains text describing the interface provided in Go for protocol buffers. Here is an edited version.
If you are using any gogo.proto extensions you will need to specify the proto_path to include the descriptor.proto and gogo.proto. gogo.proto is located in github.com/gogo/protobuf/gogoproto This should be fine, since your import is the same. descriptor.proto is located in either github.com/gogo/protobuf/protobuf or code.google.com/p/protobuf/trunk/src/ Its import is google/protobuf/descriptor.proto so it might need some help.
protoc --gogo_out=. -I=.:github.com/gogo/protobuf/protobuf *.proto
==========
The proto package converts data structures to and from the wire format of protocol buffers. It works in concert with the Go source code generated for .proto files by the protocol compiler.
A summary of the properties of the protocol buffer interface for a protocol buffer variable v:
When the .proto file specifies syntax="proto3"
, there are some differences:
Consider file test.proto, containing
syntax = "proto2";
package example;
enum FOO { X = 17; };
message Test {
required string label = 1;
optional int32 type = 2 [default=77];
repeated int64 reps = 3;
}
To create and play with a Test object from the example package,
package main
import (
"log"
"github.com/gogo/protobuf/proto"
"path/to/example"
)
func main() {
test := &example.Test{
Label: proto.String("hello"),
Type: proto.Int32(17),
Reps: []int64{1, 2, 3},
}
data, err := proto.Marshal(test)
if err != nil {
log.Fatal("marshaling error: ", err)
}
newTest := &example.Test{}
err = proto.Unmarshal(data, newTest)
if err != nil {
log.Fatal("unmarshaling error: ", err)
}
// Now test and newTest contain the same data.
if test.GetLabel() != newTest.GetLabel() {
log.Fatalf("data mismatch %q != %q", test.GetLabel(), newTest.GetLabel())
}
// etc.
}
To pass extra parameters to the plugin, use a comma-separated parameter list separated from the output directory by a colon:
protoc --gogo_out=plugins=grpc,import_path=mypackage:. *.proto
paths=(import | source_relative)
- specifies how the paths of
generated files are structured. See the "Packages and imports paths"
section above. The default is import
.plugins=plugin1+plugin2
- specifies the list of sub-plugins to
load. The only plugin in this repo is grpc
.Mfoo/bar.proto=quux/shme
- declares that foo/bar.proto is
associated with Go package quux/shme. This is subject to the
import_prefix parameter.The following parameters are deprecated and should not be used:
import_prefix=xxx
- a prefix that is added onto the beginning of
all imports.import_path=foo/bar
- used as the package if no input files
declare go_package
. If it contains slashes, everything up to the
rightmost slash is ignored.If a proto file specifies RPC services, protoc-gen-go can be instructed to
generate code compatible with gRPC (http://www.grpc.io/). To do this, pass
the plugins
parameter to protoc-gen-go; the usual way is to insert it into
the --go_out argument to protoc:
protoc --gogo_out=plugins=grpc:. *.proto
The library and the generated code are expected to be stable over time. However, we reserve the right to make breaking changes without notice for the following reasons:
XXX
. These parts of the generated code are exported out of
necessity, but should not be considered part of the public API.Any breaking changes outside of these will be announced 6 months in advance to protobuf@googlegroups.com.
You should, whenever possible, use generated code created by the protoc-gen-go
tool built at the same commit as the proto
package. The proto
package
declares package-level constants in the form ProtoPackageIsVersionX
.
Application code and generated code may depend on one of these constants to
ensure that compilation will fail if the available version of the proto library
is too old. Whenever we make a change to the generated code that requires newer
library support, in the same commit we will increment the version number of the
generated code and declare a new package-level constant whose name incorporates
the latest version number. Removing a compatibility constant is considered a
breaking change and would be subject to the announcement policy stated above.
The protoc-gen-go/generator
package exposes a plugin interface,
which is used by the gRPC code generation. This interface is not
supported and is subject to incompatible changes without notice.
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.