1<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2# Rust Proto 3 4* [rust_prost_library](#rust_prost_library) 5* [rust_prost_toolchain](#rust_prost_toolchain) 6* [rust_prost_dependencies](#rust_prost_dependencies) 7* [rust_prost_transitive_repositories](#rust_prost_transitive_repositories) 8* [rust_proto_library](#rust_proto_library) 9* [rust_grpc_library](#rust_grpc_library) 10* [rust_proto_protobuf_toolchain](#rust_proto_protobuf_toolchain) 11* [rust_proto_protobuf_dependencies](#rust_proto_protobuf_dependencies) 12* [rust_proto_protobuf_register_toolchains](#rust_proto_protobuf_register_toolchains) 13* [rust_proto_protobuf_transitive_repositories](#rust_proto_protobuf_transitive_repositories) 14 15 16## Overview 17These build rules are used for building [protobufs][protobuf]/[gRPC][grpc] in [Rust][rust] with Bazel. 18 19There are two rule sets. The first ruleset defines the `rust_prost_library` which generates Rust code 20using the [`prost`] and [`tonic`] dependencies. The second ruleset defines the `rust_proto_library` and 21`rust_grpc_library` rules which generate Rust code using the [`rust-protobuf`] dependencies. 22 23[rust]: http://www.rust-lang.org/ 24[protobuf]: https://developers.google.com/protocol-buffers/ 25[grpc]: https://grpc.io 26[`rust-protobuf`]: https://github.com/stepancheg/rust-protobuf/ 27 28See the [protobuf example](../examples/proto) for a more complete example of use. 29 30### Prost Setup 31 32```python 33load("@rules_rust//proto/prost:repositories.bzl", "rust_prost_dependencies") 34 35rust_prost_dependencies() 36 37load("@rules_rust//proto/prost:transitive_repositories.bzl", "rust_prost_transitive_repositories") 38 39rust_prost_transitive_repositories() 40``` 41 42The `prost` and `tonic` rules do not specify a default toolchain in order to avoid mismatched 43dependency issues. To setup the `prost` and `tonic` toolchain, please see the section 44[Customizing `prost` and `tonic` Dependencies](#custom-prost-deps). 45 46For additional information about Bazel toolchains, see [here](https://docs.bazel.build/versions/master/toolchains.html). 47 48#### <a name="custom-prost-deps">Customizing `prost` and `tonic` Dependencies 49 50These rules depend on the [`prost`] and [`tonic`] dependencies. To setup the necessary toolchain 51for 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. 52 53[`prost`]: https://crates.io/crates/prost 54[`prost-types`]: https://crates.io/crates/prost-types 55[`protoc-gen-prost`]: https://crates.io/crates/protoc-gen-prost 56[`protoc-gen-tonic`]: https://crates.io/crates/protoc-gen-tonic 57[`tonic`]: https://crates.io/crates/tonic 58[`protoc`]: https://github.com/protocolbuffers/protobuf 59 60To get access to these crates, you can use the [crate_universe](./crate_universe.md) repository 61rules. For example: 62 63```python 64load("//crate_universe:defs.bzl", "crate", "crates_repository") 65 66crates_repository( 67 name = "crates_io", 68 annotations = { 69 "protoc-gen-prost": [crate.annotation( 70 gen_binaries = ["protoc-gen-prost"], 71 patch_args = [ 72 "-p1", 73 ], 74 patches = [ 75 # Note: You will need to use this patch until a version greater than `0.2.2` of 76 # `protoc-gen-prost` is released. 77 "@rules_rust//proto/prost/private/3rdparty/patches:protoc-gen-prost.patch", 78 ], 79 )], 80 "protoc-gen-tonic": [crate.annotation( 81 gen_binaries = ["protoc-gen-tonic"], 82 )], 83 }, 84 cargo_lockfile = "Cargo.Bazel.lock", 85 mode = "remote", 86 packages = { 87 "prost": crate.spec( 88 version = "0", 89 ), 90 "prost-types": crate.spec( 91 version = "0", 92 ), 93 "protoc-gen-prost": crate.spec( 94 version = "0", 95 ), 96 "protoc-gen-tonic": crate.spec( 97 version = "0", 98 ), 99 "tonic": crate.spec( 100 version = "0", 101 ), 102 }, 103 repository_name = "rules_rust_prost", 104 tags = ["manual"], 105) 106``` 107 108You can then define a toolchain with the `rust_prost_toolchain` rule which uses the crates 109defined above. For example: 110 111```python 112load("@rules_rust//proto/prost:defs.bzl", "rust_prost_toolchain") 113load("@rules_rust//rust:defs.bzl", "rust_library_group") 114 115rust_library_group( 116 name = "prost_runtime", 117 deps = [ 118 "@crates_io//:prost", 119 ], 120) 121 122rust_library_group( 123 name = "tonic_runtime", 124 deps = [ 125 ":prost_runtime", 126 "@crates_io//:tonic", 127 ], 128) 129 130rust_prost_toolchain( 131 name = "prost_toolchain_impl", 132 prost_plugin = "@crates_io//:protoc-gen-prost__protoc-gen-prost", 133 prost_runtime = ":prost_runtime", 134 prost_types = "@crates_io//:prost-types", 135 proto_compiler = "@com_google_protobuf//:protoc", 136 tonic_plugin = "@crates_io//:protoc-gen-tonic__protoc-gen-tonic", 137 tonic_runtime = ":tonic_runtime", 138) 139 140toolchain( 141 name = "prost_toolchain", 142 toolchain = "prost_toolchain_impl", 143 toolchain_type = "@rules_rust//proto/prost:toolchain_type", 144) 145``` 146 147Lastly, you must register the toolchain in your `WORKSPACE` file. For example: 148 149```python 150register_toolchains("//toolchains:prost_toolchain") 151``` 152 153## Rust-Protobuf Setup 154 155To use the Rust proto rules, add the following to your `WORKSPACE` file to add the 156external repositories for the Rust proto toolchain (in addition to the [rust rules setup](..)): 157 158```python 159load("@rules_rust//proto/protobuf:repositories.bzl", "rust_proto_protobuf_dependencies", "rust_proto_protobuf_register_toolchains") 160 161rust_proto_protobuf_dependencies() 162 163rust_proto_protobuf_register_toolchains() 164 165load("@rules_rust//proto/protobuf:transitive_repositories.bzl", "rust_proto_protobuf_transitive_repositories") 166 167rust_proto_protobuf_transitive_repositories() 168``` 169 170This will load the required dependencies for the [`rust-protobuf`] rules. It will also 171register a default toolchain for the `rust_proto_library` and `rust_grpc_library` rules. 172 173To customize the `rust_proto_library` and `rust_grpc_library` toolchain, please see the section 174[Customizing `rust-protobuf` Dependencies](#custom-proto-deps). 175 176For additional information about Bazel toolchains, see [here](https://docs.bazel.build/versions/master/toolchains.html). 177 178#### <a name="custom-proto-deps">Customizing `rust-protobuf` Dependencies 179 180These rules depend on the [`protobuf`](https://crates.io/crates/protobuf) and 181the [`grpc`](https://crates.io/crates/grpc) crates in addition to the [protobuf 182compiler](https://github.com/google/protobuf). To obtain these crates, 183`rust_proto_repositories` imports the given crates using BUILD files generated with 184[crate_universe](./crate_universe.md). 185 186If you want to either change the protobuf and gRPC rust compilers, or to 187simply use [crate_universe](./crate_universe.md) in a more 188complex scenario (with more dependencies), you must redefine those 189dependencies. 190 191To do this, once you've imported the needed dependencies (see our 192[@rules_rust//proto/3rdparty/BUILD.bazel](https://github.com/bazelbuild/rules_rust/blob/main/proto/3rdparty/BUILD.bazel) 193file to see the default dependencies), you need to create your own toolchain. 194To do so you can create a BUILD file with your toolchain definition, for example: 195 196```python 197load("@rules_rust//proto:toolchain.bzl", "rust_proto_toolchain") 198 199rust_proto_toolchain( 200 name = "proto-toolchain-impl", 201 # Path to the protobuf compiler. 202 protoc = "@com_google_protobuf//:protoc", 203 # Protobuf compiler plugin to generate rust gRPC stubs. 204 grpc_plugin = "//3rdparty/crates:cargo_bin_protoc_gen_rust_grpc", 205 # Protobuf compiler plugin to generate rust protobuf stubs. 206 proto_plugin = "//3rdparty/crates:cargo_bin_protoc_gen_rust", 207) 208 209toolchain( 210 name = "proto-toolchain", 211 toolchain = ":proto-toolchain-impl", 212 toolchain_type = "@rules_rust//proto/protobuf:toolchain_type", 213) 214``` 215 216Now that you have your own toolchain, you need to register it by 217inserting the following statement in your `WORKSPACE` file: 218 219```python 220register_toolchains("//my/toolchains:proto-toolchain") 221``` 222 223Finally, you might want to set the `rust_deps` attribute in 224`rust_proto_library` and `rust_grpc_library` to change the compile-time 225dependencies: 226 227```python 228rust_proto_library( 229 ... 230 rust_deps = ["//3rdparty/crates:protobuf"], 231 ... 232) 233 234rust_grpc_library( 235 ... 236 rust_deps = [ 237 "//3rdparty/crates:protobuf", 238 "//3rdparty/crates:grpc", 239 "//3rdparty/crates:tls_api", 240 "//3rdparty/crates:tls_api_stub", 241 ], 242 ... 243) 244``` 245 246__Note__: Ideally, we would inject those dependencies from the toolchain, 247but due to [bazelbuild/bazel#6889](https://github.com/bazelbuild/bazel/issues/6889) 248all dependencies added via the toolchain ends-up being in the wrong 249configuration. 250 251--- 252--- 253 254 255 256<a id="rust_grpc_library"></a> 257 258## rust_grpc_library 259 260<pre> 261rust_grpc_library(<a href="#rust_grpc_library-name">name</a>, <a href="#rust_grpc_library-deps">deps</a>, <a href="#rust_grpc_library-crate_name">crate_name</a>, <a href="#rust_grpc_library-rust_deps">rust_deps</a>, <a href="#rust_grpc_library-rustc_flags">rustc_flags</a>) 262</pre> 263 264Builds a Rust library crate from a set of `proto_library`s suitable for gRPC. 265 266Example: 267 268```python 269load("@rules_rust//proto/protobuf:defs.bzl", "rust_grpc_library") 270 271proto_library( 272 name = "my_proto", 273 srcs = ["my.proto"] 274) 275 276rust_grpc_library( 277 name = "rust", 278 deps = [":my_proto"], 279) 280 281rust_binary( 282 name = "my_service", 283 srcs = ["my_service.rs"], 284 deps = [":rust"], 285) 286``` 287 288**ATTRIBUTES** 289 290 291| Name | Description | Type | Mandatory | Default | 292| :------------- | :------------- | :------------- | :------------- | :------------- | 293| <a id="rust_grpc_library-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 294| <a id="rust_grpc_library-deps"></a>deps | List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding gRPC stubs. | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | | 295| <a id="rust_grpc_library-crate_name"></a>crate_name | Crate name to use for this target.<br><br>This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores. | String | optional | `""` | 296| <a id="rust_grpc_library-rust_deps"></a>rust_deps | The crates the generated library depends on. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 297| <a id="rust_grpc_library-rustc_flags"></a>rustc_flags | List of compiler flags passed to `rustc`.<br><br>These strings are subject to Make variable expansion for predefined source/output path variables like `$location`, `$execpath`, and `$rootpath`. This expansion is useful if you wish to pass a generated file of arguments to rustc: `@$(location //package:target)`. | List of strings | optional | `[]` | 298 299 300<a id="rust_prost_toolchain"></a> 301 302## rust_prost_toolchain 303 304<pre> 305rust_prost_toolchain(<a href="#rust_prost_toolchain-name">name</a>, <a href="#rust_prost_toolchain-prost_opts">prost_opts</a>, <a href="#rust_prost_toolchain-prost_plugin">prost_plugin</a>, <a href="#rust_prost_toolchain-prost_plugin_flag">prost_plugin_flag</a>, <a href="#rust_prost_toolchain-prost_runtime">prost_runtime</a>, <a href="#rust_prost_toolchain-prost_types">prost_types</a>, 306 <a href="#rust_prost_toolchain-proto_compiler">proto_compiler</a>, <a href="#rust_prost_toolchain-tonic_opts">tonic_opts</a>, <a href="#rust_prost_toolchain-tonic_plugin">tonic_plugin</a>, <a href="#rust_prost_toolchain-tonic_plugin_flag">tonic_plugin_flag</a>, <a href="#rust_prost_toolchain-tonic_runtime">tonic_runtime</a>) 307</pre> 308 309Rust Prost toolchain rule. 310 311**ATTRIBUTES** 312 313 314| Name | Description | Type | Mandatory | Default | 315| :------------- | :------------- | :------------- | :------------- | :------------- | 316| <a id="rust_prost_toolchain-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 317| <a id="rust_prost_toolchain-prost_opts"></a>prost_opts | Additional options to add to Prost. | List of strings | optional | `[]` | 318| <a id="rust_prost_toolchain-prost_plugin"></a>prost_plugin | Additional plugins to add to Prost. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | 319| <a id="rust_prost_toolchain-prost_plugin_flag"></a>prost_plugin_flag | Prost plugin flag format. (e.g. `--plugin=protoc-gen-prost=%s`) | String | optional | `"--plugin=protoc-gen-prost=%s"` | 320| <a id="rust_prost_toolchain-prost_runtime"></a>prost_runtime | The Prost runtime crates to use. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | 321| <a id="rust_prost_toolchain-prost_types"></a>prost_types | The Prost types crates to use. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | 322| <a id="rust_prost_toolchain-proto_compiler"></a>proto_compiler | The protoc compiler to use. Note that this attribute is deprecated - prefer to use --incompatible_enable_proto_toolchain_resolution. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 323| <a id="rust_prost_toolchain-tonic_opts"></a>tonic_opts | Additional options to add to Tonic. | List of strings | optional | `[]` | 324| <a id="rust_prost_toolchain-tonic_plugin"></a>tonic_plugin | Additional plugins to add to Tonic. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 325| <a id="rust_prost_toolchain-tonic_plugin_flag"></a>tonic_plugin_flag | Tonic plugin flag format. (e.g. `--plugin=protoc-gen-tonic=%s`)) | String | optional | `"--plugin=protoc-gen-tonic=%s"` | 326| <a id="rust_prost_toolchain-tonic_runtime"></a>tonic_runtime | The Tonic runtime crates to use. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 327 328 329<a id="rust_proto_library"></a> 330 331## rust_proto_library 332 333<pre> 334rust_proto_library(<a href="#rust_proto_library-name">name</a>, <a href="#rust_proto_library-deps">deps</a>, <a href="#rust_proto_library-crate_name">crate_name</a>, <a href="#rust_proto_library-rust_deps">rust_deps</a>, <a href="#rust_proto_library-rustc_flags">rustc_flags</a>) 335</pre> 336 337Builds a Rust library crate from a set of `proto_library`s. 338 339Example: 340 341```python 342load("@rules_rust//proto/protobuf:defs.bzl", "rust_proto_library") 343 344proto_library( 345 name = "my_proto", 346 srcs = ["my.proto"] 347) 348 349rust_proto_library( 350 name = "rust", 351 deps = [":my_proto"], 352) 353 354rust_binary( 355 name = "my_proto_binary", 356 srcs = ["my_proto_binary.rs"], 357 deps = [":rust"], 358) 359``` 360 361**ATTRIBUTES** 362 363 364| Name | Description | Type | Mandatory | Default | 365| :------------- | :------------- | :------------- | :------------- | :------------- | 366| <a id="rust_proto_library-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 367| <a id="rust_proto_library-deps"></a>deps | List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding stubs. | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | | 368| <a id="rust_proto_library-crate_name"></a>crate_name | Crate name to use for this target.<br><br>This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores. | String | optional | `""` | 369| <a id="rust_proto_library-rust_deps"></a>rust_deps | The crates the generated library depends on. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 370| <a id="rust_proto_library-rustc_flags"></a>rustc_flags | List of compiler flags passed to `rustc`.<br><br>These strings are subject to Make variable expansion for predefined source/output path variables like `$location`, `$execpath`, and `$rootpath`. This expansion is useful if you wish to pass a generated file of arguments to rustc: `@$(location //package:target)`. | List of strings | optional | `[]` | 371 372 373<a id="rust_prost_dependencies"></a> 374 375## rust_prost_dependencies 376 377<pre> 378rust_prost_dependencies(<a href="#rust_prost_dependencies-bzlmod">bzlmod</a>) 379</pre> 380 381Declares repositories needed for prost. 382 383**PARAMETERS** 384 385 386| Name | Description | Default Value | 387| :------------- | :------------- | :------------- | 388| <a id="rust_prost_dependencies-bzlmod"></a>bzlmod | Whether bzlmod is enabled. | `False` | 389 390**RETURNS** 391 392list[struct(repo=str, is_dev_dep=bool)]: A list of the repositories 393 defined by this macro. 394 395 396<a id="rust_prost_library"></a> 397 398## rust_prost_library 399 400<pre> 401rust_prost_library(<a href="#rust_prost_library-name">name</a>, <a href="#rust_prost_library-kwargs">kwargs</a>) 402</pre> 403 404A rule for generating a Rust library using Prost. 405 406**PARAMETERS** 407 408 409| Name | Description | Default Value | 410| :------------- | :------------- | :------------- | 411| <a id="rust_prost_library-name"></a>name | The name of the target. | none | 412| <a id="rust_prost_library-kwargs"></a>kwargs | Additional keyword arguments for the underlying `rust_prost_library` rule. | none | 413 414 415<a id="rust_prost_transitive_repositories"></a> 416 417## rust_prost_transitive_repositories 418 419<pre> 420rust_prost_transitive_repositories() 421</pre> 422 423Load transitive dependencies of the `@rules_rust//proto/protobuf` rules. 424 425This macro should be called immediately after the `rust_protobuf_dependencies` macro. 426 427 428 429<a id="rust_proto_protobuf_dependencies"></a> 430 431## rust_proto_protobuf_dependencies 432 433<pre> 434rust_proto_protobuf_dependencies(<a href="#rust_proto_protobuf_dependencies-bzlmod">bzlmod</a>) 435</pre> 436 437Sets up dependencies for rules_rust's proto support. 438 439**PARAMETERS** 440 441 442| Name | Description | Default Value | 443| :------------- | :------------- | :------------- | 444| <a id="rust_proto_protobuf_dependencies-bzlmod"></a>bzlmod | Whether this function is being called from a bzlmod context rather than a workspace context. | `False` | 445 446**RETURNS** 447 448A list of structs containing information about root module deps to report to bzlmod's extension_metadata. 449 450 451<a id="rust_proto_protobuf_register_toolchains"></a> 452 453## rust_proto_protobuf_register_toolchains 454 455<pre> 456rust_proto_protobuf_register_toolchains(<a href="#rust_proto_protobuf_register_toolchains-register_toolchains">register_toolchains</a>) 457</pre> 458 459Register toolchains for proto compilation. 460 461**PARAMETERS** 462 463 464| Name | Description | Default Value | 465| :------------- | :------------- | :------------- | 466| <a id="rust_proto_protobuf_register_toolchains-register_toolchains"></a>register_toolchains | <p align="center"> - </p> | `True` | 467 468 469<a id="rust_proto_protobuf_transitive_repositories"></a> 470 471## rust_proto_protobuf_transitive_repositories 472 473<pre> 474rust_proto_protobuf_transitive_repositories() 475</pre> 476 477Load transitive dependencies of the `@rules_rust//proto/protobuf` rules. 478 479This macro should be called immediately after the `rust_protobuf_dependencies` macro. 480 481 482 483