10 releases
0.4.1 | Aug 22, 2024 |
---|---|
0.4.0 | Feb 14, 2024 |
0.3.0 | Jul 6, 2023 |
0.2.2 | Feb 25, 2023 |
0.0.1 | Mar 26, 2022 |
#489 in Encoding
76,226 downloads per month
Used in 3 crates
(2 directly)
67KB
1.5K
SLoC
protoc-gen-tonic
A protoc
plugin that generates Tonic gRPC server and client code using
the Prost! code generation engine.
When used in projects that use only Rust code, the preferred mechanism for
generating gRPC services with Tonic is to use tonic-build
from
within a build.rs
file. However, when working in polyglot environments,
it can be advantageous to utilize common tooling in the Protocol Buffers
ecosystem. One common tool used for this purpose is buf, which simplifies
the code generation process and includes several useful features, including
linting, package management, and breaking change detection.
Usage
Ensure that protoc-gen-tonic
has been installed within a directory on your
$PATH
. Then invoke protoc
from the command line as follows:
protoc --tonic_out=proto/gen -I proto proto/greeter/v1/greeter.proto
Options
This tool supports all the same options from tonic-build
except for those
that are expected to have been completely handled in an earlier
protoc-gen-prost
step. For information on the effects of these settings,
see the related documentation from tonic-build
:
default_package_filename=<value>
: default_package_filenameextern_path=<proto_path>=<rust_path>
: extern_pathcompile_well_known_types(=<boolean>)
: compile_well_known_typesdisable_package_emission(=<boolean>)
: disable_package_emissionserver_attribute=<proto_path>=<attribute>
: server_attributeserver_mod_attribute=<proto_path>=<attribute>
: server_mod_attributeclient_attribute=<proto_path>=<attribute>
: client_attributeclient_mod_attribute=<proto_path>=<attribute>
: client_mod_attribute
In addition, the following options can also be specified:
no_server(=<boolean>)
: Disables generation of the server modulesno_client(=<boolean>)
: Disables generation of the client modulesno_transport(=<boolean>)
: Disables generation of connect method usingtonic::transport::Channel
no_include(=<boolean>)
: Skips adding an include into the file generated byprotoc-gen-prost
. This behavior may be desired if this plugin is run in a separateprotoc
invocation and you encounter aTried to insert into file that doesn't exist
error.
A note on parameter values:
<attribute>
: All,
s appearing in the value must be\
escaped (i.e.\,
) This is due to the fact that internally,protoc
joins all passed parameters with a,
before sending it as a single string to the underlying plugin.<proto_path>
: Protobuf paths beginning with.
will be matched from the global root (prefix matches). All other paths will be matched as suffix matches.(=<boolean>)
: Boolean values may be specified after a parameter, but if not, the value is assumed to betrue
by virtue of having listed the parameter.
Usage with protoc
and protoc-gen-prost
To make it easier to work with the base definitions generated by prost
,
this plugin assumes that it is being run in a chained mode in the same
protoc
invocation as protoc-gen-prost
. This can be done by specifying
multiple plugins in the same protoc
invocation like so:
protoc -I proto proto/greeter/v1/greeter.proto \
--prost_out=proto/gen \
--tonic_out=proto/gen
When running as separate invocations, protoc
won't be aware of the
base definitions that were generated by protoc-gen-prost
. In this case,
using the no_include
directive is necessary, and you will need to
separately include the generated .tonic.rs
file.
protoc -I proto proto/greeter/v1/greeter.proto \
--prost_out=proto/gen
protoc -I proto proto/greeter/v1/greeter.proto \
--tonic_out=proto/gen \
--tonic_opt=no_include
Usage with buf
When used with buf, options can be specified in the buf.gen.yaml
file.
protoc-gen-prost-tonic
should appear as a plugin step after any
protoc-gen-prost
steps.
version: v1
plugins:
- plugin: prost
out: gen
- plugin: tonic
out: gen
If you have specified compile_well_known_types
or extern_path
on any
earlier step, those should also be specified for this step.
The protoc-gen-tonic
plugin is also published on the Buf Schema Registry as
a plugin which you can execute remotely, without needing to explicitly install
this tool. See the plugin listing to identify the latest published version
for use. The plugin is referenced as follows:
version: v1
plugins:
- plugin: buf.build/community/neoeinstein-tonic:v0.3.0
out: gen
Pulling all of these together, you can compile a ready-made crate for a gRPC service with types that can be JSON serialized using the following example. Then you can depend on this crate from the binary that will host the server or use the client.
version: v1
plugins:
- plugin: prost
out: gen/src
opt:
- compile_well_known_types
- extern_path=.google.protobuf=::pbjson_types
- plugin: prost-serde
out: gen/src
- plugin: tonic
out: gen/src
opt:
- compile_well_known_types
- extern_path=.google.protobuf=::pbjson_types
- plugin: prost
out: gen
opt:
- gen_crate=Cargo.toml.tpl
Dependencies
~8–18MB
~252K SLoC