Struct prost_build::Config

pub struct Config { /* fields omitted */ }

Configuration options for Protobuf code generation.

This configuration builder can be used to set non-default code generation options.

Methods

impl Config

pub fn new() -> Config

Creates a new code generator configuration with default options.

pub fn btree_map<I, S>(&mut self, paths: I) -> &mut Self where
    I: IntoIterator<Item = S>,
    S: AsRef<str>, 

Configure the code generator to generate Rust BTreeMap fields for Protobuf map type fields.

Arguments

paths - paths to specific fields, messages, or packages which should use a Rust BTreeMap for Protobuf map fields. Paths are specified in terms of the Protobuf type name (not the generated Rust type name). Paths with a leading . are treated as fully qualified names. Paths without a leading . are treated as relative, and are suffix matched on the fully qualified field name. If a Protobuf map field matches any of the paths, a Rust BTreeMap field is generated instead of the default HashMap.

The matching is done on the Protobuf names, before converting to Rust-friendly casing standards.

Examples

// Match a specific field in a message type.
config.btree_map(&[".my_messages.MyMessageType.my_map_field"]);

// Match all map fields in a message type.
config.btree_map(&[".my_messages.MyMessageType"]);

// Match all map fields in a package.
config.btree_map(&[".my_messages"]);

// Match all map fields.
config.btree_map(&["."]);

// Match all map fields in a nested message.
config.btree_map(&[".my_messages.MyMessageType.MyNestedMessageType"]);

// Match all fields named 'my_map_field'.
config.btree_map(&["my_map_field"]);

// Match all fields named 'my_map_field' in messages named 'MyMessageType', regardless of
// package or nesting.
config.btree_map(&["MyMessageType.my_map_field"]);

// Match all fields named 'my_map_field', and all fields in the 'foo.bar' package.
config.btree_map(&["my_map_field", ".foo.bar"]);

pub fn field_attribute<P, A>(&mut self, path: P, attribute: A) -> &mut Self where
    P: AsRef<str>,
    A: AsRef<str>, 

Add additional attribute to matched fields.

Arguments

path - a patch matching any number of fields. These fields get the attribute. For details about matching fields see btree_map.

attribute - an arbitrary string that'll be placed before each matched field. The expected usage are additional attributes, usually in concert with whole-type attributes set with type_attribute, but it is not checked and anything can be put there.

Note that the calls to this method are cumulative ‒ if multiple paths from multiple calls match the same field, the field gets all the corresponding attributes.

Examples

// Prost renames fields named `in` to `in_`. But if serialized through serde,
// they should as `in`.
config.field_attribute("in", "#[serde(rename = \"in\")]");

pub fn type_attribute<P, A>(&mut self, path: P, attribute: A) -> &mut Self where
    P: AsRef<str>,
    A: AsRef<str>, 

Add additional attribute to matched messages, enums and one-ofs.

Arguments

paths - a path matching any number of types. It works the same way as in btree_map, just with the field name omitted.

attribute - an arbitrary string to be placed before each matched type. The expected usage are additional attributes, but anything is allowed.

The calls to this method are cumulative. They don't overwrite previous calls and if a type is matched by multiple calls of the method, all relevant attributes are added to it.

For things like serde it might be needed to combine with field attributes.

Examples

// Nothing around uses floats, so we can derive real `Eq` in addition to `PartialEq`.
config.type_attribute(".", "#[derive(Eq)]");
// Some messages want to be serializable with serde as well.
config.type_attribute("my_messages.MyMessageType",
                      "#[derive(Serialize)] #[serde(rename-all = \"snake_case\")]");
config.type_attribute("my_messages.MyMessageType.MyNestedMessageType",
                      "#[derive(Serialize)] #[serde(rename-all = \"snake_case\")]");

Oneof fields

The oneof fields don't have a type name of their own inside Protobuf. Therefore, the field name can be used both with type_attribute and field_attribute ‒ the first is placed before the enum type definition, the other before the field inside corresponding message struct.

In other words, to place an attribute on the enum implementing the oneof, the match would look like my_messages.MyMessageType.oneofname.

pub fn service_generator(
    &mut self,
    service_generator: Box<dyn ServiceGenerator>
) -> &mut Self

Configures the code generator to use the provided service generator.

pub fn compile_well_known_types(&mut self) -> &mut Self

