Rules Rust

This repository provides rules for building Rust projects with Bazel.

Setup

The rules are released, and releases can be found on the GitHub Releases page. We recommend using the latest release from that page.

Bzlmod

Note that rules_rust bzlmod support is still a work in progress. Most features should work, but bugs are more likely. This is not a desired end-state - please report (or better yet, help fix!) bugs you run into.

To use rules_rust in a project using bzlmod, add the following to your MODULE.bazel file:

bazel_dep(name = "rules_rust", version = "0.48.0")

Don't forget to substitute in your desired release's version number.

WORKSPACE

To use rules_rust in a project using a WORKSPACE file, add the following to your WORKSPACE file to add the external repositories for the Rust toolchain:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

# To find additional information on this release or newer ones visit:
# https://github.com/bazelbuild/rules_rust/releases
http_archive(
    name = "rules_rust",
    integrity = "sha256-Weev1uz2QztBlDA88JX6A1N72SucD1V8lBsaliM0TTg=",
    urls = ["https://github.com/bazelbuild/rules_rust/releases/download/0.48.0/rules_rust-v0.48.0.tar.gz"],
)

load("@rules_rust//rust:repositories.bzl", "rules_rust_dependencies", "rust_register_toolchains")

rules_rust_dependencies()

rust_register_toolchains()

Don't forget to substitute in your desired release's version number and integrity hash.

Specifying Rust version

To build with a particular version of the Rust compiler, pass that version to rust_register_toolchains:

rust_register_toolchains(
    edition = "2021",
    versions = [
        "1.79.0"
    ],
)

As well as an exact version, versions can accept nightly/{iso_date} and beta/{iso_date} strings for toolchains from different release channels.

rust_register_toolchains(
    edition = "2021",
    versions = [
        "nightly/2024-06-13",
    ],
)

By default, a stable and nightly toolchain will be registered if no versions are passed to rust_register_toolchains. However, if only 1 version is passed and it is from the nightly or beta release channels (i.e. not stable), then a build setting must also be set in the project's .bazelrc file.

build --@rules_rust//rust/toolchain/channel=nightly

Failure to do so will result in rules attempting to match a stable toolchain when one was not registered.

Supported bazel versions

The oldest version of Bazel the main branch is tested against is 7.3.1. Previous versions may still be functional in certain environments, but this is the minimum version we strive to fully support.

We test these rules against the latest rolling releases of Bazel, and aim for compatibility with them, but prioritise stable releases over rolling releases where necessary.

Supported platforms

We aim to support Linux and macOS.

We do not have sufficient maintainer expertise to support Windows. Most things probably work, but we have had to disable many tests in CI because we lack the expertise to fix them. We welcome contributions to help improve its support.

Windows support for some features requires --enable_runfiles to be passed to Bazel, we recommend putting it in your bazelrc. See Using Bazel on Windows for more Windows-specific recommendations.

Rules

• defs: standard rust rules for building and testing libraries and binaries.
• rustdoc: rules for generating and testing rust documentation.
• clippy: rules for running clippy.
• rustfmt: rules for running rustfmt.
• cargo: Rules dedicated to Cargo compatibility. ie: build.rs scripts.
• crate_universe: Rules for generating Bazel targets for external crate dependencies.

Experimental rules

• rust_analyzer: rules for generating rust-project.json files for rust-analyzer

3rd party rules

• rust_bindgen: rules for generating C++ bindings.
• rust_proto: rules for generating protobuf and gRPC stubs.
• rust_wasm_bindgen: rules for generating WebAssembly bindings.

Full API

You can also browse the full API in one page.

Rust

• rust_binary
• rust_library
• rust_library_group
• rust_static_library
• rust_shared_library
• rust_proc_macro
• rust_test
• rust_test_suite
• error_format
• extra_rustc_flag
• extra_rustc_flags
• capture_clippy_output

capture_clippy_output

capture_clippy_output(name)

Control whether to print clippy output or store it to a file, using the configured error_format.

ATTRIBUTES

error_format

error_format(name)

Change the --error-format flag from the command line with --@rules_rust//:error_format. See rustc documentation for valid values.

ATTRIBUTES

extra_rustc_flag

extra_rustc_flag(name)

Add additional rustc_flag from the command line with --@rules_rust//:extra_rustc_flag. Multiple uses are accumulated and appended after the extra_rustc_flags.

ATTRIBUTES

extra_rustc_flags

extra_rustc_flags(name)

Add additional rustc_flags from the command line with --@rules_rust//:extra_rustc_flags. This flag should only be used for flags that need to be applied across the entire build. For options that apply to individual crates, use the rustc_flags attribute on the individual crate's rule instead. NOTE: These flags not applied to the exec configuration (proc-macros, cargo_build_script, etc); use --@rules_rust//:extra_exec_rustc_flags to apply flags to the exec configuration.

ATTRIBUTES

rust_binary

rust_binary(name, deps, srcs, data, aliases, alwayslink, binary_name, compile_data, crate_features,
            crate_name, crate_root, crate_type, edition, env, experimental_use_cc_common_link,
            linker_script, malloc, out_binary, platform, proc_macro_deps, rustc_env, rustc_env_files,
            rustc_flags, stamp, version)

Builds a Rust binary crate.

Example:

Suppose you have the following directory structure for a Rust project with a library crate, hello_lib, and a binary crate, hello_world that uses the hello_lib library:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs
    hello_world/
        BUILD
        src/
            main.rs

hello_lib/src/lib.rs:

#![allow(unused)]
fn main() {
pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) {
        println!("{} {}", &self.greeting, thing);
    }
}
}

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

load("@rules_rust//rust:defs.bzl", "rust_library")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

hello_world/src/main.rs:

extern crate hello_lib;

fn main() {
    let hello = hello_lib::Greeter::new("Hello");
    hello.greet("world");
}

hello_world/BUILD:

load("@rules_rust//rust:defs.bzl", "rust_binary")

rust_binary(
    name = "hello_world",
    srcs = ["src/main.rs"],
    deps = ["//hello_lib"],
)

