protoc-gen-gox

Overview ¶

Command protoc-gen-gox is a protoc plugin. It is a dispatcher that will run protoc-gen-go as well as other protoc plugins that also generate Go code.

Protoc Arguments ¶

By default, it will just run protoc-gen-go, as if a --go_out parameter had been present on the protoc command-line. Before the output location, you can indicate a config file and also enable or disable particular plugins. These arguments are a comma-separated list, followed by a colon and then the output location:

protoc --gox_out=-go,+foo:./ test.proto

The allowed args are:

1. "config=<filename>": A yaml file that contains configuration for the plugins that protoc-gen-gox will run.
2. "plugin_path=<list>": Indicates a pipe-delimited list of directories where protoc-gen-gox will search for its plugins. If a plugin is not found in this plugin path, the directories in the PATH environment variable will also be searched.
3. "+<plugin>": Indicates that the named plugin should be run, even if it is not referenced in any given config file.
4. "-<plugin>": Indicates that the named plugin should NOT be run. Its configuration in any named config file is ignored. This is the only way to prevent the standard go plugin (protoc-gen-go) from running since it will run under normal circumstances, even without any configuration.

A plugin may be referenced via its full name, such as "protoc-gen-go", or via its short name, such as "go". Furthermore, the actual plugin file/executable is not required to have the "protoc-gen-" prefix.

The plugin name "go-grpc" is a pseudo-plugin. When enabled or disabled, it means to add or remove the "grpc" label from any "plugins" arg for the standard go plugin (protoc-gen-go). You can enable or disable it from the protoc args using a "+go-grpc" or "-go-grpc" arg to the gox plugin. It is not allowed to configure this psuedo-plugin in a config file: configure the standard "go" plugin instead with a "plugins=grpc" argument.

Config File ¶

The config file, optionally indicated by a "config=<filename>" argument, must be a YAML file. Its format is as follows:

# optional list of directories to search for plugins
plugin_path: ["/foo", "/bar", "/baz"]

# optional list of parameters to pass to *every* plugin
common_params: []

# other keys indicate plugin names and their config
plugin_name:
  # optional path to where plugin file resides - can be path to
  # plugin itself or directory that contains plugin
  location: "/foo/bar/plugin_name"
  # optional arguments to supply to this plugin
  params: ["frobnitz=off"]

# other keys can use full name of plugins that follow protoc convention
# (but don't have to: "foobar" could also be used for this one):
protoc-gen-foobar: {} # empty config is fine

Go Plugins ¶

The protoc-gen-gox program can load Go plugins and execute them (instead of forking them as separate executables). If a given protoc plugin binary is compiled as a Go plugin, then it should register itself from an init function using the goxplugin.Register function. The protoc-gen-gox program will then link in the Go plugin at runtime and execute any such plugins that were registered when the plugin binary was initialized. If a given protoc plugin is *not* a Go plugin or fails to register any plugins, it will then be invoked as a standard protoc plugin executable.