diff --git a/tonic-build/README.md b/tonic-build/README.md index 462d4d515..ab67deccc 100644 --- a/tonic-build/README.md +++ b/tonic-build/README.md @@ -2,6 +2,15 @@ Compiles proto files via prost and generates service stubs and proto definitions 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. + The `prost` feature must be enabled to use this feature. +- `prost`: Enables usage of prost generator (enabled by default). +- `transport`: Enables generation of `connect` method using `tonic::transport::Channel` + (enabled by default). + ## Features Required dependencies @@ -15,21 +24,22 @@ prost = "" tonic-build = "" ``` -## Examples +## Getting Started -### Simple +`tonic-build` works by being included as a [`build.rs` file](https://doc.rust-lang.org/cargo/reference/build-scripts.html) at the root of the binary/library. -In `build.rs`: -```rust +You can rely on the defaults via + +```rust,no_run fn main() -> Result<(), Box> { tonic_build::compile_protos("proto/service.proto")?; Ok(()) } ``` -### Configuration +Or configure the generated code deeper via -```rust +```rust,no_run fn main() -> Result<(), Box> { tonic_build::configure() .build_server(false) @@ -40,20 +50,37 @@ fn main() -> Result<(), Box> { Ok(()) } ``` -See [more examples here](https://github.com/hyperium/tonic/tree/master/examples) + +For further details how to use the generated client/server, see the [examples here](https://github.com/hyperium/tonic/tree/master/examples) or the Google APIs example below. + + +## NixOS related hints + +On NixOS, it is better to specify the location of `PROTOC` and `PROTOC_INCLUDE` explicitly. + +```bash +$ 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. ### Google APIs example A good way to use Google API is probably using git submodules. So suppose in our `proto` folder we do: -``` +```bash git submodule add https://github.com/googleapis/googleapis git submodule update --remote ``` And a bunch of Google proto files in structure will be like this: -``` +```raw ├── googleapis │   └── google │   ├── api @@ -68,21 +95,23 @@ And a bunch of Google proto files in structure will be like this: │   └── schema.proto ``` -Then we can generate Rust code via this setup in our `build.rs` -```rust -fn main() { +Then we can generate Rust code via this setup in our `build.rs`: + +```rust,no_run +fn main() -> Result<(), Box> { tonic_build::configure() .build_server(false) //.out_dir("src/google") // you can change the generated code's location .compile_protos( &["proto/googleapis/google/pubsub/v1/pubsub.proto"], &["proto/googleapis"], // specify the root location to search proto dependencies - ).unwrap(); + )?; + Ok(()) } ``` Then you can reference the generated Rust like this this in your code: -```rust +```rust,ignore pub mod api { tonic::include_proto!("google.pubsub.v1"); } @@ -92,7 +121,7 @@ use api::{publisher_client::PublisherClient, ListTopicsRequest}; Or if you want to save the generated code in your own code base, you can uncomment the line `.out_dir(...)` above, and in your lib file config a mod like this: -```rust +```rust,ignore pub mod google { #[path = ""] pub mod pubsub { diff --git a/tonic-build/src/lib.rs b/tonic-build/src/lib.rs index 4a0d2ac7e..fef48637c 100644 --- a/tonic-build/src/lib.rs +++ b/tonic-build/src/lib.rs @@ -1,65 +1,4 @@ -//! `tonic-build` compiles `proto` files via `prost` and generates service stubs -//! and proto definitions 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. The -//! `prost` feature must be enabled to use this feature. -//! - `prost`: Enables usage of prost generator (enabled by default). -//! - `transport`: Enables generation of `connect` method using `tonic::transport::Channel` -//! (enabled by default). -//! -//! # Required dependencies -//! -//! ```toml -//! [dependencies] -//! tonic = -//! prost = -//! -//! [build-dependencies] -//! tonic-build = -//! ``` -//! -//! # Examples -//! Simple -//! -//! ```rust,no_run -//! fn main() -> Result<(), Box> { -//! tonic_build::compile_protos("proto/service.proto")?; -//! Ok(()) -//! } -//! ``` -//! -//! Configuration -//! -//! ```rust,no_run -//! fn main() -> Result<(), Box> { -//! tonic_build::configure() -//! .build_server(false) -//! .compile_protos( -//! &["proto/helloworld/helloworld.proto"], -//! &["proto/helloworld"], -//! )?; -//! Ok(()) -//! } -//!``` -//! -//! ## NixOS related hints -//! -//! On NixOS, it is better to specify the location of `PROTOC` and `PROTOC_INCLUDE` explicitly. -//! -//! ```bash -//! $ 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. - +#![doc = include_str!("../README.md")] #![recursion_limit = "256"] #![doc( html_logo_url = "https://raw.githubusercontent.com/tokio-rs/website/master/public/img/icons/tonic.svg"