Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(tonic-build): try to improve the doc-diff between tonic-build's lib.rs and Readme #2035

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs(tonic-build): try to improve the doc-diff between tonic-build's lib.rs and Readme #2035

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 36 additions & 8 deletions tonic-build/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -15,19 +24,20 @@ prost = "<prost-version>"
tonic-build = "<tonic-version>"
```

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

You can rely on the defaults via

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

### Configuration
Or configure the generated code deeper via

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
Expand All @@ -40,20 +50,37 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
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
Expand All @@ -68,7 +95,8 @@ 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`
Then we can generate Rust code via this setup in our `build.rs`:

```rust
fn main() {
tonic_build::configure()
Expand Down
63 changes: 1 addition & 62 deletions tonic-build/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 = <tonic-version>
//! prost = <prost-version>
//!
//! [build-dependencies]
//! tonic-build = <tonic-version>
//! ```
//!
//! # Examples
//! Simple
//!
//! ```rust,no_run
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//! tonic_build::compile_protos("proto/service.proto")?;
//! Ok(())
//! }
//! ```
//!
//! Configuration
//!
//! ```rust,no_run
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//! 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"]
#![warn(
missing_debug_implementations,
Expand Down Expand Up @@ -173,9 +112,9 @@
impl Attributes {
fn for_mod(&self, name: &str) -> Vec<syn::Attribute> {
generate_attributes(name, &self.module)
}

Check failure on line 115 in tonic-build/src/lib.rs

View workflow job for this annotation

GitHub Actions / test (macOS-latest) 

failed to resolve: use of undeclared crate or module `tonic`

fn for_struct(&self, name: &str) -> Vec<syn::Attribute> {

Check failure on line 117 in tonic-build/src/lib.rs

View workflow job for this annotation

GitHub Actions / test (macOS-latest) 

unresolved imports `api::publisher_client`, `api::ListTopicsRequest`
generate_attributes(name, &self.structure)
}

Expand All @@ -186,7 +125,7 @@
/// ```
/// # use tonic_build::*;
/// let mut attributes = Attributes::default();
/// attributes.push_mod("my.proto.package", r#"#[cfg(feature = "server")]"#);

Check failure on line 128 in tonic-build/src/lib.rs

View workflow job for this annotation

GitHub Actions / test (macOS-latest) 

couldn't read tonic-build/src/google/google.pubsub.v1.rs: No such file or directory (os error 2)
/// ```
pub fn push_mod(&mut self, pattern: impl Into<String>, attr: impl Into<String>) {
self.module.push((pattern.into(), attr.into()));
Expand Down
Loading