Build and run hello_world:

$ bazel run //hello_world
INFO: Found 1 target...
Target //examples/rust/hello_world:hello_world up-to-date:
bazel-bin/examples/rust/hello_world/hello_world
INFO: Elapsed time: 1.308s, Critical Path: 1.22s

INFO: Running command line: bazel-bin/examples/rust/hello_world/hello_world
Hello world

On Windows, a PDB file containing debugging information is available under the key pdb_file in OutputGroupInfo. Similarly on macOS, a dSYM folder is available under the key dsym_folder in OutputGroupInfo.

ATTRIBUTES

rust_library

rust_library(name, deps, srcs, data, aliases, alwayslink, compile_data, crate_features, crate_name,
             crate_root, disable_pipelining, edition, proc_macro_deps, rustc_env, rustc_env_files,
             rustc_flags, stamp, version)

Builds a Rust library crate.

Example:

Suppose you have the following directory structure for a simple Rust library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            greeter.rs
            lib.rs

hello_lib/src/greeter.rs:

#![allow(unused)]
fn main() {
pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) {
        println!("{} {}", &self.greeting, thing);
    }
}
}

hello_lib/src/lib.rs:

#![allow(unused)]
fn main() {
pub mod greeter;
}

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

load("@rules_rust//rust:defs.bzl", "rust_library")

rust_library(
    name = "hello_lib",
    srcs = [
        "src/greeter.rs",
        "src/lib.rs",
    ],
)

Build the library:

$ bazel build //hello_lib
INFO: Found 1 target...
Target //examples/rust/hello_lib:hello_lib up-to-date:
bazel-bin/examples/rust/hello_lib/libhello_lib.rlib
INFO: Elapsed time: 1.245s, Critical Path: 1.01s

ATTRIBUTES

rust_library_group

rust_library_group(name, deps)

Functions as an alias for a set of dependencies.

Specifically, the following are equivalent:

rust_library_group(
    name = "crate_group",
    deps = [
        ":crate1",
        ":crate2",
    ],
)

rust_library(
    name = "foobar",
    deps = [":crate_group"],
    ...
)

and

rust_library(
    name = "foobar",
    deps = [
        ":crate1",
        ":crate2",
    ],
    ...
)

ATTRIBUTES

rust_proc_macro

rust_proc_macro(name, deps, srcs, data, aliases, alwayslink, compile_data, crate_features,
                crate_name, crate_root, edition, proc_macro_deps, rustc_env, rustc_env_files,
                rustc_flags, stamp, version)

Builds a Rust proc-macro crate.

ATTRIBUTES

rust_shared_library

rust_shared_library(name, deps, srcs, data, aliases, alwayslink, compile_data, crate_features,
                    crate_name, crate_root, edition, experimental_use_cc_common_link, malloc,
                    platform, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, stamp,
                    version)

Builds a Rust shared library.

This shared library will contain all transitively reachable crates and native objects. It is meant to be used when producing an artifact that is then consumed by some other build system (for example to produce a shared library that Python program links against).

This rule provides CcInfo, so it can be used everywhere Bazel expects rules_cc.

When building the whole binary in Bazel, use rust_library instead.

ATTRIBUTES

rust_static_library

rust_static_library(name, deps, srcs, data, aliases, alwayslink, compile_data, crate_features,
                    crate_name, crate_root, edition, platform, proc_macro_deps, rustc_env,
                    rustc_env_files, rustc_flags, stamp, version)

Builds a Rust static library.

This static library will contain all transitively reachable crates and native objects. It is meant to be used when producing an artifact that is then consumed by some other build system (for example to produce an archive that Python program links against).

This rule provides CcInfo, so it can be used everywhere Bazel expects rules_cc.

When building the whole binary in Bazel, use rust_library instead.

ATTRIBUTES

rust_test

rust_test(name, deps, srcs, data, aliases, alwayslink, compile_data, crate, crate_features,
          crate_name, crate_root, edition, env, env_inherit, experimental_use_cc_common_link, malloc,
          platform, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, stamp,
          use_libtest_harness, version)

Builds a Rust test crate.

Examples:

Suppose you have the following directory structure for a Rust library crate with unit test code in the library sources:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs

hello_lib/src/lib.rs:

#![allow(unused)]
fn main() {
pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) -> String {
        format!("{} {}", &self.greeting, thing)
    }
}

#[cfg(test)]
mod test {
    use super::Greeter;

    #[test]
    fn test_greeting() {
        let hello = Greeter::new("Hi");
        assert_eq!("Hi Rust", hello.greet("Rust"));
    }
}
}

To build and run the tests, simply add a rust_test rule with no srcs and only depends on the hello_lib rust_library target via the crate attribute:

hello_lib/BUILD:

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_test(
    name = "hello_lib_test",
    crate = ":hello_lib",
    # You may add other deps that are specific to the test configuration
    deps = ["//some/dev/dep"],
)

Run the test with bazel test //hello_lib:hello_lib_test.

Example: test directory

Integration tests that live in the tests directory, they are essentially built as separate crates. Suppose you have the following directory structure where greeting.rs is an integration test for the hello_lib library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs
        tests/
            greeting.rs

hello_lib/tests/greeting.rs:

#![allow(unused)]
fn main() {
extern crate hello_lib;

use hello_lib;

#[test]
fn test_greeting() {
    let hello = greeter::Greeter::new("Hello");
    assert_eq!("Hello world", hello.greeting("world"));
}
}

To build the greeting.rs integration test, simply add a rust_test target with greeting.rs in srcs and a dependency on the hello_lib target:

hello_lib/BUILD:

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_test(
    name = "greeting_test",
    srcs = ["tests/greeting.rs"],
    deps = [":hello_lib"],
)

Run the test with bazel test //hello_lib:greeting_test.

ATTRIBUTES

rust_test_suite

rust_test_suite(name, srcs, shared_srcs, kwargs)

A rule for creating a test suite for a set of rust_test targets.

