Skip to content

Commit

Permalink
all: update README.md
Browse files Browse the repository at this point in the history 
Change-Id: I60d9ccf1685e2e30327b5a4daf3c65b540c51e88
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/220679
Reviewed-by: Damien Neil <[email protected]>
  • Loading branch information
@dsnet
dsnet committed Feb 28, 2020
1 parent c343881 commit d935ec2
Showing 1 changed file with 113 additions and 276 deletions.
389 changes: 113 additions & 276 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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
[email protected].

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.
[[email protected]](https://groups.google.com/forum/#!forum/protobuf).

0 comments on commit d935ec2

Please sign in to comment.