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.