rules_rust

Rust Proto

Overview

These build rules are used for building protobufs/gRPC in 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.

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

Prost Setup

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.

For additional information about Bazel toolchains, see here.

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.

To get access to these crates, you can use the crate_universe repository rules. For example:

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:

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:

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

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.

For additional information about Bazel toolchains, see here.

Customizing rust-protobuf Dependencies

These rules depend 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 crate_universe.

If you want to either change the protobuf and gRPC rust compilers, or to simply use crate_universe 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/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:

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:

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 = ["//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 all dependencies added via the toolchain ends-up being in the wrong configuration.



rust_grpc_library

rust_grpc_library(name, crate_name, deps, rust_deps, rustc_flags)

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

Example:

load("@rules_rust//proto/protobuf:defs.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  
crate_name Crate name to use for this target.

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 ""
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 []
rustc_flags List of compiler flags passed to rustc.

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 []

rust_prost_toolchain

rust_prost_toolchain(name, prost_opts, prost_plugin, prost_plugin_flag, prost_runtime, prost_types,
                     proto_compiler, tonic_opts, tonic_plugin, tonic_plugin_flag, tonic_runtime)

Rust Prost toolchain rule.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required  
prost_opts Additional options to add to Prost. List of strings optional []
prost_plugin Additional plugins to add to Prost. Label required  
prost_plugin_flag Prost plugin flag format. (e.g. --plugin=protoc-gen-prost=%s) String optional "--plugin=protoc-gen-prost=%s"
prost_runtime The Prost runtime crates to use. Label required  
prost_types The Prost types crates to use. Label required  
proto_compiler The protoc compiler to use. Label required  
tonic_opts Additional options to add to Tonic. List of strings optional []
tonic_plugin Additional plugins to add to Tonic. Label optional None
tonic_plugin_flag Tonic plugin flag format. (e.g. --plugin=protoc-gen-tonic=%s)) String optional "--plugin=protoc-gen-tonic=%s"
tonic_runtime The Tonic runtime crates to use. Label optional None

rust_proto_library

rust_proto_library(name, crate_name, deps, rust_deps, rustc_flags)

Builds a Rust library crate from a set of proto_librarys.

Example:

load("@rules_rust//proto/protobuf:defs.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  
crate_name Crate name to use for this target.

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 ""
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 []
rustc_flags List of compiler flags passed to rustc.

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 []

rust_prost_dependencies

rust_prost_dependencies(bzlmod)

Declares repositories needed for prost.

PARAMETERS

Name Description Default Value
bzlmod Whether bzlmod is enabled. False

RETURNS

list[struct(repo=str, is_dev_dep=bool)]: A list of the repositories defined by this macro.

rust_prost_library

rust_prost_library(name, kwargs)

A rule for generating a Rust library using Prost.

PARAMETERS

Name Description Default Value
name The name of the target. none
kwargs Additional keyword arguments for the underlying rust_prost_library rule. none

rust_prost_transitive_repositories

rust_prost_transitive_repositories()

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

This macro should be called immediately after the rust_protobuf_dependencies macro.

rust_proto_protobuf_dependencies

rust_proto_protobuf_dependencies()

rust_proto_protobuf_register_toolchains

rust_proto_protobuf_register_toolchains(register_toolchains)

Register toolchains for proto compilation.

PARAMETERS

Name Description Default Value
register_toolchains <p align="center"> - </p> True

rust_proto_protobuf_transitive_repositories

rust_proto_protobuf_transitive_repositories()

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

This macro should be called immediately after the rust_protobuf_dependencies macro.