78 stable releases
3.7.1 | Oct 15, 2024 |
---|---|
3.5.1 | Aug 19, 2024 |
3.5.0 | Jun 26, 2024 |
3.4.0 | Feb 26, 2024 |
1.6.0 | May 11, 2018 |
#87 in Encoding
506,887 downloads per month
Used in 401 crates
(94 directly)
2MB
40K
SLoC
Protobuf code generator for protobuf
crate
This crate is useful mostly from build.rs
scripts to generate .rs
files during the build.
How to generate code
There are three main ways to generate .rs
files from .proto
files:
- using
protoc
command line tool andprotoc-gen-rs
plugin - using this crate
Codegen
with pure rust parser - using this crate
Codegen
withprotoc
parser
Which one should you use depends on your needs.
If you are using non-cargo build system (like Bazel), you might prefer
using protoc-gen-rs
plugin for protoc
.
If you build with cargo
, you probably want to use Codegen
from this crate.
Protoc parser vs pure rust parser
There are two protobuf parsers which can be plugged into this crate:
protoc
-based parser (protoc
is a command like utility from Google protobuf)- pure rust parser (
protobuf-parse
crate)
protoc
-based parser is expected to parse .proto
files very correctly:
all Google's protobuf implementations rely on it.
While there are no known bugs in protobuf-parse
, it is not tested very well.
Also protobuf-parse
does not implement certain rarely used features of .proto
parser,
mostly complex message options specified in .proto
files.
I never saw anyone using them, but you have been warned.
Note protoc
command can be obtained from
protoc-bin-vendored
crate.
Example
// Use this in build.rs
protobuf_codegen::Codegen::new()
// Use `protoc` parser, optional.
.protoc()
// Use `protoc-bin-vendored` bundled protoc command, optional.
.protoc_path(&protoc_bin_vendored::protoc_bin_path().unwrap())
// All inputs and imports from the inputs must reside in `includes` directories.
.includes(&["src/protos"])
// Inputs must reside in some of include paths.
.input("src/protos/apple.proto")
.input("src/protos/banana.proto")
// Specify output directory relative to Cargo output directory.
.cargo_out_dir("protos")
.run_from_script();
How to use protoc-gen-rs
If you have to.
(Note protoc
can be invoked programmatically with
protoc crate)
- Install protobuf for
protoc
binary.
On OS X Homebrew can be used:
brew install protobuf
On Ubuntu, protobuf-compiler
package can be installed:
apt-get install protobuf-compiler
Protobuf is needed only for code generation, rust-protobuf
runtime
does not use C++ protobuf library.
- Install
protoc-gen-rs
program (which isprotoc
plugin)
It can be installed either from source or with cargo install protobuf-codegen
command.
- Add
protoc-gen-rs
to $PATH
If you installed it with cargo, it should be
PATH="$HOME/.cargo/bin:$PATH"
- Generate .rs files:
protoc --rs_out . foo.proto
This will generate .rs files in current directory.
Customize generate code
Sometimes generated code need to be adjusted, e. g. to have custom derives.
rust-protobuf provides two options to do that:
- generated
.rs
files contain@@protoc_insertion_point(...)
markers (similar markers inserts Google's protobuf generator for C++ or Java). Simple scriptsed
one-liners can be used to replace these markers with custom annotations. Codegen::customize_callback
can be used to patch generated code when invoked frombuild.rs
script.
Serde
rust-protobuf since version 3 no longer directly supports serde.
Rust-protobuf 3 fully supports:
- runtime reflection
- JSON parsing and printing via
protobuf-json-mapping
Which covers the most of serde use cases.
If you still need serde, generic customization callback (see above) can be used
to insert #[serde(...)]
annotations.
Example project in the rust-protobuf repository demonstrates how to do it.
Dependencies
~5–15MB
~203K SLoC