rustdoc_toolchain.bzl
rustdoc_toolchain
load("@rules_rust//rust:rustdoc_toolchain.bzl", "rustdoc_toolchain")
rustdoc_toolchain(name, channel, extra_rustdoc_flags, iso_date, rust_toolchain, rustdoc, version)
A toolchain providing rustdoc.
rust_doc and rust_doc_test resolve @rules_rust//rust/rustdoc:toolchain_type
and run the rustdoc it provides. Build scripts do not see it by default; a
cargo_build_script which needs rustdoc lists
@rules_rust//rust/toolchain:current_rustdoc_toolchain in toolchains and sets
RUSTDOC to $(RUSTDOC) in build_script_env.
The toolchain derives its sysroot from the one of its rust_toolchain: the
same rustc, libraries and standard library, plus bin/rustdoc. rustdoc is
a rustc driver which loads librustc_driver from beside itself and builds
doctests with the rustc beside itself, so actions running rustdoc use the
derived sysroot, and that sysroot is complete even where symlinks are
materialized as copies.
rustdoc must come from the same Rust release as rustc. The rust module
extension declares one rustdoc_toolchain in the repository of every
rust_toolchain it registers, bound to it through rust_toolchain, and
registers the two together. A rustdoc_toolchain which leaves
rust_toolchain unset derives from the rust_toolchain resolved for
@rules_rust//rust:toolchain_type instead and states its release through
version, iso_date and channel, which the resolved toolchain must agree
with; the two ways exclude each other. Either way the toolchain advertises
the version, iso_date and channel of the rust_toolchain it derives
from. A rule which runs rustdoc resolves both toolchain types and
find_rustdoc checks that the rustdoc_toolchain derives from the
rust_toolchain the rule resolved. When it does not, as when a
rust_toolchain is registered on its own ahead of the generated ones, the
rule falls back to the deprecated rust_doc of that rust_toolchain, or
fails when it is unset. That attribute is deprecated in favor of this rule and
is consulted only in that case or when no rustdoc_toolchain is registered at
all.
$(RUSTDOC) and $(RUSTDOC_RLOCATIONPATH) are available as Make variables to
targets which list @rules_rust//rust/toolchain:current_rustdoc_toolchain, a
rustdoc_toolchain_alias, in toolchains.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| channel | The Rust release channel rustdoc comes from (stable, nightly, or beta), as in rust_toolchain.channel. | String | optional | "" |
| extra_rustdoc_flags | Extra flags to pass to rustdoc. They follow the rust_toolchain's extra_rustc_flags and precede the flags of the target and the command line. Subject to Make variable expansion with respect to the rust_toolchain's variables (RUST_SYSROOT, RUSTC, ...) and RUSTDOC. | List of strings | optional | [] |
| iso_date | The ISO date of the nightly or beta release rustdoc comes from, as in rust_toolchain.iso_date. Empty for stable releases. | String | optional | "" |
| rust_toolchain | The rust_toolchain whose sysroot this toolchain derives its own from, normally the one declared beside it over the same release. Exclusive with version, iso_date and channel: when unset the rust_toolchain resolved for @rules_rust//rust:toolchain_type is used instead and version is required, so that the resolved toolchain can be checked to come from the same release. | Label | optional | None |
| rustdoc | The rustdoc binary. Can be a direct source or a filegroup containing one item. | Label | required | |
| version | The version of the Rust release rustdoc comes from (e.g. 1.94.1), as in rust_toolchain.version. Required when rust_toolchain is unset, and not allowed with it. The resolved rust_toolchain must agree on version, iso_date and channel wherever both state them. | String | optional | "" |
rustdoc_toolchain_alias
load("@rules_rust//rust:rustdoc_toolchain.bzl", "rustdoc_toolchain_alias")
rustdoc_toolchain_alias(name, mandatory)
A target standing in for the rustdoc_toolchain resolved for the current platform.
The alias forwards the toolchain's providers, its Make variables ($(RUSTDOC),
$(RUSTDOC_RLOCATIONPATH)) and its files: the sysroot rustdoc runs from, so
that it runs from a genrule's tools on any executor.
@rules_rust//rust/toolchain:current_rustdoc_toolchain is the alias
rules_rust declares.
This follows cc_toolchain_alias from rules_cc.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| mandatory | Whether to fail when no toolchain is registered. When False, the target provides nothing instead. | Boolean | optional | True |
find_rustdoc
load("@rules_rust//rust:rustdoc_toolchain.bzl", "find_rustdoc")
find_rustdoc(ctx, rust_toolchain)
The rustdoc_toolchain a rule should run rustdoc from.
The registered rustdoc_toolchain is preferred when its sysroot derives
from the rust_toolchain the rule resolved. When it derives from another
one, or none is registered, an equivalent toolchain is made from the
deprecated rust_doc of the rust_toolchain, running from that
toolchain's sysroot, which is how rules found rustdoc before
@rules_rust//rust/rustdoc:toolchain_type existed. A rustdoc_toolchain
of another rust_toolchain with nothing to fall back to is an error: its
rustdoc would load that other rustc's libraries.
PARAMETERS
RETURNS
ToolchainInfo: A rustdoc_toolchain, or None when neither toolchain provides rustdoc.