mirror of https://github.com/bazelbuild/rules_rust
241 lines
7.9 KiB
Plaintext
241 lines
7.9 KiB
Plaintext
#[[
|
|
## Overview
|
|
These build rules are used for building [protobufs][protobuf]/[gRPC][grpc] in [Rust][rust] with Bazel.
|
|
|
|
There are two rule sets. The first ruleset defines the `rust_prost_library` which generates Rust code
|
|
using the [`prost`] and [`tonic`] dependencies. The second ruleset defines the `rust_proto_library` and
|
|
`rust_grpc_library` rules which generate Rust code using the [`rust-protobuf`] dependencies.
|
|
|
|
[rust]: http://www.rust-lang.org/
|
|
[protobuf]: https://developers.google.com/protocol-buffers/
|
|
[grpc]: https://grpc.io
|
|
[`rust-protobuf`]: https://github.com/stepancheg/rust-protobuf/
|
|
|
|
See the [protobuf example](../examples/proto) for a more complete example of use.
|
|
|
|
### Prost Setup
|
|
|
|
```python
|
|
load("@rules_rust//proto/prost:repositories.bzl", "rust_prost_dependencies")
|
|
|
|
rust_prost_dependencies()
|
|
|
|
load("@rules_rust//proto/prost:transitive_repositories.bzl", "rust_prost_transitive_repositories")
|
|
|
|
rust_prost_transitive_repositories()
|
|
```
|
|
|
|
The `prost` and `tonic` rules do not specify a default toolchain in order to avoid mismatched
|
|
dependency issues. To setup the `prost` and `tonic` toolchain, please see the section
|
|
[Customizing `prost` and `tonic` Dependencies](#custom-prost-deps).
|
|
|
|
For additional information about Bazel toolchains, see [here](https://docs.bazel.build/versions/master/toolchains.html).
|
|
|
|
#### <a name="custom-prost-deps">Customizing `prost` and `tonic` Dependencies
|
|
|
|
These rules depend on the [`prost`] and [`tonic`] dependencies. To setup the necessary toolchain
|
|
for these rules, you must define a toolchain with the [`prost`], [`prost-types`], [`tonic`], [`protoc-gen-prost`], and [`protoc-gen-tonic`] crates as well as the [`protoc`] binary.
|
|
|
|
[`prost`]: https://crates.io/crates/prost
|
|
[`prost-types`]: https://crates.io/crates/prost-types
|
|
[`protoc-gen-prost`]: https://crates.io/crates/protoc-gen-prost
|
|
[`protoc-gen-tonic`]: https://crates.io/crates/protoc-gen-tonic
|
|
[`tonic`]: https://crates.io/crates/tonic
|
|
[`protoc`]: https://github.com/protocolbuffers/protobuf
|
|
|
|
To get access to these crates, you can use the [crate_universe](./crate_universe.md) repository
|
|
rules. For example:
|
|
|
|
```python
|
|
load("//crate_universe:defs.bzl", "crate", "crates_repository")
|
|
|
|
crates_repository(
|
|
name = "crates_io",
|
|
annotations = {
|
|
"protoc-gen-prost": [crate.annotation(
|
|
gen_binaries = ["protoc-gen-prost"],
|
|
patch_args = [
|
|
"-p1",
|
|
],
|
|
patches = [
|
|
# Note: You will need to use this patch until a version greater than `0.2.2` of
|
|
# `protoc-gen-prost` is released.
|
|
"@rules_rust//proto/prost/private/3rdparty/patches:protoc-gen-prost.patch",
|
|
],
|
|
)],
|
|
"protoc-gen-tonic": [crate.annotation(
|
|
gen_binaries = ["protoc-gen-tonic"],
|
|
)],
|
|
},
|
|
cargo_lockfile = "Cargo.Bazel.lock",
|
|
mode = "remote",
|
|
packages = {
|
|
"prost": crate.spec(
|
|
version = "0",
|
|
),
|
|
"prost-types": crate.spec(
|
|
version = "0",
|
|
),
|
|
"protoc-gen-prost": crate.spec(
|
|
version = "0",
|
|
),
|
|
"protoc-gen-tonic": crate.spec(
|
|
version = "0",
|
|
),
|
|
"tonic": crate.spec(
|
|
version = "0",
|
|
),
|
|
},
|
|
repository_name = "rules_rust_prost",
|
|
tags = ["manual"],
|
|
)
|
|
```
|
|
|
|
You can then define a toolchain with the `rust_prost_toolchain` rule which uses the crates
|
|
defined above. For example:
|
|
|
|
```python
|
|
load("@rules_rust//proto/prost:defs.bzl", "rust_prost_toolchain")
|
|
load("@rules_rust//rust:defs.bzl", "rust_library_group")
|
|
|
|
rust_library_group(
|
|
name = "prost_runtime",
|
|
deps = [
|
|
"@crates_io//:prost",
|
|
],
|
|
)
|
|
|
|
rust_library_group(
|
|
name = "tonic_runtime",
|
|
deps = [
|
|
":prost_runtime",
|
|
"@crates_io//:tonic",
|
|
],
|
|
)
|
|
|
|
rust_prost_toolchain(
|
|
name = "prost_toolchain_impl",
|
|
prost_plugin = "@crates_io//:protoc-gen-prost__protoc-gen-prost",
|
|
prost_runtime = ":prost_runtime",
|
|
prost_types = "@crates_io//:prost-types",
|
|
proto_compiler = "@com_google_protobuf//:protoc",
|
|
tonic_plugin = "@crates_io//:protoc-gen-tonic__protoc-gen-tonic",
|
|
tonic_runtime = ":tonic_runtime",
|
|
)
|
|
|
|
toolchain(
|
|
name = "prost_toolchain",
|
|
toolchain = "prost_toolchain_impl",
|
|
toolchain_type = "@rules_rust//proto/prost:toolchain_type",
|
|
)
|
|
```
|
|
|
|
Lastly, you must register the toolchain in your `WORKSPACE` file. For example:
|
|
|
|
```python
|
|
register_toolchains("//toolchains:prost_toolchain")
|
|
```
|
|
|
|
## Rust-Protobuf Setup
|
|
|
|
To use the Rust proto rules, add the following to your `WORKSPACE` file to add the
|
|
external repositories for the Rust proto toolchain (in addition to the [rust rules setup](..)):
|
|
|
|
```python
|
|
load("@rules_rust//proto/protobuf:repositories.bzl", "rust_proto_protobuf_dependencies", "rust_proto_protobuf_register_toolchains")
|
|
|
|
rust_proto_protobuf_dependencies()
|
|
|
|
rust_proto_protobuf_register_toolchains()
|
|
|
|
load("@rules_rust//proto/protobuf:transitive_repositories.bzl", "rust_proto_protobuf_transitive_repositories")
|
|
|
|
rust_proto_protobuf_transitive_repositories()
|
|
```
|
|
|
|
This will load the required dependencies for the [`rust-protobuf`] rules. It will also
|
|
register a default toolchain for the `rust_proto_library` and `rust_grpc_library` rules.
|
|
|
|
To customize the `rust_proto_library` and `rust_grpc_library` toolchain, please see the section
|
|
[Customizing `rust-protobuf` Dependencies](#custom-proto-deps).
|
|
|
|
For additional information about Bazel toolchains, see [here](https://docs.bazel.build/versions/master/toolchains.html).
|
|
|
|
#### <a name="custom-proto-deps">Customizing `rust-protobuf` Dependencies
|
|
|
|
These rules depend on the [`protobuf`](https://crates.io/crates/protobuf) and
|
|
the [`grpc`](https://crates.io/crates/grpc) crates in addition to the [protobuf
|
|
compiler](https://github.com/google/protobuf). To obtain these crates,
|
|
`rust_proto_repositories` imports the given crates using BUILD files generated with
|
|
[crate_universe](./crate_universe.md).
|
|
|
|
If you want to either change the protobuf and gRPC rust compilers, or to
|
|
simply use [crate_universe](./crate_universe.md) in a more
|
|
complex scenario (with more dependencies), you must redefine those
|
|
dependencies.
|
|
|
|
To do this, once you've imported the needed dependencies (see our
|
|
[@rules_rust//proto/protobuf/3rdparty/BUILD.bazel](https://github.com/bazelbuild/rules_rust/blob/main/proto/protobuf/3rdparty/BUILD.bazel)
|
|
file to see the default dependencies), you need to create your own toolchain.
|
|
To do so you can create a BUILD file with your toolchain definition, for example:
|
|
|
|
```python
|
|
load("@rules_rust//proto:toolchain.bzl", "rust_proto_toolchain")
|
|
|
|
rust_proto_toolchain(
|
|
name = "proto-toolchain-impl",
|
|
# Path to the protobuf compiler.
|
|
protoc = "@com_google_protobuf//:protoc",
|
|
# Protobuf compiler plugin to generate rust gRPC stubs.
|
|
grpc_plugin = "//3rdparty/crates:cargo_bin_protoc_gen_rust_grpc",
|
|
# Protobuf compiler plugin to generate rust protobuf stubs.
|
|
proto_plugin = "//3rdparty/crates:cargo_bin_protoc_gen_rust",
|
|
)
|
|
|
|
toolchain(
|
|
name = "proto-toolchain",
|
|
toolchain = ":proto-toolchain-impl",
|
|
toolchain_type = "@rules_rust//proto/protobuf:toolchain_type",
|
|
)
|
|
```
|
|
|
|
Now that you have your own toolchain, you need to register it by
|
|
inserting the following statement in your `WORKSPACE` file:
|
|
|
|
```python
|
|
register_toolchains("//my/toolchains:proto-toolchain")
|
|
```
|
|
|
|
Finally, you might want to set the `rust_deps` attribute in
|
|
`rust_proto_library` and `rust_grpc_library` to change the compile-time
|
|
dependencies:
|
|
|
|
```python
|
|
rust_proto_library(
|
|
...
|
|
rust_deps = ["//3rdparty/crates:protobuf"],
|
|
...
|
|
)
|
|
|
|
rust_grpc_library(
|
|
...
|
|
rust_deps = [
|
|
"//3rdparty/crates:protobuf",
|
|
"//3rdparty/crates:grpc",
|
|
"//3rdparty/crates:tls_api",
|
|
"//3rdparty/crates:tls_api_stub",
|
|
],
|
|
...
|
|
)
|
|
```
|
|
|
|
__Note__: Ideally, we would inject those dependencies from the toolchain,
|
|
but due to [bazelbuild/bazel#6889](https://github.com/bazelbuild/bazel/issues/6889)
|
|
all dependencies added via the toolchain ends-up being in the wrong
|
|
configuration.
|
|
|
|
---
|
|
---
|
|
|
|
]]#
|