9 releases
0.3.1 | Aug 22, 2024 |
---|---|
0.3.0 | Feb 14, 2024 |
0.2.3 | Mar 1, 2023 |
0.2.1 | Nov 14, 2022 |
0.0.1 | Mar 26, 2022 |
#1271 in Encoding
9,740 downloads per month
Used in haqq-indexer-proto
52KB
918 lines
protoc-gen-prost-serde
A protoc
plugin that generates serde serialization implementations that
follow the conventions of protobuf-JSON.
When used in projects that use only Rust code, the preferred mechanism for
generating protobuf definitions with Prost! is to use prost-build
from
within a build.rs
file and then generate serde implementations using
pbjson-build
. 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-prost-serde
has been installed within a directory
on your $PATH
. Then invoke protoc
from the command line as follows:
protoc --prost-serde_out=proto/gen -I proto proto/greeter/v1/greeter.proto
Options
This tool supports all the same options from pbjson-build
. For more
information on the effects of these settings, see the related documentation
from that crate:
btree_map=<proto_path>
: btree_mapdefault_package_filename=<value>
: default_package_filenameextern_path=<proto_path>=<rust_path>
: extern_pathretain_enum_prefix(=<boolean>)
: retain_enum_prefixpreserve_proto_field_names=(<boolean>)
: preserve_proto_field_namesignore_unknown_fields=(<boolean>)
: ignore_unknown_fieldsemit_fields=(<boolean>)
: emit_fieldsuse_integers_for_enums=(<boolean>)
: use_integers_for_enums
In addition, the following options can also be specified:
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:
<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 \
--prost_opt=compile_well_known_types \
--prost_opt=extern_path=.google.protobuf=::pbjson_types \
--prost-serde_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 .serde.rs
file.
protoc -I proto proto/greeter/v1/greeter.proto \
--prost_out=proto/gen \
--prost_opt=compile_well_known_types \
--prost_opt=extern_path=.google.protobuf=::pbjson_types
protoc -I proto proto/greeter/v1/greeter.proto \
--prost-serde_out=proto/gen \
--prost-serde_opt=no_include
Usage with buf
When used with buf, options can be specified in the buf.gen.yaml
file.
protoc-gen-prost-serde
should appear as a plugin step after any
protoc-gen-prost
steps. In addition, the compile_well_known_types
and extern_path=.google.protobuf=::pbjson_types
options should be specified.
version: v1
plugins:
- plugin: prost
out: gen
opt:
- compile_well_known_types
- extern_path=.google.protobuf=::pbjson_types
- plugin: prost-serde
out: gen
The protoc-gen-prost-serde
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-prost-serde:v0.2.3
out: gen
protoc-gen-prost-serde
is also compatible with the protoc-gen-prost-crate
plugin:
version: v1
plugins:
- plugin: prost
out: gen
opt:
- compile_well_known_types
- extern_path=.google.protobuf=::pbjson_types
- plugin: prost-serde
out: gen
- plugin: prost-crate
strategy: all
out: gen
opt:
- no_features
Dependencies
~7–18MB
~232K SLoC