From d935ec2d8651dd42483870c22889d3eb4fa3e35f Mon Sep 17 00:00:00 2001 From: Joe Tsai Date: Mon, 24 Feb 2020 14:46:24 -0800 Subject: [PATCH] all: update README.md Change-Id: I60d9ccf1685e2e30327b5a4daf3c65b540c51e88 Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/220679 Reviewed-by: Damien Neil --- README.md | 389 ++++++++++++++++-------------------------------------- 1 file changed, 113 insertions(+), 276 deletions(-) diff --git a/README.md b/README.md index 09e07728e2..4f4302c062 100644 --- a/README.md +++ b/README.md @@ -1,281 +1,118 @@ -# Go support for Protocol Buffers - Google's data interchange format +# Go support for Protocol Buffers +[![GoDev](https://img.shields.io/static/v1?label=godev&message=reference&color=00add8)](https://pkg.go.dev/mod/github.com/golang/protobuf) [![Build Status](https://travis-ci.org/golang/protobuf.svg?branch=master)](https://travis-ci.org/golang/protobuf) -[![GoDoc](https://godoc.org/github.com/golang/protobuf?status.svg)](https://godoc.org/github.com/golang/protobuf) -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.9. - -This software implements Go bindings for protocol buffers. For -information about protocol buffers themselves, see - https://developers.google.com/protocol-buffers/ - -## Installation ## - -To use this software, you must: -- Install the standard C++ implementation of protocol buffers from - https://developers.google.com/protocol-buffers/ -- Of course, install the Go compiler and tools from - https://golang.org/ - See - https://golang.org/doc/install - 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/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. - -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. - - -## Using protocol buffers with 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 --go_out -parameter set to the directory you want to output the Go code to. - - protoc --go_out=. *.proto - -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/golang/protobuf/ptypes/any"; - -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: - -```shell - protoc --go_out=. inputs/x.proto - # writes ./github.com/golang/protobuf/p/x.pb.go -``` - - (This can work well with `--go_out=$GOPATH`.) - -- Relative to the input file: - -```shell -protoc --go_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. - -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: - - - Names are turned from camel_case to CamelCase for export. - - There are no methods on v to set fields; just treat - them as structure fields. - - There are getters that return a field's value if set, - and return the field's default value if unset. - The getters work even if the receiver is a nil message. - - The zero value for a struct is its correct initialization state. - All desired fields must be set before marshaling. - - A Reset() method will restore a protobuf struct to its zero state. - - Non-repeated fields are pointers to the values; nil means unset. - That is, optional or required field int32 f becomes F *int32. - - Repeated fields are slices. - - Helper functions are available to aid the setting of fields. - Helpers for getting values are superseded by the - GetFoo methods and their use is deprecated. - msg.Foo = proto.String("hello") // set field - - Constants are defined to hold the default values of all fields that - have them. They have the form Default_StructName_FieldName. - Because the getter methods handle defaulted values, - direct use of these constants should be rare. - - Enums are given type names and maps from names to values. - Enum values are prefixed with the enum's type name. Enum types have - a String method, and a Enum method to assist in message construction. - - Nested groups and enums have type names prefixed with the name of - the surrounding message type. - - Extensions are given descriptor names that start with E_, - followed by an underscore-delimited list of the nested messages - that contain it (if any) followed by the CamelCased name of the - extension field itself. HasExtension, ClearExtension, GetExtension - and SetExtension are functions for manipulating extensions. - - Oneof field sets are given a single field in their message, - with distinguished wrapper types for each possible field value. - - Marshal and Unmarshal are functions to encode and decode the wire format. - -When the .proto file specifies `syntax="proto3"`, there are some differences: - - - Non-repeated fields of non-message type are values instead of pointers. - - 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; - } -``` - -To create and play with a Test object from the example package, - -```go - package main - - import ( - "log" - - "github.com/golang/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. - } -``` - -## Parameters ## - -To pass extra parameters to the plugin, use a comma-separated -parameter list separated from the output directory by a colon: - - protoc --go_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. - -## gRPC Support ## - -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 --go_out=plugins=grpc:. *.proto - -## Compatibility ## - -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: - -- Security. A security issue in the specification or implementation may come to - light whose resolution requires breaking compatibility. We reserve the right - to address such security issues. -- Unspecified behavior. There are some aspects of the Protocol Buffers - specification that are undefined. Programs that depend on such unspecified - behavior may break in future releases. -- Specification errors or changes. If it becomes necessary to address an - inconsistency, incompleteness, or change in the Protocol Buffers - specification, resolving the issue could affect the meaning or legality of - existing programs. We reserve the right to address such issues, including - updating the implementations. -- Bugs. If the library has a bug that violates the specification, a program - that depends on the buggy behavior may break if the bug is fixed. We reserve - the right to fix such bugs. -- Adding methods or fields to generated structs. These may conflict with field - names that already exist in a schema, causing applications to break. When the - code generator encounters a field in the schema that would collide with a - generated field or method name, the code generator will append an underscore - to the generated field or method name. -- Adding, removing, or changing methods or fields in generated structs that - start with `XXX`. These parts of the generated code are exported out of - necessity, but should not be considered part of the public API. -- Adding, removing, or changing unexported symbols in generated code. +This module +([`github.com/golang/protobuf`](https://pkg.go.dev/mod/github.com/golang/protobuf)) +contains Go bindings for protocol buffers. + +It has been superseded by the +[`google.golang.org/protobuf`](https://pkg.go.dev/mod/google.golang.org/protobuf) +module, which contains an updated and simplified API, +support for protobuf reflection, and many other improvements. +We recommend that new code use the `google.golang.org/protobuf` module. + +Versions v1.4 and later of `github.com/golang/protobuf` are implemented +in terms of `google.golang.org/protobuf`. +Programs which use both modules should use at least version v1.4 of this one. + +See +[release note documentation](https://github.com/golang/protobuf/releases) +for more information about individual releases of this project. + +See +[documentation for the next major revision](https://pkg.go.dev/mod/google.golang.org/protobuf) +for more information about the purpose, usage, and history of this project. + +## Package index + +Summary of the packages provided by this module: + +* [`proto`](https://pkg.go.dev/github.com/golang/protobuf/proto): Package + `proto` provides functions operating on protobuf messages such as cloning, + merging, and checking equality, as well as binary serialization and text + serialization. +* [`jsonpb`](https://pkg.go.dev/github.com/golang/protobuf/jsonpb): Package + `jsonpb` serializes protobuf messages as JSON. +* [`ptypes`](https://pkg.go.dev/github.com/golang/protobuf/ptypes): Package + `ptypes` provides helper functionality for protobuf well-known types. +* [`ptypes/any`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/any): + Package `any` is the generated package for `google/protobuf/any.proto`. +* [`ptypes/empty`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/empty): + Package `empty` is the generated package for `google/protobuf/empty.proto`. +* [`ptypes/timestamp`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/timestamp): + Package `timestamp` is the generated package for + `google/protobuf/timestamp.proto`. +* [`ptypes/duration`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/duration): + Package `duration` is the generated package for + `google/protobuf/duration.proto`. +* [`ptypes/wrappers`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/wrappers): + Package `wrappers` is the generated package for + `google/protobuf/wrappers.proto`. +* [`ptypes/struct`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/struct): + Package `struct` is the generated package for + `google/protobuf/struct.proto`. +* [`protoc-gen-go/descriptor`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/descriptor): + Package `descriptor` is the generated package for + `google/protobuf/descriptor.proto`. +* [`protoc-gen-go/plugin`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/plugin): + Package `plugin` is the generated package for + `google/protobuf/compiler/plugin.proto`. +* [`protoc-gen-go`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go): + The `protoc-gen-go` binary is a protoc plugin to generate a Go protocol + buffer package. + +## Reporting issues + +The issue tracker for this project +[is located here](https://github.com/golang/protobuf/issues). + +Please report any issues with a sufficient description of the bug or feature +request. Bug reports should ideally be accompanied by a minimal reproduction of +the issue. Irreproducible bugs are difficult to diagnose and fix (and likely to +be closed after some period of time). Bug reports must specify the version of +the +[Go protocol buffer module](https://github.com/protocolbuffers/protobuf-go/releases) +and also the version of the +[protocol buffer toolchain](https://github.com/protocolbuffers/protobuf/releases) +being used. + +## Contributing + +This project is open-source and accepts contributions. See the +[contribution guide](https://github.com/golang/protobuf/blob/master/CONTRIBUTING.md) +for more information. + +## Compatibility + +This module 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: + +* **Security:** A security issue in the specification or implementation may + come to light whose resolution requires breaking compatibility. We reserve + the right to address such issues. +* **Unspecified behavior:** There are some aspects of the protocol buffer + specification that are undefined. Programs that depend on unspecified + behavior may break in future releases. +* **Specification changes:** It may become necessary to address an + inconsistency, incompleteness, or change in the protocol buffer + specification, which may affect the behavior of existing programs. We + reserve the right to address such changes. +* **Bugs:** If a package has a bug that violates correctness, a program + depending on the buggy behavior may break if the bug is fixed. We reserve + the right to fix such bugs. +* **Generated additions**: We reserve the right to add new declarations to + generated Go packages of `.proto` files. This includes declared constants, + variables, functions, types, fields in structs, and methods on types. This + may break attempts at injecting additional code on top of what is generated + by `protoc-gen-go`. Such practice is not supported by this project. +* **Internal changes**: We reserve the right to add, modify, and remove + internal code, which includes all unexported declarations, the + [`generator`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/generator) + package, and all packages under + [`internal`](https://pkg.go.dev/github.com/golang/protobuf/internal). 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. +[protobuf@googlegroups.com](https://groups.google.com/forum/#!forum/protobuf).