cargo_toolchain.bzl

cargo_toolchain

load("@rules_rust//cargo:cargo_toolchain.bzl", "cargo_toolchain")

cargo_toolchain(name, cargo, channel, iso_date, version)

A toolchain providing a Cargo binary.

Rules which run Cargo on the execution platform, such as crates_vendor and cargo_build_script, resolve @rules_rust//cargo:toolchain_type and use the binary it provides. The toolchain carries Cargo alone, so compile actions, which never run Cargo, do not depend on it.

Cargo is released together with rustc and is only tested against the compiler it shipped with, so the rust module extension declares a cargo_toolchain in the same repository as every rust_toolchain it registers and registers the two with the same constraints and channel setting. The toolchain carries the same version, iso_date and channel identifiers as rust_toolchain; cargo_build_script fails when the Cargo and Rust toolchains it resolves state different ones.

$(CARGO) and $(CARGO_RLOCATIONPATH) are available as Make variables to targets which list @rules_rust//cargo:current_cargo_toolchain, a cargo_toolchain_alias, in toolchains.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
cargo	The `cargo` binary. Can be a direct source or a filegroup containing one item.	Label	required
channel	The Rust release channel Cargo comes from (`stable`, `nightly`, or `beta`), as in `rust_toolchain.channel`.	String	optional	`""`
iso_date	The ISO date of the nightly or beta release Cargo comes from, as in `rust_toolchain.iso_date`. Empty for stable releases.	String	optional	`""`
version	The version of the Rust release Cargo comes from (e.g. `1.94.1`), as in `rust_toolchain.version`. Rules which run Cargo next to `rustc` compare the two; leave empty to opt out.	String	optional	`""`

cargo_toolchain_alias

load("@rules_rust//cargo:cargo_toolchain.bzl", "cargo_toolchain_alias")

cargo_toolchain_alias(name, mandatory)

A target standing in for the cargo_toolchain resolved for the current platform.

The alias forwards the toolchain's providers, its Make variables ($(CARGO), $(CARGO_RLOCATIONPATH)) and the cargo binary. @rules_rust//cargo:current_cargo_toolchain is the alias rules_rust declares. While the deprecated cargo attribute of rust_toolchain exists, the alias stands in for it when no cargo_toolchain is registered.

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_cargo

load("@rules_rust//cargo:cargo_toolchain.bzl", "find_cargo")

find_cargo(ctx, rust_toolchain)

The Cargo binary a rule should run, and the files it needs at run time.

The registered cargo_toolchain is preferred. When none is registered the cargo of the rust_toolchain is used, which is how rules found Cargo before @rules_rust//cargo:toolchain_type existed.

PARAMETERS

Name	Description	Default Value
ctx	The rule context. The rule must list `config_common.toolchain_type(rust_common.cargo_toolchain_type, mandatory = False)` in `toolchains`.	none
rust_toolchain	The resolved `rust_toolchain`, or `None`.	none

RETURNS

struct: cargo, the binary (a File, or None when neither toolchain provides one), files, a depset to add to the action's tools, and toolchain, the cargo_toolchain used, or None when falling back.