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

NameDescriptionTypeMandatoryDefault
nameA unique name for this target.Namerequired
channelThe Rust release channel rustdoc comes from (stable, nightly, or beta), as in rust_toolchain.channel.Stringoptional""
extra_rustdoc_flagsExtra 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 stringsoptional[]
iso_dateThe ISO date of the nightly or beta release rustdoc comes from, as in rust_toolchain.iso_date. Empty for stable releases.Stringoptional""
rust_toolchainThe 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.LabeloptionalNone
rustdocThe rustdoc binary. Can be a direct source or a filegroup containing one item.Labelrequired
versionThe 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.Stringoptional""

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

NameDescriptionTypeMandatoryDefault
nameA unique name for this target.Namerequired
mandatoryWhether to fail when no toolchain is registered. When False, the target provides nothing instead.BooleanoptionalTrue

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

NameDescriptionDefault Value
ctxThe rule context. The rule must list config_common.toolchain_type(rust_common.rustdoc_toolchain_type, mandatory = False) in toolchains.none
rust_toolchainThe resolved rust_toolchain, or None.none

RETURNS

ToolchainInfo: A rustdoc_toolchain, or None when neither toolchain provides rustdoc.