Add Prost and Tonic rules. (#2033)
* Setup Prost and Tonic rules.
* Regenerate documentation
* Add more tests.
* Add more tests and address feedback.
* Regenerate documentation
* Add to proto docs page.
* Bump min supported bazel version.
* buildifier
* Always enable backtracing.
* Add more info to failing rename.
* Set min rust version to 1.62.0
* Handle rust keywords as package names.
* exclude windows from prost toolchain support.
* buildifier
* redundant
* Use prost-types to parse the file descriptor set.
* Cleanup and more tests.
* Move prost-types to toolchain definition.
* fix rustfmt
* Add example of building protos with complex imports
* impl Display
* Fix all tests
* Add rust checks for the complex import protos.
* Address feedback
* Fix buildifier
* Depend on remote-apis repo.
* Remove bazel remote apis due to file length and transitive dependency issues.
* Update patch and docs.
* Regenerate documentation
* Regenerate documentation
* Update docs.
---------
Co-authored-by: Daniel Wagner-Hall <dwagnerhall@apple.com>
diff --git a/docs/rust_proto.vm b/docs/rust_proto.vm
index c5e069c..b2dce93 100644
--- a/docs/rust_proto.vm
+++ b/docs/rust_proto.vm
@@ -1,11 +1,16 @@
#[[
## 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_proto_library` and `rust_grpc_library`
+rules which generate Rust code using the [`rust-protobuf`] dependencies. The second ruleset defines
+the `rust_prost_library` and `rust_tonic_library` rules which generate Rust code using the [`prost`]
+and [`tonic`] dependencies respectively.
+
[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.
@@ -24,17 +29,21 @@
rust_proto_transitive_repositories()
```
-This will load crate dependencies of protobuf that are generated using
-[crate_universe](./crate_universe.md) inside the rules_rust
-repository. However, using those dependencies might conflict with other uses
-of [crate_universe](./crate_universe.md). If you need to change
-those dependencies, please see the [dedicated section below](#custom-deps).
+This will load the required dependencies for the Proto, Prost, and Tonic rules. It will also
+register a default toolchain for the `rust_proto_library` and `rust_grpc_library` rules. The
+`prost` and `tonic` rules do not specify a default toolchain in order to avoid mismatched
+dependency issues.
+
+To customize the `rust_proto_library` and `rust_grpc_library` toolchain, please see the section
+[Customizing `rust-protobuf` Dependencies](#custom-proto-deps).
+
+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-deps">Customizing dependencies
+## <a name="custom-proto-deps">Customizing `rust-protobuf` Dependencies
-These rules depends on the [`protobuf`](https://crates.io/crates/protobuf) and
+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
@@ -104,4 +113,109 @@
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.
+
+## <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 = "default_prost_toolchain_impl",
+ toolchain_type = "//proto/prost:toolchain_type",
+)
+```
+
+Lastly, you must register the toolchain in your `WORKSPACE` file. For example:
+
+```python
+register_toolchains("//toolchains:prost_toolchain")
+```
]]#
