summaryrefslogtreecommitdiff
path: root/vendor/github.com/gogo/protobuf/README
diff options
context:
space:
mode:
authorValentin Rothberg <rothberg@redhat.com>2019-01-08 14:52:57 +0100
committerValentin Rothberg <rothberg@redhat.com>2019-01-11 13:38:11 +0100
commitbd40dcfc2bc7c9014ea1f33482fb63aacbcdfe87 (patch)
tree5f06e4e289f16d9164d692590a3fe6541b5384cf /vendor/github.com/gogo/protobuf/README
parent545f24421247c9f6251a634764db3f8f8070a812 (diff)
downloadpodman-bd40dcfc2bc7c9014ea1f33482fb63aacbcdfe87.tar.gz
podman-bd40dcfc2bc7c9014ea1f33482fb63aacbcdfe87.tar.bz2
podman-bd40dcfc2bc7c9014ea1f33482fb63aacbcdfe87.zip
vendor: update everything
* If possible, update each dependency to the latest available version. * Use releases over commit IDs and avoid vendoring branches. Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Diffstat (limited to 'vendor/github.com/gogo/protobuf/README')
-rw-r--r--vendor/github.com/gogo/protobuf/README84
1 files changed, 62 insertions, 22 deletions
diff --git a/vendor/github.com/gogo/protobuf/README b/vendor/github.com/gogo/protobuf/README
index 0ad513633..405429a95 100644
--- a/vendor/github.com/gogo/protobuf/README
+++ b/vendor/github.com/gogo/protobuf/README
@@ -1,13 +1,18 @@
-GoGoProtobuf http://github.com/gogo/protobuf extends
+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.
+
+
# Go support for Protocol Buffers
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.4.
+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
@@ -25,7 +30,7 @@ To use this software, you must:
for details or, if you are using gccgo, follow the instructions at
https://golang.org/doc/install/gccgo
- Grab the code from the repository and install the proto package.
- The simplest way is to run `go get -u github.com/golang/protobuf/{proto,protoc-gen-go}`.
+ 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 $GOBIN,
defaulting to $GOPATH/bin. It must be in your $PATH for the protocol
compiler, protoc, to find it.
@@ -58,6 +63,45 @@ parameter set to the directory you want to output the Go code to.
The generated files will be suffixed .pb.go. See the Test code below
for an example using such a file.
+## Packages and input paths ##
+
+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
+ # writes ./github.com/gogo/protobuf/p/x.pb.go
+
+ (This can work well with `--gogo_out=$GOPATH`.)
+
+- Relative to the input file:
+
+ protoc --gogo_out=paths=source_relative:. inputs/x.proto
+ # generate ./inputs/x.pb.go
+
+## Generated code ##
+
The package comment for the proto library contains text describing
the interface provided in Go for protocol buffers. Here is an edited
version.
@@ -118,23 +162,20 @@ for a protocol buffer variable v:
When the .proto file specifies `syntax="proto3"`, there are some differences:
- Non-repeated fields of non-message type are values instead of pointers.
- - Getters are only generated for message and oneof fields.
- Enum types do not get an Enum method.
Consider file test.proto, containing
```proto
+ syntax = "proto2";
package example;
-
+
enum FOO { X = 17; };
-
+
message Test {
required string label = 1;
optional int32 type = 2 [default=77];
repeated int64 reps = 3;
- optional group OptionalGroup = 4 {
- required string RequiredField = 5;
- }
}
```
@@ -151,13 +192,10 @@ To create and play with a Test object from the example package,
)
func main() {
- test := &example.Test {
+ test := &example.Test{
Label: proto.String("hello"),
Type: proto.Int32(17),
Reps: []int64{1, 2, 3},
- Optionalgroup: &example.Test_OptionalGroup {
- RequiredField: proto.String("good bye"),
- },
}
data, err := proto.Marshal(test)
if err != nil {
@@ -185,19 +223,23 @@ parameter list separated from the output directory by a colon:
protoc --gogo_out=plugins=grpc,import_path=mypackage:. *.proto
-
-- `import_prefix=xxx` - a prefix that is added onto the beginning of
- all imports. Useful for things like generating protos in a
- subdirectory, or regenerating vendored protobufs in-place.
-- `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.
+- `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.
+
## gRPC Support ##
If a proto file specifies RPC services, protoc-gen-go can be instructed to
@@ -251,8 +293,6 @@ 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.
-## Plugins ##
-
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.