Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/stefandanaita/grpc-build

Easy gRPC compilation for Rust
https://github.com/stefandanaita/grpc-build

grpc protobuf rpc rust rust-lang rust-library

Last synced: 3 days ago
JSON representation

Easy gRPC compilation for Rust

Awesome Lists containing this project

README 

        
# grpc-build



`grpc-build` provides an flexible way to manage protobuf files and generate the gRPC code required by [tonic](https://github.com/hyperium/tonic).



It is built on top of [tonic_build](https://github.com/hyperium/tonic/tree/master/tonic-build) and it extends its functionality by compiling all the protobuf files inside a directory.

In addition to that, this library adds another feature: full proto name annotation.

This could be useful in cases where you want use the full name (package + message name) to identify a protobuf message.

Therefore, for each top-level protobuf message this library adds a method to its generated struct returning its full proto name.



Given the following protobuf definition:

```protobuf

// my_message.proto

package grpc_build;

message Message {}

```



The library will generate the standard Rust code plus the extra impl for each message.



```rust

// Message.rs (generated)

struct Message {}



impl NamedMessage for Message {

    /// This returns package (grpc-build) + message name (Message).

    const NAME: &'static str = "grpc_build.MyMessage"

}

```



If the protobuf content is valid (worth [linting it](https://buf.build/docs/tour-4)), `grpc-build` will take care of the protobuf imports and it will also generate the `mod.rs` file to allow the compiler to find the generated code. This file will be placed inside the *output directory*.



It comes both as a library that can be used directly inside a project and as a binary that can be used in CI pipelines.



[Documentation](https://docs.rs/grpc-build) - [Crates.io](https://crates.io/crates/grpc-build)



## Getting started



### Using it as a binary

Get the [latest binary release](https://github.com/stefandanaita/grpc-build/releases) and use it inside your CI pipeline.



```

grpc-build build --in-dir="" --out-dir=""

```



Depending on the requirements, you can generate the gRPC Client and/or Server by using the `--build-client` (`-c`) and `--build-server` (`-s`) flags.



To overwrite the contents of the output directory, use the `--force` (`-f`) flag.



```

// both client and server, overwriting the existing protogen

grpc-build build -c -s --in-dir="" --out-dir="" -f

```



### Using it as a library



The most convenient way of using `grpc_build` as a library is by taking advantage of Rust's `build.rs` file. Don't forget to add `grpc_build` to the [build-dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies) list.



```rust

// build.rs

use grpc_build::Builder;



fn main() {

    Builder::new()

        .build_client(true)

        .build_server(true)

        .force(true)

        .out_dir("src/protogen")

        .build("protos")

        .unwrap();

}

```



If you want to set advanced compilation options (like an additional `#[derive]` for the generated types), use the `build_with_config` function, which exposes the underlying [`tonic_build::Builder`](https://docs.rs/tonic-build/0.5.0/tonic_build/struct.Builder.html).



A more advanced usage is to use the `get_protos` and `refactor` functions yourself. The following example does almost the same as the example above, except you don't get the `NamedMessage` traits auto derived



```rust

fn main() {

    let proto_src_dir = "protos";

    let proto_out_dir = "src/protogen";



    let protos: Vec<_> = crate::base::get_protos(proto_src_dir).collect();



    grpc_build::prepare_out_dir(proto_out_dir).unwrap();



    tonic_build::configure()

        .out_dir(proto_out_dir)

        .build_server(true)

        .build_client(true)

        .compile(&protos, &["."])

        .unwrap();



    grpc_build::refactor(proto_out_dir).unwrap();

}

```



## License

This project is licensed under the [MIT license](https://github.com/stefandanaita/grpc-build/blob/master/LICENSE).