This rule can be used for setting up typical rust integration tests. Given the following directory structure:

[crate]/
    BUILD.bazel
    src/
        lib.rs
        main.rs
    tests/
        integrated_test_a.rs
        integrated_test_b.rs
        integrated_test_c.rs
        patterns/
            fibonacci_test.rs
        helpers/
            mod.rs

The rule can be used to generate rust_test targets for each source file under tests and a test_suite which encapsulates all tests.

load("//rust:defs.bzl", "rust_binary", "rust_library", "rust_test_suite")

rust_library(
    name = "math_lib",
    srcs = ["src/lib.rs"],
)

rust_binary(
    name = "math_bin",
    srcs = ["src/main.rs"],
)

rust_test_suite(
    name = "integrated_tests_suite",
    srcs = glob(["tests/**"]),
    shared_srcs=glob(["tests/helpers/**"]),
    deps = [":math_lib"],
)

PARAMETERS

Rust Doc

• rust_doc
• rust_doc_test

rust_doc

rust_doc(name, crate, html_after_content, html_before_content, html_in_header, markdown_css,
         rustc_flags, rustdoc_flags)

Generates code documentation.

Example: Suppose you have the following directory structure for a Rust library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs

To build rustdoc documentation for the hello_lib crate, define a rust_doc rule that depends on the the hello_lib rust_library target:

package(default_visibility = ["//visibility:public"])

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_doc(
    name = "hello_lib_doc",
    crate = ":hello_lib",
)

Running bazel build //hello_lib:hello_lib_doc will build a zip file containing the documentation for the hello_lib library crate generated by rustdoc.

ATTRIBUTES

rust_doc_test

rust_doc_test(name, deps, crate, proc_macro_deps)

Runs Rust documentation tests.

Example:

Suppose you have the following directory structure for a Rust library crate:

[workspace]/
WORKSPACE
hello_lib/
    BUILD
    src/
        lib.rs

To run documentation tests for the hello_lib crate, define a rust_doc_test target that depends on the hello_lib rust_library target:

package(default_visibility = ["//visibility:public"])

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_doc_test(
    name = "hello_lib_doc_test",
    crate = ":hello_lib",
)

Running bazel test //hello_lib:hello_lib_doc_test will run all documentation tests for the hello_lib library crate.

ATTRIBUTES

Rust Clippy

• rust_clippy
• rust_clippy_aspect

Overview

Clippy is a tool for catching common mistakes in Rust code and improving it. An expansive list of lints and the justification can be found in their documentation.

Setup

Simply add the following to the .bazelrc file in the root of your workspace:

build --aspects=@rules_rust//rust:defs.bzl%rust_clippy_aspect
build --output_groups=+clippy_checks

This will enable clippy on all Rust targets.

Note that targets tagged with no-clippy will not perform clippy checks

To use a local clippy.toml, add the following flag to your .bazelrc. Note that due to the upstream implementation of clippy, this file must be named either .clippy.toml or clippy.toml. Using a custom config file requires Rust 1.34.0 or newer.

build --@rules_rust//:clippy.toml=//:clippy.toml

rust_clippy

rust_clippy(name, deps)

Executes the clippy checker on a specific target.

Similar to rust_clippy_aspect, but allows specifying a list of dependencies within the build system.

For example, given the following example targets:

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_test(
    name = "greeting_test",
    srcs = ["tests/greeting.rs"],
    deps = [":hello_lib"],
)

Rust clippy can be set as a build target with the following:

load("@rules_rust//rust:defs.bzl", "rust_clippy")

rust_clippy(
    name = "hello_library_clippy",
    testonly = True,
    deps = [
        ":hello_lib",
        ":greeting_test",
    ],
)

ATTRIBUTES

rust_clippy_aspect

rust_clippy_aspect(name)

Executes the clippy checker on specified targets.

This aspect applies to existing rust_library, rust_test, and rust_binary rules.

As an example, if the following is defined in examples/hello_lib/BUILD.bazel:

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_test(
    name = "greeting_test",
    srcs = ["tests/greeting.rs"],
    deps = [":hello_lib"],
)

Then the targets can be analyzed with clippy using the following command:

$ bazel build --aspects=@rules_rust//rust:defs.bzl%rust_clippy_aspect               --output_groups=clippy_checks //hello_lib:all

ASPECT ATTRIBUTES

ATTRIBUTES

Rust Fmt

• rustfmt_aspect
• rustfmt_test
• rustfmt_toolchain

Overview

Rustfmt is a tool for formatting Rust code according to style guidelines. By default, Rustfmt uses a style which conforms to the Rust style guide that has been formalized through the style RFC process. A complete list of all configuration options can be found in the Rustfmt GitHub Pages.

Setup

Formatting your Rust targets' source code requires no setup outside of loading rules_rust in your workspace. Simply run bazel run @rules_rust//:rustfmt to format source code.

In addition to this formatter, a simple check can be performed using the rustfmt_aspect aspect by running

bazel build --aspects=@rules_rust//rust:defs.bzl%rustfmt_aspect --output_groups=rustfmt_checks

Add the following to a .bazelrc file to enable this check during the build phase.

build --aspects=@rules_rust//rust:defs.bzl%rustfmt_aspect
build --output_groups=+rustfmt_checks

It's recommended to only enable this aspect in your CI environment so formatting issues do not impact user's ability to rapidly iterate on changes.

The rustfmt_aspect also uses a --@rules_rust//:rustfmt.toml setting which determines the configuration file used by the formatter (@rules_rust//tools/rustfmt) and the aspect (rustfmt_aspect). This flag can be added to your .bazelrc file to ensure a consistent config file is used whenever rustfmt is run:

build --@rules_rust//:rustfmt.toml=//:rustfmt.toml

Tips

Any target which uses Bazel generated sources will cause the @rules_rust//tools/rustfmt tool to fail with failed to resolve mod `MOD` . To avoid failures, skip_children = true is recommended to be set in the workspace's rustfmt.toml file which allows rustfmt to run on these targets without failing.

