Toolchains
A Rust build in Bazel selects its compiler, standard library, and companion tools
through a set of registered Bazel toolchains. rules_rust
ships one toolchain type per companion tool so that Rust, rustdoc, clippy,
rustfmt, cargo, and rust-analyzer can be resolved independently, and so
that a compile action depends only on the compiler it runs.
Most users register toolchains via the rust module extension (see
Bzlmod) rather than declaring these rules directly. The rules
below exist for users who need to define custom toolchains — for example, to point
at a locally built rustc or to add a target triple that the extension doesn't
cover.
Toolchain rules
- rust_toolchain — Declare a Rust compilation toolchain: the
rustcbinary, standard library, linker, and per-target compilation settings. Only what every compile action needs lives here; the tools below have toolchains of their own so their binaries stay out of compile inputs. - rustdoc_toolchain — Declare a toolchain providing the
rustdocbinary used by rust_doc and rust_doc_test. Build scripts do not see it unless a cargo_build_script lists it intoolchainsand maps$(RUSTDOC)inbuild_script_env. Therustmodule extension registers one next to everyrust_toolchain, from the same distribution, sincerustdocmust matchrustcexactly. Therust_docattribute ofrust_toolchainis deprecated in its favor and is only consulted when norustdoc_toolchainis registered. - clippy_toolchain — Declare a toolchain providing the
clippy-driver(and optionallycargo-clippy) binary used by the clippy rules. Registered next to everyrust_toolchainin the same way. Theclippy_driverandcargo_clippyattributes ofrust_toolchainare deprecated in its favor and are only consulted when noclippy_toolchainis registered. - rustfmt_toolchain — Declare a toolchain providing the
rustfmtbinary used by rustfmt rules. - rust_analyzer_toolchain — Declare a toolchain
providing the
rust-analyzerbinary and proc-macro server used by the rust_analyzer integration. - cargo_toolchain — Declare a toolchain providing the
cargobinary used by rules which run Cargo, such as cargo_build_script and crates_vendor. Therustmodule extension declares one in the repository of everyrust_toolchainit registers and registers the two together, so Cargo always comes from the same release asrustc; the toolchain carries the sameversion,iso_dateandchannelidentifiers andcargo_build_scriptfails when they differ. Thecargoattribute ofrust_toolchainis deprecated in its favor and is only consulted when nocargo_toolchainis registered.
Rule author helpers
rust_common carries the label of every toolchain type rules_rust defines:
toolchain_type, rustdoc_toolchain_type, clippy_toolchain_type,
rustfmt_toolchain_type, rust_analyzer_toolchain_type and
cargo_toolchain_type. A rule declares the ones it needs in toolchains, for
example config_common.toolchain_type(rust_common.clippy_toolchain_type, mandatory = False), and reads them back with ctx.toolchains[...].
While the deprecated rust_doc, clippy_driver, cargo_clippy and cargo
attributes of rust_toolchain remain, the matching
find_rustdoc,
find_clippy and
find_cargo helpers prefer the registered
toolchain and fall back to those attributes.
Data rules
- rust_stdlib_filegroup — Group the files of a Rust
standard library archive into a target that can be attached to a
rust_toolchainvia therust_stdattribute.