fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
fe657ed7
0.6.0
1#[[ 2## Overview 3 4These build rules are used for building [protobufs][protobuf]/[gRPC][grpc] in [Rust][rust] with Bazel. 5 6[rust]: http://www.rust-lang.org/ 7[protobuf]: https://developers.google.com/protocol-buffers/ 8[grpc]: https://grpc.io 9 10See the [protobuf example](../examples/proto) for a more complete example of use. 11 12### Setup 13 14To use the Rust proto rules, add the following to your `WORKSPACE` file to add the 15external repositories for the Rust proto toolchain (in addition to the [rust rules setup](..)): 16 17```python 18load("@rules_rust//proto:repositories.bzl", "rust_proto_repositories") 19 20rust_proto_repositories() 21 22load("@rules_rust//proto:transitive_repositories.bzl", "rust_proto_transitive_repositories") 23 24rust_proto_transitive_repositories() 25``` 26 27[raze]: https://github.com/google/cargo-raze 28 29This will load crate dependencies of protobuf that are generated using 30[cargo raze][raze] inside the rules_rust 31repository. However, using those dependencies might conflict with other uses 32of [cargo raze][raze]. If you need to change 33those dependencies, please see the [dedicated section below](#custom-deps). 34 35For additional information about Bazel toolchains, see [here](https://docs.bazel.build/versions/master/toolchains.html). 36 37## <a name="custom-deps">Customizing dependencies 38 39These rules depends on the [`protobuf`](https://crates.io/crates/protobuf) and 40the [`grpc`](https://crates.io/crates/grpc) crates in addition to the [protobuf 41compiler](https://github.com/google/protobuf). To obtain these crates, 42`rust_proto_repositories` imports the given crates using BUILD files generated with 43[`cargo raze`][raze]. 44 45If you want to either change the protobuf and gRPC rust compilers, or to 46simply use [`cargo raze`][raze] in a more 47complex scenario (with more dependencies), you must redefine those 48dependencies. 49 50To do this, once you've imported the needed dependencies (see our 51[Cargo.toml](raze/Cargo.toml) file to see the default dependencies), you 52need to create your own toolchain. To do so you can create a BUILD 53file with your toolchain definition, for example: 54 55```python 56load("@rules_rust//proto:toolchain.bzl", "rust_proto_toolchain") 57 58rust_proto_toolchain( 59 name = "proto-toolchain-impl", 60 # Path to the protobuf compiler. 61 protoc = "@com_google_protobuf//:protoc", 62 # Protobuf compiler plugin to generate rust gRPC stubs. 63 grpc_plugin = "//cargo_raze/remote:cargo_bin_protoc_gen_rust_grpc", 64 # Protobuf compiler plugin to generate rust protobuf stubs. 65 proto_plugin = "//cargo_raze/remote:cargo_bin_protoc_gen_rust", 66) 67 68toolchain( 69 name = "proto-toolchain", 70 toolchain = ":proto-toolchain-impl", 71 toolchain_type = "@rules_rust//proto:toolchain", 72) 73``` 74 75Now that you have your own toolchain, you need to register it by 76inserting the following statement in your `WORKSPACE` file: 77 78```python 79register_toolchains("//my/toolchains:proto-toolchain") 80``` 81 82Finally, you might want to set the `rust_deps` attribute in 83`rust_proto_library` and `rust_grpc_library` to change the compile-time 84dependencies: 85 86```python 87rust_proto_library( 88 ... 89 rust_deps = ["//cargo_raze/remote:protobuf"], 90 ... 91) 92 93rust_grpc_library( 94 ... 95 rust_deps = [ 96 "//cargo_raze/remote:protobuf", 97 "//cargo_raze/remote:grpc", 98 "//cargo_raze/remote:tls_api", 99 "//cargo_raze/remote:tls_api_stub", 100 ], 101 ... 102) 103``` 104 105__Note__: Ideally, we would inject those dependencies from the toolchain, 106but due to [bazelbuild/bazel#6889](https://github.com/bazelbuild/bazel/issues/6889) 107all dependencies added via the toolchain ends-up being in the wrong 108configuration. 109]]#