rustfmt_test

rustfmt_test(name, targets)

A test rule for performing rustfmt --check on a set of targets

ATTRIBUTES

rustfmt_toolchain

rustfmt_toolchain(name, rustc, rustc_lib, rustfmt)

A toolchain for rustfmt

ATTRIBUTES

rustfmt_aspect

rustfmt_aspect(name)

This aspect is used to gather information about a crate for use in rustfmt and perform rustfmt checks

Output Groups:

• rustfmt_checks: Executes rustfmt --check on the specified target.

The build setting @rules_rust//:rustfmt.toml is used to control the Rustfmt configuration settings used at runtime.

This aspect is executed on any target which provides the CrateInfo provider. However users may tag a target with no-rustfmt or no-format to have it skipped. Additionally, generated source files are also ignored by this aspect.

ASPECT ATTRIBUTES

ATTRIBUTES

Rust Proto

• rust_prost_library
• rust_prost_toolchain
• rust_prost_dependencies
• rust_prost_transitive_repositories
• rust_proto_library
• rust_grpc_library
• rust_proto_protobuf_toolchain
• rust_proto_protobuf_dependencies
• rust_proto_protobuf_register_toolchains
• rust_proto_protobuf_transitive_repositories

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/protobuf/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, deps, crate_name, 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

rust_prost_toolchain

