# 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="<protobuf directory>" --out-dir="<codegen>"
```

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="<protobuf directory>" --out-dir="<codegen>" -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).