1 unstable release
0.8.1 | Oct 6, 2021 |
---|
#10 in #prost-build
Used in informalsystems-tonic-bui…
26MB
5.5K
SLoC
Contains (Mach-o exe, 12MB) third-party/protobuf/protoc-osx-x86_64, (ELF exe/lib, 6MB) protoc-linux-aarch_64, (ELF exe/lib, 5MB) third-party/protobuf/protoc-linux-x86_32, (ELF exe/lib, 5MB) third-party/protobuf/protoc-linux-x86_64, (Mach-o exe, 5.5MB) third-party/protobuf/protoc-osx-aarch64, (DOS exe, 2.5MB) third-party/protobuf/protoc-win32.exe
prost-build
prost-build
makes it easy to generate Rust code from .proto
files as part of
a Cargo build. See the crate documentation for examples
of how to integrate prost-build
into a Cargo project.
License
prost-build
is distributed under the terms of the Apache License (Version 2.0).
See LICENSE for details.
Copyright 2017 Dan Burkert
lib.rs
:
prost-build
compiles .proto
files into Rust.
prost-build
is designed to be used for build-time code generation as part of a Cargo
build-script.
Example
Let's create a small crate, snazzy
, that defines a collection of
snazzy new items in a protobuf file.
$ cargo new snazzy && cd snazzy
First, add prost-build
, prost
and its public dependencies to Cargo.toml
(see crates.io for the current versions):
[dependencies]
bytes = <bytes-version>
prost = <prost-version>
[build-dependencies]
prost-build = { version = <prost-version> }
Next, add src/items.proto
to the project:
syntax = "proto3";
package snazzy.items;
// A snazzy new shirt!
message Shirt {
enum Size {
SMALL = 0;
MEDIUM = 1;
LARGE = 2;
}
string color = 1;
Size size = 2;
}
To generate Rust code from items.proto
, we use prost-build
in the crate's
build.rs
build-script:
use std::io::Result;
fn main() -> Result<()> {
prost_build::compile_protos(&["src/items.proto"], &["src/"])?;
Ok(())
}
And finally, in lib.rs
, include the generated code:
// Include the `items` module, which is generated from items.proto.
pub mod items {
include!(concat!(env!("OUT_DIR"), "/snazzy.items.rs"));
}
pub fn create_large_shirt(color: String) -> items::Shirt {
let mut shirt = items::Shirt::default();
shirt.color = color;
shirt.set_size(items::shirt::Size::Large);
shirt
}
That's it! Run cargo doc
to see documentation for the generated code. The full
example project can be found on GitHub.
Sourcing protoc
prost-build
depends on the Protocol Buffers compiler, protoc
, to parse .proto
files into
a representation that can be transformed into Rust. If set, prost-build
uses the PROTOC
and
PROTOC_INCLUDE
environment variables for locating protoc
and the Protobuf includes
directory. For example, on a macOS system where Protobuf is installed with Homebrew, set the
environment to:
PROTOC=/usr/local/bin/protoc
PROTOC_INCLUDE=/usr/local/include
and in a typical Linux installation:
PROTOC=/usr/bin/protoc
PROTOC_INCLUDE=/usr/include
If PROTOC
is not found in the environment, then a pre-compiled protoc
binary bundled in the
prost-build crate is used. Pre-compiled protoc
binaries exist for Linux (non-musl), macOS,
and Windows systems. If no pre-compiled protoc
is available for the host platform, then the
protoc
or protoc.exe
binary on the PATH
is used. If protoc
is not available in any of
these fallback locations, then the build fails.
If PROTOC_INCLUDE
is not found in the environment, then the Protobuf include directory
bundled in the prost-build crate is be used.
To force prost-build
to use the protoc
on the PATH
, add PROTOC=protoc
to the
environment.
Dependencies
~8–18MB
~251K SLoC