rust_prost_toolchain(name, include_transitive_deps, 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

rust_proto_library

rust_proto_library(name, deps, crate_name, 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

rust_prost_dependencies

rust_prost_dependencies(bzlmod)

Declares repositories needed for prost.

PARAMETERS

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

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(bzlmod)

Sets up dependencies for rules_rust's proto support.

PARAMETERS

RETURNS

A list of structs containing information about root module deps to report to bzlmod's extension_metadata.

rust_proto_protobuf_register_toolchains

rust_proto_protobuf_register_toolchains(register_toolchains)

Register toolchains for proto compilation.

PARAMETERS

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.

Rust Bindgen

• rust_bindgen_library
• rust_bindgen
• rust_bindgen_toolchain
• rust_bindgen_dependencies
• rust_bindgen_register_toolchains

Overview

These rules are for using Bindgen to generate Rust bindings to C (and some C++) libraries.

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

Setup

To use the Rust bindgen rules, add the following to your WORKSPACE file to add the external repositories for the Rust bindgen toolchain (in addition to the rust rules setup):

load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains")

rust_bindgen_dependencies()

rust_bindgen_register_toolchains()

load("@rules_rust//bindgen:transitive_repositories.bzl", "rust_bindgen_transitive_dependencies")

rust_bindgen_transitive_dependencies()

Bindgen aims to be as hermetic as possible so will end up building libclang from llvm-project from source. If this is found to be undesirable then no Bindgen related calls should be added to your WORKSPACE and instead users should define their own repositories using something akin to crate_universe and define their own toolchains following the instructions for rust_bindgen_toolchain.

rust_bindgen

rust_bindgen(name, bindgen_flags, cc_lib, clang_flags, header, merge_cc_lib_objects_into_rlib,
             wrap_static_fns)

Generates a rust source file from a cc_library and a header.

ATTRIBUTES

rust_bindgen_toolchain

rust_bindgen_toolchain(name, bindgen, clang, default_rustfmt, libclang, libstdcxx)

The tools required for the rust_bindgen rule.

This rule depends on the bindgen binary crate, and it in turn depends on both a clang binary and the clang library. To obtain these dependencies, rust_bindgen_dependencies imports bindgen and its dependencies.

load("@rules_rust//bindgen:defs.bzl", "rust_bindgen_toolchain")

rust_bindgen_toolchain(
    name = "bindgen_toolchain_impl",
    bindgen = "//my/rust:bindgen",
    clang = "//my/clang:clang",
    libclang = "//my/clang:libclang.so",
    libstdcxx = "//my/cpp:libstdc++",
)

toolchain(
    name = "bindgen_toolchain",
    toolchain = "bindgen_toolchain_impl",
    toolchain_type = "@rules_rust//bindgen:toolchain_type",
)

This toolchain will then need to be registered in the current WORKSPACE. For additional information, see the Bazel toolchains documentation.

ATTRIBUTES

rust_bindgen_dependencies

rust_bindgen_dependencies()

Declare dependencies needed for bindgen.

RETURNS

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

rust_bindgen_library

rust_bindgen_library(name, header, cc_lib, bindgen_flags, bindgen_features, clang_flags,
                     wrap_static_fns, kwargs)

Generates a rust source file for header, and builds a rust_library.

Arguments are the same as rust_bindgen, and kwargs are passed directly to rust_library.

PARAMETERS

rust_bindgen_register_toolchains

rust_bindgen_register_toolchains(register_toolchains)

Registers the default toolchains for the rules_rust bindgen rules.

PARAMETERS

Rust Wasm Bindgen

• rust_wasm_bindgen_dependencies
• rust_wasm_bindgen_register_toolchains
• rust_wasm_bindgen_toolchain
• rust_wasm_bindgen
• RustWasmBindgenInfo

Overview

Bazel rules for generating wasm modules for Javascript using wasm-bindgen.

Setup

To begin using the wasm-bindgen rules, users can load the necessary dependencies in their workspace by adding the following to their WORKSPACE.bazel file.

load("@rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_dependencies", "rust_wasm_bindgen_register_toolchains")

rust_wasm_bindgen_dependencies()

rust_wasm_bindgen_register_toolchains()

This should enable users to start using the rust_wasm_bindgen rule. However, it's common to want to control the version of wasm-bindgen in the workspace instead of relying on the one provided by rules_rust. In this case, users should avoid calling rust_wasm_bindgen_register_toolchains and instead use the rust_wasm_bindgen_toolchain rule to define their own toolchains to register in the workspace.

Interfacing with Javascript rules

While it's recommended for users to mantain their own , in the @rules_rust//wasm_bindgen package there exists interface sub-packages for various Javascript Bazel rules. E.g. build_bazel_rules_nodejs or aspect_rules_js. The rules defined there are a more convenient way to use rust_wasm_bindgen with the associated javascript rules due to the inclusion of additional providers. Each directory contains a defs.bzl file that defines the different variants of rust_wasm_bindgen. (e.g. nodejs_rust_wasm_bindgen for the rules_nodejs submodule).

rust_wasm_bindgen

rust_wasm_bindgen(name, bindgen_flags, target, target_arch, wasm_file)

Generates javascript and typescript bindings for a webassembly module using wasm-bindgen.

An example of this rule in use can be seen at @rules_rust//examples/wasm

ATTRIBUTES

rust_wasm_bindgen_toolchain

rust_wasm_bindgen_toolchain(name, bindgen)

The tools required for the rust_wasm_bindgen rule.

In cases where users want to control or change the version of wasm-bindgen used by rust_wasm_bindgen, a unique toolchain can be created as in the example below:

load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")

rust_bindgen_toolchain(
    bindgen = "//3rdparty/crates:wasm_bindgen_cli__bin",
)

toolchain(
    name = "wasm_bindgen_toolchain",
    toolchain = "wasm_bindgen_toolchain_impl",
    toolchain_type = "@rules_rust//wasm_bindgen: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:wasm_bindgen_toolchain")

For additional information, see the Bazel toolchains documentation.

ATTRIBUTES

RustWasmBindgenInfo

RustWasmBindgenInfo(js, ts, wasm)

Info about wasm-bindgen outputs.

FIELDS

rust_wasm_bindgen_dependencies

rust_wasm_bindgen_dependencies()

Declare dependencies needed for the rules_rust wasm-bindgen rules.

RETURNS

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

rust_wasm_bindgen_register_toolchains

rust_wasm_bindgen_register_toolchains(register_toolchains)

Registers the default toolchains for the rules_rust wasm-bindgen rules.

PARAMETERS

Cargo

• cargo_bootstrap_repository
• cargo_build_script
• cargo_dep_env
• cargo_env

cargo_dep_env

cargo_dep_env(name, src, out_dir)

A rule for generating variables for dependent cargo_build_scripts without a build script. This is useful for using Bazel rules instead of a build script, while also generating configuration information for build scripts which depend on this crate.

ATTRIBUTES

cargo_build_script

cargo_build_script(name, edition, crate_name, crate_root, srcs, crate_features, version, deps,
                   link_deps, proc_macro_deps, build_script_env, data, compile_data, tools, links,
                   rundir, rustc_env, rustc_env_files, rustc_flags, visibility, tags, aliases,
                   pkg_name, kwargs)

Compile and execute a rust build script to generate build attributes

This rules take the same arguments as rust_binary.

Example:

Suppose you have a crate with a cargo build script build.rs:

[workspace]/
    hello_lib/
        BUILD
        build.rs
        src/
            lib.rs

Then you want to use the build script in the following:

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

load("@rules_rust//rust:defs.bzl", "rust_binary", "rust_library")
load("@rules_rust//cargo:defs.bzl", "cargo_build_script")

# This will run the build script from the root of the workspace, and
# collect the outputs.
cargo_build_script(
    name = "build_script",
    srcs = ["build.rs"],
    # Optional environment variables passed during build.rs compilation
    rustc_env = {
       "CARGO_PKG_VERSION": "0.1.2",
    },
    # Optional environment variables passed during build.rs execution.
    # Note that as the build script's working directory is not execroot,
    # execpath/location will return an absolute path, instead of a relative
    # one.
    build_script_env = {
        "SOME_TOOL_OR_FILE": "$(execpath @tool//:binary)"
    },
    # Optional data/tool dependencies
    data = ["@tool//:binary"],
)

rust_library(
    name = "hello_lib",
    srcs = [
        "src/lib.rs",
    ],
    deps = [":build_script"],
)

The hello_lib target will be build with the flags and the environment variables declared by the build script in addition to the file generated by it.

PARAMETERS

cargo_env

cargo_env(env)

A helper for generating platform specific environment variables

load("@rules_rust//rust:defs.bzl", "rust_common")
load("@rules_rust//cargo:defs.bzl", "cargo_bootstrap_repository", "cargo_env")

cargo_bootstrap_repository(
    name = "bootstrapped_bin",
    cargo_lockfile = "//:Cargo.lock",
    cargo_toml = "//:Cargo.toml",
    srcs = ["//:resolver_srcs"],
    version = rust_common.default_version,
    binary = "my-crate-binary",
    env = {
        "x86_64-unknown-linux-gnu": cargo_env({
            "FOO": "BAR",
        }),
    },
    env_label = {
        "aarch64-unknown-linux-musl": cargo_env({
            "DOC": "//:README.md",
        }),
    }
)

PARAMETERS

RETURNS

str: A json encoded string of the environment variables

cargo_bootstrap_repository

cargo_bootstrap_repository(name, srcs, binary, build_mode, cargo_config, cargo_lockfile, cargo_toml,
                           env, env_label, repo_mapping, rust_toolchain_cargo_template,
                           rust_toolchain_rustc_template, timeout, version)

A rule for bootstrapping a Rust binary using Cargo

ATTRIBUTES

Rust Analyzer

• rust_analyzer_aspect
• rust_analyzer_toolchain

Overview

For non-Cargo projects, rust-analyzer depends on a rust-project.json file at the root of the project that describes its structure. The rust_analyzer rule facilitates generating such a file.

Setup

First, ensure rules_rust is setup in your workspace. By default, rust_register_toolchains will ensure a rust_analyzer_toolchain is registered within the WORKSPACE.

Next, load the dependencies for the rust-project.json generator tool:

load("@rules_rust//tools/rust_analyzer:deps.bzl", "rust_analyzer_dependencies")

rust_analyzer_dependencies()

Finally, run bazel run @rules_rust//tools/rust_analyzer:gen_rust_project whenever dependencies change to regenerate the rust-project.json file. It should be added to .gitignore because it is effectively a build artifact. Once the rust-project.json has been generated in the project root, rust-analyzer can pick it up upon restart.

For users who do not use rust_register_toolchains to register toolchains, the following can be added to their WORKSPACE to register a rust_analyzer_toolchain. Please make sure the Rust version used in this toolchain matches the version used by the currently registered toolchain or the sources/documentation will not match what's being compiled with and can lead to confusing results.

load("@rules_rust//rust:repositories.bzl", "rust_analyzer_toolchain_repository")

register_toolchains(rust_analyzer_toolchain_repository(
    name = "rust_analyzer_toolchain",
    # This should match the currently registered toolchain.
    version = "1.63.0",
))

VSCode

To set this up using VSCode, users should first install the rust_analyzer plugin. With that in place, the following task can be added to the .vscode/tasks.json file of the workspace to ensure a rust-project.json file is created and up to date when the editor is opened.

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Generate rust-project.json",
            "command": "bazel",
            "args": [
                "run",
                "//tools/rust_analyzer:gen_rust_project"
            ],
            "options": {
                "cwd": "${workspaceFolder}"
            },
            "group": "build",
            "problemMatcher": [],
            "presentation": {
                "reveal": "never",
                "panel": "dedicated",
            },
            "runOptions": {
                "runOn": "folderOpen"
            }
        },
    ]
}

