Crate ntex_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.

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

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

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.