Crate prost_build

source ·
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.
// It is important to maintain the same structure as in the proto.
pub mod snazzy {
    pub mod items {
        include!(concat!(env!("OUT_DIR"), "/snazzy.items.rs"));
    }
}

use snazzy::items;

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.

Cleaning up Markdown in code docs

If you are using protobuf files from third parties, where the author of the protobuf is not treating comments as Markdown, or is, but has codeblocks in their docs, then you may need to clean up the documentation in order that cargo test --doc will not fail spuriously, and that cargo doc doesn’t attempt to render the codeblocks as Rust code.

To do this, in your Cargo.toml, add features = ["cleanup-markdown"] to the inclusion of the prost-build crate and when your code is generated, the code docs will automatically be cleaned up a bit.

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 for locating protoc. For example, on a macOS system where Protobuf is installed with Homebrew, set the environment variables to:

PROTOC=/usr/local/bin/protoc

and in a typical Linux installation:

PROTOC=/usr/bin/protoc

If no PROTOC environment variable is set then prost-build will search the current path for protoc or protoc.exe. If prost-build can not find protoc via these methods the compile_protos method will fail.

Compiling protoc from source

To compile protoc from source you can use the protobuf-src crate and set the correct environment variables.

ⓘ
std::env::set_var("PROTOC", protobuf_src::protoc());

// Now compile your proto files via prost-build

Structs

  • Comments
    Comments on a Protobuf item.
  • Config
    Configuration options for Protobuf code generation.
  • Method
    A service method descriptor.
  • Module
    A Rust module path for a Protobuf package.
  • Service
    A service descriptor.

Traits

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

Functions