Alternative vscode option (prototype)

Add the following to your bazelrc:

build --@rules_rust//:rustc_output_diagnostics=true --output_groups=+rust_lib_rustc_output,+rust_metadata_rustc_output

Then you can use a prototype rust-analyzer plugin that automatically collects the outputs whenever you recompile.

rust_analyzer_toolchain

rust_analyzer_toolchain(name, proc_macro_srv, rustc, rustc_srcs)

A toolchain for rust-analyzer.

ATTRIBUTES

rust_analyzer_aspect

rust_analyzer_aspect(name)

Annotates rust rules with RustAnalyzerInfo later used to build a rust-project.json

ASPECT ATTRIBUTES

ATTRIBUTES

Rust rules

• CrateInfo
• DepInfo
• RustWasmBindgenInfo
• StdLibInfo
• capture_clippy_output
• cargo_bootstrap_repository
• cargo_build_script
• cargo_dep_env
• cargo_env
• error_format
• extra_rustc_flag
• extra_rustc_flags
• fail_when_enabled
• incompatible_flag
• rules_rust_dependencies
• rust_analyzer_aspect
• rust_analyzer_toolchain
• rust_analyzer_toolchain_repository
• rust_binary
• rust_bindgen
• rust_bindgen_dependencies
• rust_bindgen_library
• rust_bindgen_register_toolchains
• rust_bindgen_toolchain
• rust_clippy
• rust_clippy_aspect
• rust_doc
• rust_doc_test
• rust_grpc_library
• rust_library
• rust_library_group
• rust_proc_macro
• rust_prost_dependencies
• rust_prost_library
• rust_prost_toolchain
• rust_prost_transitive_repositories
• rust_proto_library
• rust_proto_protobuf_dependencies
• rust_proto_protobuf_register_toolchains
• rust_proto_protobuf_toolchain
• rust_proto_protobuf_transitive_repositories
• rust_register_toolchains
• rust_repositories
• rust_repository_set
• rust_shared_library
• rust_static_library
• rust_stdlib_filegroup
• rust_test
• rust_test_suite
• rust_toolchain
• rust_toolchain_repository
• rust_toolchain_repository_proxy
• rust_toolchain_tools_repository
• rust_wasm_bindgen
• rust_wasm_bindgen_dependencies
• rust_wasm_bindgen_register_toolchains
• rust_wasm_bindgen_toolchain
• rustfmt_aspect
• rustfmt_test
• rustfmt_toolchain

capture_clippy_output

capture_clippy_output(name)

Control whether to print clippy output or store it to a file, using the configured error_format.

ATTRIBUTES

cargo_dep_env

cargo_dep_env(name, src, out_dir)

A rule for generating variables for dependent cargo_build_scripts without a build script. This is useful for using Bazel rules instead of a build script, while also generating configuration information for build scripts which depend on this crate.

ATTRIBUTES

error_format

error_format(name)

Change the --error-format flag from the command line with --@rules_rust//:error_format. See rustc documentation for valid values.

ATTRIBUTES

extra_rustc_flag

extra_rustc_flag(name)

Add additional rustc_flag from the command line with --@rules_rust//:extra_rustc_flag. Multiple uses are accumulated and appended after the extra_rustc_flags.

ATTRIBUTES

extra_rustc_flags

extra_rustc_flags(name)

Add additional rustc_flags from the command line with --@rules_rust//:extra_rustc_flags. This flag should only be used for flags that need to be applied across the entire build. For options that apply to individual crates, use the rustc_flags attribute on the individual crate's rule instead. NOTE: These flags not applied to the exec configuration (proc-macros, cargo_build_script, etc); use --@rules_rust//:extra_exec_rustc_flags to apply flags to the exec configuration.

ATTRIBUTES

incompatible_flag

incompatible_flag(name, issue)

A rule defining an incompatible flag.

ATTRIBUTES

rust_analyzer_toolchain

rust_analyzer_toolchain(name, proc_macro_srv, rustc, rustc_srcs)

A toolchain for rust-analyzer.

ATTRIBUTES

rust_binary

rust_binary(name, deps, srcs, data, aliases, alwayslink, binary_name, compile_data, crate_features,
            crate_name, crate_root, crate_type, edition, env, experimental_use_cc_common_link,
            linker_script, malloc, out_binary, platform, proc_macro_deps, rustc_env, rustc_env_files,
            rustc_flags, stamp, version)

Builds a Rust binary crate.

Example:

Suppose you have the following directory structure for a Rust project with a library crate, hello_lib, and a binary crate, hello_world that uses the hello_lib library:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs
    hello_world/
        BUILD
        src/
            main.rs

hello_lib/src/lib.rs:

