Crate tonic_build

source ·
Expand description

tonic-build compiles proto files via prost and generates service stubs and proto definitiones for use with tonic.

Feature flags

  • cleanup-markdown: Enables cleaning up documentation from the generated code. Useful when documentation of the generated code fails cargo test --doc for example.
  • prost: Enables usage of prost generator (enabled by default).
  • transport: Enables generation of connect method using tonic::transport::Channel (enabled by default).

Required dependencies

[dependencies]
tonic = <tonic-version>
prost = <prost-version>

[build-dependencies]
tonic-build = <tonic-version>

Examples

Simple

fn main() -> Result<(), Box<dyn std::error::Error>> {
    tonic_build::compile_protos("proto/service.proto")?;
    Ok(())
}

Configuration

fn main() -> Result<(), Box<dyn std::error::Error>> {
   tonic_build::configure()
        .build_server(false)
        .compile(
            &["proto/helloworld/helloworld.proto"],
            &["proto/helloworld"],
        )?;
   Ok(())
}

On NixOS, it is better to specify the location of PROTOC and PROTOC_INCLUDE explicitly.

$ export PROTOBUF_LOCATION=$(nix-env -q protobuf --out-path --no-name)
$ export PROTOC=$PROTOBUF_LOCATION/bin/protoc
$ export PROTOC_INCLUDE=$PROTOBUF_LOCATION/include
$ cargo build

The reason being that if prost_build::compile_protos fails to generate the resultant package, the failure is not obvious until the include!(concat!(env!("OUT_DIR"), "/resultant.rs")); fails with No such file or directory error.

Modules

client
Service code generation for client
manual
This module provides utilities for generating tonic service stubs and clients purely in Rust without the need of proto files. It also enables you to set a custom Codec if you want to use a custom serialization format other than protobuf.
server
Service code generation for Server

Structs

Attributes
Attributes that will be added to mod and struct items.
Builder
Service generator builder.
CodeGenBuilder
Builder for the generic code generation of server and clients.

Traits

Method
Method generation trait.
Service
Service generation trait.

Functions

compile_protos
Simple .proto compiling. Use configure instead if you need more options.
configure
Configure tonic-build code generation.