Protocol Buffers Data Type Go Code Generation

External

https://protobuf.dev/reference/go/go-generated

Internal

• Protocol Buffer Concepts

Overview

Protocol Buffer files are processed by the Protocol Buffer compiler protoc, which needs the Go plugin protoc-gen-go to generate Go code. The plugin is installed as described in the Installation section below. The protoc command line details are discussed in the Code Generation section.

Installation

The generic compiler must be installed with TODO.

To generate Go code, the Go plugin must be installed with:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

This will install a protoc-gen-go binary in ${GOBIN}.

Code Generation

The compiler requires a mandatory source directory, specified with --proto_path, where it expects the find the .proto Protocol Buffer files, possibly scattered over a directory sub-hierarchy. The Protocol Buffer files are individually specified on the compiler's command line, and their path must be relative to --proto_path.

The compiler creates a single Go source file for each .proto command line-provided input file. The name of the output file is the name of the corresponding .proto file where the .proto extension is replaced with .pb.go. person.proto will generate a person.pb.go Go source file.

The compiler must know Go package's import path for every .proto it processes, including those transitively depended upon by the .proto files being processed. There are two ways to specify the Go package import path:

• By declaring it within the .proto file. This method is recommended and described in detail below.
• By declaring it on the command line when invoking protoc using --go_opt options.

The newly created Go source files will be placed under the root directory specified by --go_out, but where exactly depends on the --go_opt compiler flags, as shown below.

  protoc \
    --proto_path=<protocol-buffer-root-source-directory> \
    --go_out=<protocol-buffer-generated-code-root-directory> \
    [--go_opt=...] \
    <protocol-buffer-file-1>.proto <protocol-buffer-file-1>.proto ...

For more details on a typical Go project layout, see:

Go Project Layout

Example

A typical layout that includes Protocol Buffer files that will generate code in different packages:

...

Declare Package Input Path inside the .proto Files

The Protocol Buffer compiler must know the path of the directory where to place the generated .pb.go file, relative to the --go_out directory. The recommended way to specify this path is to use go_package option inside the .proto file. The value of the go_package option is the path of the directory, relative to the --go_out directory, where the generated file will be placed.

For example:

syntax = "proto3";

option go_package = "./somepkgpb";

message Something { 
  ...
}

compiled with:

protoc ... --go_out=./pkg somefile.proto

will determine the compiler to place the generated somefile.pb.go in ./pkg/somepkgpb. Note that the compiler expects a filesystem path as value of the go_package option, so it expects to see at least one "." or a "/".

The package name for the generated code file will be automatically inferred to be the last path fragment of the path specified with go_package option. In the example above, the package name will be somepkgp.

Package Naming Convention

The package name for the Go source code files generated from .proto files are conventionally suffixed with "pb": somepkgpb.