#![allow(unused)]
fn main() {
pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) {
        println!("{} {}", &self.greeting, thing);
    }
}
}

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

load("@rules_rust//rust:defs.bzl", "rust_library")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

hello_world/src/main.rs:

extern crate hello_lib;

fn main() {
    let hello = hello_lib::Greeter::new("Hello");
    hello.greet("world");
}

hello_world/BUILD:

load("@rules_rust//rust:defs.bzl", "rust_binary")

rust_binary(
    name = "hello_world",
    srcs = ["src/main.rs"],
    deps = ["//hello_lib"],
)

Build and run hello_world:

$ bazel run //hello_world
INFO: Found 1 target...
Target //examples/rust/hello_world:hello_world up-to-date:
bazel-bin/examples/rust/hello_world/hello_world
INFO: Elapsed time: 1.308s, Critical Path: 1.22s

INFO: Running command line: bazel-bin/examples/rust/hello_world/hello_world
Hello world

On Windows, a PDB file containing debugging information is available under the key pdb_file in OutputGroupInfo. Similarly on macOS, a dSYM folder is available under the key dsym_folder in OutputGroupInfo.

ATTRIBUTES

rust_bindgen

rust_bindgen(name, bindgen_flags, cc_lib, clang_flags, header, merge_cc_lib_objects_into_rlib,
             wrap_static_fns)

Generates a rust source file from a cc_library and a header.

ATTRIBUTES

rust_bindgen_toolchain

rust_bindgen_toolchain(name, bindgen, clang, default_rustfmt, libclang, libstdcxx)

The tools required for the rust_bindgen rule.

This rule depends on the bindgen binary crate, and it in turn depends on both a clang binary and the clang library. To obtain these dependencies, rust_bindgen_dependencies imports bindgen and its dependencies.

load("@rules_rust//bindgen:defs.bzl", "rust_bindgen_toolchain")

rust_bindgen_toolchain(
    name = "bindgen_toolchain_impl",
    bindgen = "//my/rust:bindgen",
    clang = "//my/clang:clang",
    libclang = "//my/clang:libclang.so",
    libstdcxx = "//my/cpp:libstdc++",
)

toolchain(
    name = "bindgen_toolchain",
    toolchain = "bindgen_toolchain_impl",
    toolchain_type = "@rules_rust//bindgen:toolchain_type",
)

This toolchain will then need to be registered in the current WORKSPACE. For additional information, see the Bazel toolchains documentation.

ATTRIBUTES

rust_clippy

rust_clippy(name, deps)

Executes the clippy checker on a specific target.

Similar to rust_clippy_aspect, but allows specifying a list of dependencies within the build system.

For example, given the following example targets:

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_test(
    name = "greeting_test",
    srcs = ["tests/greeting.rs"],
    deps = [":hello_lib"],
)

Rust clippy can be set as a build target with the following:

load("@rules_rust//rust:defs.bzl", "rust_clippy")

rust_clippy(
    name = "hello_library_clippy",
    testonly = True,
    deps = [
        ":hello_lib",
        ":greeting_test",
    ],
)

ATTRIBUTES

rust_doc

rust_doc(name, crate, html_after_content, html_before_content, html_in_header, markdown_css,
         rustc_flags, rustdoc_flags)

Generates code documentation.

Example: Suppose you have the following directory structure for a Rust library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs

To build rustdoc documentation for the hello_lib crate, define a rust_doc rule that depends on the the hello_lib rust_library target:

package(default_visibility = ["//visibility:public"])

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_doc(
    name = "hello_lib_doc",
    crate = ":hello_lib",
)

Running bazel build //hello_lib:hello_lib_doc will build a zip file containing the documentation for the hello_lib library crate generated by rustdoc.

ATTRIBUTES

rust_doc_test

rust_doc_test(name, deps, crate, proc_macro_deps)

Runs Rust documentation tests.

Example:

Suppose you have the following directory structure for a Rust library crate:

[workspace]/
WORKSPACE
hello_lib/
    BUILD
    src/
        lib.rs

To run documentation tests for the hello_lib crate, define a rust_doc_test target that depends on the hello_lib rust_library target:

package(default_visibility = ["//visibility:public"])

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_doc_test(
    name = "hello_lib_doc_test",
    crate = ":hello_lib",
)

Running bazel test //hello_lib:hello_lib_doc_test will run all documentation tests for the hello_lib library crate.

ATTRIBUTES

rust_grpc_library

rust_grpc_library(name, deps, crate_name, 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

rust_library

rust_library(name, deps, srcs, data, aliases, alwayslink, compile_data, crate_features, crate_name,
             crate_root, disable_pipelining, edition, proc_macro_deps, rustc_env, rustc_env_files,
             rustc_flags, stamp, version)

Builds a Rust library crate.

Example:

Suppose you have the following directory structure for a simple Rust library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            greeter.rs
            lib.rs

hello_lib/src/greeter.rs:

#![allow(unused)]
fn main() {
pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) {
        println!("{} {}", &self.greeting, thing);
    }
}
}

hello_lib/src/lib.rs:

#![allow(unused)]
fn main() {
pub mod greeter;
}

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

load("@rules_rust//rust:defs.bzl", "rust_library")

rust_library(
    name = "hello_lib",
    srcs = [
        "src/greeter.rs",
        "src/lib.rs",
    ],
)

Build the library:

$ bazel build //hello_lib
INFO: Found 1 target...
Target //examples/rust/hello_lib:hello_lib up-to-date:
bazel-bin/examples/rust/hello_lib/libhello_lib.rlib
INFO: Elapsed time: 1.245s, Critical Path: 1.01s

ATTRIBUTES

rust_library_group

rust_library_group(name, deps)

Functions as an alias for a set of dependencies.

Specifically, the following are equivalent:

rust_library_group(
    name = "crate_group",
    deps = [
        ":crate1",
        ":crate2",
    ],
)

rust_library(
    name = "foobar",
    deps = [":crate_group"],
    ...
)

and

rust_library(
    name = "foobar",
    deps = [
        ":crate1",
        ":crate2",
    ],
    ...
)

