Documentation ¶
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:
- "config=<filename>": A yaml file that contains configuration for the plugins that protoc-gen-gox will run.
- "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.
- "+<plugin>": Indicates that the named plugin should be run, even if it is not referenced in any given config file.
- "-<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.