Configures the code generator to not use the prost_types crate for Protobuf well-known types, and instead generate Protobuf well-known types from their .proto definitions.

pub fn extern_path<P1, P2>(
    &mut self,
    proto_path: P1,
    rust_path: P2
) -> &mut Self where
    P1: Into<String>,
    P2: Into<String>, 

Declare an externally provided Protobuf package or type.

extern_path allows prost types in external crates to be referenced in generated code.

When prost compiles a .proto which includes an import of another .proto, it will automatically recursively compile the imported file as well. extern_path can be used to instead substitute types from an external crate.

Example

As an example, consider a crate, uuid, with a prost-generated Uuid type:

// uuid.proto

syntax = "proto3";
package uuid;

message Uuid {
    string uuid_str = 1;
}

The uuid crate implements some traits for Uuid, and publicly exports it:

// lib.rs in the uuid crate

include!(concat!(env!("OUT_DIR"), "/uuid.rs"));

pub trait DoSomething {
    fn do_it(&self);
}

impl DoSomething for Uuid {
    fn do_it(&self) {
        println!("Done");
    }
}

A separate crate, my_application, uses prost to generate message types which reference Uuid:

// my_application.proto

syntax = "proto3";
package my_application;

import "uuid.proto";

message MyMessage {
    uuid.Uuid message_id = 1;
    string some_payload = 2;
}

Additionally, my_application depends on the trait impls provided by the uuid crate:

// `main.rs` of `my_application`

use uuid::{DoSomething, Uuid};

include!(concat!(env!("OUT_DIR"), "/my_application.rs"));

pub fn process_message(msg: MyMessage) {
    if let Some(uuid) = msg.message_id {
        uuid.do_it();
    }
}

Without configuring uuid as an external path in my_application's build.rs, prost would compile a completely separate version of the Uuid type, and process_message would fail to compile. However, if my_application configures uuid as an extern path with a call to .extern_path(".uuid", "::uuid"), prost will use the external type instead of compiling a new version of Uuid. Note that the configuration could also be specified as .extern_path(".uuid.Uuid", "::uuid::Uuid") if only the Uuid type were externally provided, and not the whole uuid package.

Usage

extern_path takes a fully-qualified Protobuf path, and the corresponding Rust path that it will be substituted with in generated code. The Protobuf path can refer to a package or a type, and the Rust path should correspondingly refer to a Rust module or type.

// Declare the `uuid` Protobuf package and all nested packages and types as externally
// provided by the `uuid` crate.
config.extern_path(".uuid", "::uuid");

// Declare the `foo.bar.baz` Protobuf package and all nested packages and types as
// externally provided by the `foo_bar_baz` crate.
config.extern_path(".foo.bar.baz", "::foo_bar_baz");

// Declare the `uuid.Uuid` Protobuf type (and all nested types) as externally provided
// by the `uuid` crate's `Uuid` type.
config.extern_path(".uuid.Uuid", "::uuid::Uuid");

pub fn retain_enum_prefix(&mut self) -> &mut Self

Configures the code generator to not strip the enum name from variant names.

Protobuf enum definitions commonly include the enum name as a prefix of every variant name. This style is non-idiomatic in Rust, so by default prost strips the enum name prefix from variants which include it. Configuring this option prevents prost from stripping the prefix.

pub fn out_dir<P>(&mut self, path: P) -> &mut Self where
    P: Into<PathBuf>, 

Configures the output directory where generated Rust files will be written.

If unset, defaults to the OUT_DIR environment variable. OUT_DIR is set by Cargo when executing build scripts, so out_dir typically does not need to be configured.

pub fn compile_protos<P>(&mut self, protos: &[P], includes: &[P]) -> Result<()> where
    P: AsRef<Path>, 

Compile .proto files into Rust files during a Cargo build with additional code generator configuration options.

This method is like the prost_build::compile_protos function, with the added ability to specify non-default code generation options. See that function for more information about the arguments and generated outputs.

Example build.rs

fn main() {
    let mut prost_build = prost_build::Config::new();
    prost_build.btree_map(&["."]);
    prost_build.compile_protos(&["src/frontend.proto", "src/backend.proto"],
                               &["src"]).unwrap();
}

Trait Implementations

impl Default for Config

fn default() -> Config

Returns the "default value" for a type.