ATTRIBUTES

rust_proc_macro

rust_proc_macro(name, deps, srcs, data, aliases, alwayslink, compile_data, crate_features,
                crate_name, crate_root, edition, proc_macro_deps, rustc_env, rustc_env_files,
                rustc_flags, stamp, version)

Builds a Rust proc-macro crate.

ATTRIBUTES

rust_prost_toolchain

rust_prost_toolchain(name, include_transitive_deps, 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

rust_proto_library

rust_proto_library(name, deps, crate_name, 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

rust_shared_library

rust_shared_library(name, deps, srcs, data, aliases, alwayslink, compile_data, crate_features,
                    crate_name, crate_root, edition, experimental_use_cc_common_link, malloc,
                    platform, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, stamp,
                    version)

Builds a Rust shared library.

This shared library will contain all transitively reachable crates and native objects. It is meant to be used when producing an artifact that is then consumed by some other build system (for example to produce a shared library that Python program links against).

This rule provides CcInfo, so it can be used everywhere Bazel expects rules_cc.

When building the whole binary in Bazel, use rust_library instead.

ATTRIBUTES

rust_static_library

rust_static_library(name, deps, srcs, data, aliases, alwayslink, compile_data, crate_features,
                    crate_name, crate_root, edition, platform, proc_macro_deps, rustc_env,
                    rustc_env_files, rustc_flags, stamp, version)

Builds a Rust static library.

This static library will contain all transitively reachable crates and native objects. It is meant to be used when producing an artifact that is then consumed by some other build system (for example to produce an archive that Python program links against).

This rule provides CcInfo, so it can be used everywhere Bazel expects rules_cc.

When building the whole binary in Bazel, use rust_library instead.

ATTRIBUTES

rust_stdlib_filegroup

rust_stdlib_filegroup(name, srcs)

A dedicated filegroup-like rule for Rust stdlib artifacts.

ATTRIBUTES

rust_test

rust_test(name, deps, srcs, data, aliases, alwayslink, compile_data, crate, crate_features,
          crate_name, crate_root, edition, env, env_inherit, experimental_use_cc_common_link, malloc,
          platform, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, stamp,
          use_libtest_harness, version)

Builds a Rust test crate.

Examples:

Suppose you have the following directory structure for a Rust library crate with unit test code in the library sources:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs

hello_lib/src/lib.rs:

#![allow(unused)]
fn main() {
pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) -> String {
        format!("{} {}", &self.greeting, thing)
    }
}

#[cfg(test)]
mod test {
    use super::Greeter;

    #[test]
    fn test_greeting() {
        let hello = Greeter::new("Hi");
        assert_eq!("Hi Rust", hello.greet("Rust"));
    }
}
}

To build and run the tests, simply add a rust_test rule with no srcs and only depends on the hello_lib rust_library target via the crate attribute:

hello_lib/BUILD:

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_test(
    name = "hello_lib_test",
    crate = ":hello_lib",
    # You may add other deps that are specific to the test configuration
    deps = ["//some/dev/dep"],
)

Run the test with bazel test //hello_lib:hello_lib_test.

Example: test directory

Integration tests that live in the tests directory, they are essentially built as separate crates. Suppose you have the following directory structure where greeting.rs is an integration test for the hello_lib library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs
        tests/
            greeting.rs

hello_lib/tests/greeting.rs:

#![allow(unused)]
fn main() {
extern crate hello_lib;

use hello_lib;

#[test]
fn test_greeting() {
    let hello = greeter::Greeter::new("Hello");
    assert_eq!("Hello world", hello.greeting("world"));
}
}

To build the greeting.rs integration test, simply add a rust_test target with greeting.rs in srcs and a dependency on the hello_lib target:

hello_lib/BUILD:

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_test(
    name = "greeting_test",
    srcs = ["tests/greeting.rs"],
    deps = [":hello_lib"],
)

Run the test with bazel test //hello_lib:greeting_test.

ATTRIBUTES

rust_toolchain

rust_toolchain(name, allocator_library, binary_ext, cargo, cargo_clippy, clippy_driver, debug_info,
               default_edition, dylib_ext, env, exec_triple, experimental_link_std_dylib,
               experimental_use_cc_common_link, extra_exec_rustc_flags, extra_rustc_flags,
               extra_rustc_flags_for_crate_types, global_allocator_library, llvm_cov, llvm_profdata,
               llvm_tools, opt_level, per_crate_rustc_flags, rust_doc, rust_std, rustc, rustc_lib,
               rustfmt, staticlib_ext, stdlib_linkflags, strip_level, target_json, target_triple)

Declares a Rust toolchain for use.

This is for declaring a custom toolchain, eg. for configuring a particular version of rust or supporting a new platform.

Example:

Suppose the core rust team has ported the compiler to a new target CPU, called cpuX. This support can be used in Bazel by defining a new toolchain definition and declaration:

load('@rules_rust//rust:toolchain.bzl', 'rust_toolchain')

rust_toolchain(
    name = "rust_cpuX_impl",
    binary_ext = "",
    dylib_ext = ".so",
    exec_triple = "cpuX-unknown-linux-gnu",
    rust_doc = "@rust_cpuX//:rustdoc",
    rust_std = "@rust_cpuX//:rust_std",
    rustc = "@rust_cpuX//:rustc",
    rustc_lib = "@rust_cpuX//:rustc_lib",
    staticlib_ext = ".a",
    stdlib_linkflags = ["-lpthread", "-ldl"],
    target_triple = "cpuX-unknown-linux-gnu",
)

toolchain(
    name = "rust_cpuX",
    exec_compatible_with = [
        "@platforms//cpu:cpuX",
        "@platforms//os:linux",
    ],
    target_compatible_with = [
        "@platforms//cpu:cpuX",
        "@platforms//os:linux",
    ],
    toolchain = ":rust_cpuX_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//rust:repositories.bzl for examples of defining the @rust_cpuX repository with the actual binaries and libraries.

ATTRIBUTES