View source for Protocol Buffers Data Type Go Code Generation

=External=
https://protobuf.dev/reference/go/go-generated
=Internal=
* [[Protocol_Buffer_Concepts#Data_Type_Code_Generation|Protocol Buffer Concepts]]

=Overview=
Protocol Buffer files are processed by the Protocol Buffer compiler <code>protoc</code>, which needs the Go plugin <code>protoc-gen-go</code> to generate Go code. The plugin is installed as described in the [[#Installation|Installation]] section below. The <code>protoc</code> command line details are discussed in the [[#Code_Generation|Code Generation]] section.

=Installation=

The generic compiler must be installed with:
<syntaxhighlight lang='bash'>
brew install protobuf
</syntaxhighlight>

To generate Go code, the Go plugin must be installed with:
<syntaxhighlight lang='bash'>
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
</syntaxhighlight>

This will install a <code>protoc-gen-go</code> binary in <code>${GOBIN}</code>.

=Code Generation=

The compiler requires a mandatory source directory, specified with <code>--proto_path</code>, where it expects the find the <code>.proto</code> 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 paths must be relative to <code>--proto_path</code>.

The compiler creates one single Go source file for each <code>.proto</code> input file. The name of the output file is the name of the corresponding <code>.proto</code> file where the <code>.proto</code> extension is replaced with <code>.pb.go</code>. For example, a <code>person.proto</code> Protocol Buffer file will generate a <code>person.pb.go</code> Go source file.

The compiler must know Go package's [[Go_Packages#Import_Path|import path]] for every <code>.proto</code> it processes, including those transitively depended upon by the <code>.proto</code> files being processed. <font color=darkkhaki>Is the "import path" mentioned here the import path for the generated Go package, or something else? Is there an "import path" concept for the Protocol Buffer files themselves?</font> There are two ways to specify the Go package import path:
* By declaring it within the <code>.proto</code> file with <code>option go_package</code>. This method is recommended and described in detail in the [[#Declare_Package_Input_Path_inside_the_.proto_Files|Declare Package Input Path inside the <tt>.proto</tt> Files]] section.
* By declaring it on the command line when invoking <code>protoc</code> using <code>[[#--go_opt|--go_opt]]</code> options.

The newly created Go source files will be placed somewhere in the root directory specified by <code>--go_out</code>, but where exactly depends on the <code>option go_package</code> setting embedded within the file or on the <code>[[#--go_opt|--go_opt]]</code> compiler flags, as shown below. 
<syntaxhighlight lang='bash'>
  protoc \
    --proto_path=<protocol-buffer-root-source-directory> \
    --go_out=<protocol-buffer-root-generated-code-directory> \
    [--go_opt=...] \
    .../<protocol-buffer-file-1>.proto .../<protocol-buffer-file-1>.proto ...
</syntaxhighlight>

For more details on a typical Go project layout, see: {{Internal|Go_Project#Protocol_Buffer|Go Project Layout}}

=Declare Package Input Path inside the <tt>.proto</tt> Files=

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

<syntaxhighlight lang='protobuf'>
syntax = "proto3";

option go_package = "./somepkgpb";

message Something { 
  ...
}
</syntaxhighlight>

compiled with:
<syntaxhighlight lang='bash'>
protoc ... --go_out=./pkg somefile.proto
</syntaxhighlight>

will make the compiler to place the generated <code>somefile.pb.go</code> in <code>./pkg/somepkgpb</code>. Note that the compiler expects the <code>go_package</code> option value to be a filesystem path, so it expects to see at least a dot (".") or a slash ("/").

The package name for the generated code file will be by default automatically inferred as the '''the last path fragment''' of the path specified with <code>go_package</code> option. In the example above, the package name will be <code>somepkgpb</code>. 
An explicit package name may be specified, by separating the name from the import path by a semicolon (<code>"./somepkgpb;someothername"</code>). However, this usage is discouraged since the package name will be derived by default from the import path in a reasonable manner.

Package names should follow [[#Package_Naming_Convention|Protocol Buffer package name convention]].

=Package Naming Convention=

The package name for the Go source code files generated from <code>.proto</code> files are conventionally suffixed with "pb": <tt>somepkg<b>pb</b></tt>. Even if it not required to use the same name for the enclosing directory, it is good practice if that happens.

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

<font size=-2>
 .
 ├── go.mod
 ├── pkg
 │   ├── main
 │   │    └── main.go
 │   ├── somepkgpb          ┌─────────────────────────────────────────┐ 
 │   │    ├── file1.pb.go  ─┤ package somepkgpb                       │ 
 │   │    └── file2.pb.go   └─────────────────────────────────────────┘
 │   └── someotherpkgpb     ┌─────────────────────────────────────────┐ 
 │        ├── file3.pb.go  ─┤ package someotherpkgpb                  │ 
 │        └── file4.pb.go   └─────────────────────────────────────────┘
 └── protobuf
      ├── somepkgpb         ┌─────────────────────────────────────────┐ 
      │    ├── file1.proto ─┤ option go_package = "./somepkgpb";      │ 
      │    └── file2.proto  └─────────────────────────────────────────┘
      └── someotherpkgpb    ┌─────────────────────────────────────────┐ 
           ├── file3.proto ─┤ option go_package = "./someotherpkgpb"; │ 
           └── file4.proto  └─────────────────────────────────────────┘

</font>

The <code>protoc</code> command is:

<syntaxhighlight lang='bash'>
protoc \
  --proto_path=./protobuf --go_out=./pkg \
  somepkgpb/file1.proto somepkgpb/file2.proto someotherpkgpb/file3.proto someotherpkgpb/file4.proto
</syntaxhighlight>
=Compilation=

Update the necessary dependencies to <code>[[go.mod]]</code> with:

<syntaxhighlight lang='bash'>
go get google.golang.org/protobuf/reflect/protoreflect
</syntaxhighlight>

=The <tt>package</tt> Specifier=

<font color=darkkhaki>
There is no correlation between the Go import path and the <code>package</code> specifier in the <code>.proto</code> file. The latter is only relevant to the protobuf namespace, while the former is only relevant to the Go namespace.
</font>

=<tt>--go_opt</tt>=
==<tt>paths=import</tt>==
<font color=darkkhaki>TODO</font>.
==<tt>paths=source_relative</tt>==
<font color=darkkhaki>TODO</font>.
==<tt>module=${PREFIX}</tt>==
<font color=darkkhaki>TODO</font>.
==<tt>M${PROTO_FILE}=${GO_IMPORT_PATH}</tt>==
<font color=darkkhaki>TODO</font>. Use [[#Declare_Package_Input_Path_inside_the_.proto_Files|Declare Package Input Path inside the <tt>.proto</tt> Files]] instead.