Crate informalsystems_prost_build

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.

Structs

• Comments
  Comments on a Protobuf item.
• Config
  Configuration options for Protobuf code generation.
• Method
  A service method descriptor.
• Service
  A service descriptor.

Traits

• ServiceGenerator
  A service generator takes a service descriptor and generates Rust code.

Functions

• compile_protos
  Compile .proto files into Rust files during a Cargo build.
• protoc
  Returns the path to the protoc binary.
• protoc_include
  Returns the path to the Protobuf include directory.