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 library crate, snazzy, that defines a collection of snazzy new items in a protobuf file.

$ cargo new --lib snazzy && cd snazzy

First, add prost-build and prost as dependencies to Cargo.toml:

$ cargo add --build prost-build
$ cargo add prost

Next, add src/items.proto to the project:

syntax = "proto3";

package snazzy.items;

// A snazzy new shirt!
message Shirt {
    // Label sizes
    enum Size {
        SMALL = 0;
        MEDIUM = 1;
        LARGE = 2;
    }

    // The base color
    string color = 1;
    // The size as stated on the label
    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;

/// Returns a large shirt of the specified color
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.

§Feature Flags

  • format: Format the generated output. This feature is enabled by default.
  • cleanup-markdown: Clean up Markdown in protobuf docs. Enable this to clean up protobuf files from third parties.

§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.

The easiest way for prost-build to find protoc is to install it in your PATH. This can be done by following the protoc install instructions. prost-build will search the current path for protoc or protoc.exe.

When protoc is installed in a different location, set PROTOC to the path of the executable. 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

Alternatively, the path to protoc execuatable can be explicitly set via Config::protoc_executable().

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§