Rust Proto

• rust_grpc_library
• rust_proto_library
• rust_proto_repositories
• rust_proto_transitive_repositories
• rust_proto_toolchain

Overview

These build rules are used for building protobufs/gRPC in Rust with Bazel.

See the protobuf example for a more complete example of use.

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):

load("@rules_rust//proto:repositories.bzl", "rust_proto_repositories")

rust_proto_repositories()

load("@rules_rust//proto:transitive_repositories.bzl", "rust_proto_transitive_repositories")

rust_proto_transitive_repositories()

This will load crate dependencies of protobuf that are generated using cargo raze inside the rules_rust repository. However, using those dependencies might conflict with other uses of cargo raze. If you need to change those dependencies, please see the dedicated section below.

For additional information about Bazel toolchains, see here.

Customizing dependencies

These rules depends on the protobuf and the grpc crates in addition to the protobuf compiler. To obtain these crates, rust_proto_repositories imports the given crates using BUILD files generated with cargo raze.

If you want to either change the protobuf and gRPC rust compilers, or to simply use cargo raze 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 Cargo.toml 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:

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 = "//cargo_raze/remote:cargo_bin_protoc_gen_rust_grpc",
    # Protobuf compiler plugin to generate rust protobuf stubs.
    proto_plugin = "//cargo_raze/remote:cargo_bin_protoc_gen_rust",
)

toolchain(
    name = "proto-toolchain",
    toolchain = ":proto-toolchain-impl",
    toolchain_type = "@rules_rust//proto:toolchain",
)

Now that you have your own toolchain, you need to register it by inserting the following statement in your WORKSPACE file:

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:

rust_proto_library(
    ...
    rust_deps = ["//cargo_raze/remote:protobuf"],
    ...
)

rust_grpc_library(
    ...
    rust_deps = [
        "//cargo_raze/remote:protobuf",
        "//cargo_raze/remote:grpc",
        "//cargo_raze/remote:tls_api",
        "//cargo_raze/remote:tls_api_stub",
    ],
    ...
)

Note: Ideally, we would inject those dependencies from the toolchain, but due to bazelbuild/bazel#6889 all dependencies added via the toolchain ends-up being in the wrong configuration.

rust_grpc_library

Builds a Rust library crate from a set of proto_librarys suitable for gRPC.

Example:

load("//proto:proto.bzl", "rust_grpc_library")

proto_library(
    name = "my_proto",
    srcs = ["my.proto"]
)

rust_grpc_library(
    name = "rust",
    deps = [":my_proto"],
)

rust_binary(
    name = "my_service",
    srcs = ["my_service.rs"],
    deps = [":rust"],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding gRPC stubs.	List of labels	required
rust_deps	The crates the generated library depends on.	List of labels	optional	[]

rust_proto_library

Builds a Rust library crate from a set of proto_librarys.

Example:

load("@rules_rust//proto:proto.bzl", "rust_proto_library")

proto_library(
    name = "my_proto",
    srcs = ["my.proto"]
)

rust_proto_library(
    name = "rust",
    deps = [":my_proto"],
)

rust_binary(
    name = "my_proto_binary",
    srcs = ["my_proto_binary.rs"],
    deps = [":rust"],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding stubs.	List of labels	required
rust_deps	The crates the generated library depends on.	List of labels	optional	[]

rust_proto_toolchain

Declares a Rust Proto toolchain for use.

This is used to configure proto compilation and can be used to set different protobuf compiler plugin.

Example:

Suppose a new nicer gRPC plugin has came out. The new plugin can be used in Bazel by defining a new toolchain definition and declaration:

load('@rules_rust//proto:toolchain.bzl', 'rust_proto_toolchain')

rust_proto_toolchain(
   name="rust_proto_impl",
   grpc_plugin="@rust_grpc//:grpc_plugin",
   grpc_compile_deps=["@rust_grpc//:grpc_deps"],
)

toolchain(
    name="rust_proto",
    exec_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    target_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    toolchain = ":rust_proto_impl",
)

Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the --extra_toolchains flag for Bazel, and it will be used.

See @rules_rust//proto:BUILD for examples of defining the toolchain.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
edition	The edition used by the generated rust source.	String	optional	“2018”
grpc_compile_deps	The crates the generated grpc libraries depends on.	List of labels	optional	[Label(“//proto/raze:protobuf”), Label(“//proto/raze:grpc”), Label(“//proto/raze:tls_api”), Label(“//proto/raze:tls_api_stub”)]
grpc_plugin	The location of the Rust protobuf compiler plugin to generate rust gRPC stubs.	Label	optional	//proto:protoc_gen_rust_grpc
proto_compile_deps	The crates the generated protobuf libraries depends on.	List of labels	optional	[Label(“//proto/raze:protobuf”)]
proto_plugin	The location of the Rust protobuf compiler plugin used to generate rust sources.	Label	optional	//proto:protoc_gen_rust
protoc	The location of the protoc binary. It should be an executable target.	Label	optional	@com_google_protobuf//:protoc

rust_proto_repositories

Declare dependencies needed for proto compilation.

PARAMETERS

Name	Description	Default Value
register_default_toolchain	If True, the default rust_proto_toolchain (@rules_rust//proto:default-proto-toolchain) is registered. This toolchain requires a set of dependencies that were generated using cargo raze. These will also be loaded.	True

rust_proto_transitive_repositories

Load transitive dependencies of the @rules_rust//proto rules.

This macro should be called immediately after the rust_proto_repositories macro.