Crate prost_build

Expand description

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.

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 no PROTOC environment variable is set then prost-build will search the current path for protoc or protoc.exe. If protoc is not found via these two methods then prost-build will attempt to compile protoc from the bundled source.

If you would not like prost-build to not compile protoc from source ever then ensure you have set PROTOC_NO_VENDOR environment variable as this will disable compiling from source even if the vendored feature flag is enabled.

If you would like to always compile from source then setting the vendored feature flag will force prost-build to always build protoc from source.

If PROTOC_INCLUDE is not found in the environment, then the Protobuf include directory bundled in the prost-build crate is be used.

Compiling `protoc` from source

Compiling protoc from source requires a few external dependencies. Currently, prost-build uses cmake to build protoc. For more information check out the protobuf build instructions.