Rust Repositories

• rust_repositories
• rust_repository_set
• rust_toolchain
• rust_toolchain_repository
• rust_toolchain_repository_proxy

rust_toolchain

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",
    rustc = "@rust_cpuX//:rustc",
    rustc_lib = "@rust_cpuX//:rustc_lib",
    rust_lib = "@rust_cpuX//:rust_lib",
    rust_doc = "@rust_cpuX//:rustdoc",
    binary_ext = "",
    staticlib_ext = ".a",
    dylib_ext = ".so",
    stdlib_linkflags = ["-lpthread", "-ldl"],
    os = "linux",
)

toolchain(
    name = "rust_cpuX",
    exec_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    target_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    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

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
allocator_library	Target that provides allocator functions when rust_library targets are embedded in a cc_binary.	Label	optional	None
binary_ext	The extension for binaries created from rustc.	String	required
cargo	The location of the cargo binary. Can be a direct source or a filegroup containing one item.	Label	optional	None
clippy_driver	The location of the clippy-driver binary. Can be a direct source or a filegroup containing one item.	Label	optional	None
debug_info	Rustc debug info levels per opt level	Dictionary: String -> String	optional	{“dbg”: “2”, “fastbuild”: “0”, “opt”: “0”}
default_edition	The edition to use for rust_* rules that don't specify an edition.	String	optional	“2015”
dylib_ext	The extension for dynamic libraries created from rustc.	String	required
exec_triple	The platform triple for the toolchains execution environment. For more details see: https://docs.bazel.build/versions/master/skylark/rules.html#configurations	String	optional	""
opt_level	Rustc optimization levels.	Dictionary: String -> String	optional	{“dbg”: “0”, “fastbuild”: “0”, “opt”: “3”}
os	The operating system for the current toolchain	String	required
rust_doc	The location of the rustdoc binary. Can be a direct source or a filegroup containing one item.	Label	optional	None
rust_lib	The rust standard library.	Label	optional	None
rustc	The location of the rustc binary. Can be a direct source or a filegroup containing one item.	Label	optional	None
rustc_lib	The libraries used by rustc during compilation.	Label	optional	None
rustc_src	The source code of rustc.	Label	optional	None
rustfmt	The location of the rustfmt binary. Can be a direct source or a filegroup containing one item.	Label	optional	None
staticlib_ext	The extension for static libraries created from rustc.	String	required
stdlib_linkflags	Additional linker libs used when std lib is linked, see https://github.com/rust-lang/rust/blob/master/src/libstd/build.rs	List of strings	required
target_triple	The platform triple for the toolchains target environment. For more details see: https://docs.bazel.build/versions/master/skylark/rules.html#configurations	String	optional	""

rust_toolchain_repository

Composes a single workspace containing the toolchain components for compiling on a given platform to a series of target platforms.

A given instance of this rule should be accompanied by a rust_toolchain_repository_proxy invocation to declare its toolchains to Bazel; the indirection allows separating toolchain selection from toolchain fetching.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
dev_components	Whether to download the rustc-dev components (defaults to False). Requires version to be “nightly”.	Boolean	optional	False
edition	The rust edition to be used by default.	String	optional	“2015”
exec_triple	The Rust-style target that this compiler runs on	String	required
extra_target_triples	Additional rust-style targets that this set of toolchains should support.	List of strings	optional	[]
include_rustc_src	Whether to download and unpack the rustc source files. These are very large, and slow to unpack, but are required to support rust analyzer.	Boolean	optional	False
iso_date	The date of the tool (or None, if the version is a specific version).	String	optional	""
repo_mapping	A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry “@foo”: “@bar” declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).	Dictionary: String -> String	required
rustfmt_version	The version of the tool among “nightly”, “beta”, or an exact version.	String	optional	""
sha256s	A dict associating tool subdirectories to sha256 hashes. See rust_repositories for more details.	Dictionary: String -> String	optional	{}
toolchain_name_prefix	The per-target prefix expected for the rust_toolchain declarations in the parent workspace.	String	optional	""
urls	A list of mirror urls containing the tools from the Rust-lang static file server. These must contain the ‘{}’ used to substitute the tool being fetched (using .format).	List of strings	optional	[“https://static.rust-lang.org/dist/{}.tar.gz”]
version	The version of the tool among “nightly”, “beta”, or an exact version.	String	required

rust_toolchain_repository_proxy

Generates a toolchain-bearing repository that declares the toolchains from some other rust_toolchain_repository.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
exec_triple	The Rust-style target triple for the compilation platform	String	required
extra_target_triples	The Rust-style triples for extra compilation targets	List of strings	optional	[]
parent_workspace_name	The name of the other rust_toolchain_repository	String	required
repo_mapping	A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry “@foo”: “@bar” declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).	Dictionary: String -> String	required
toolchain_name_prefix	The per-target prefix expected for the rust_toolchain declarations in the parent workspace.	String	optional	""

rust_repositories

Emits a default set of toolchains for Linux, MacOS, and Freebsd

Skip this macro and call the rust_repository_set macros directly if you need a compiler for other hosts or for additional target triples.

The sha256 attribute represents a dict associating tool subdirectories to sha256 hashes. As an example:

{
    "rust-1.46.0-x86_64-unknown-linux-gnu": "e3b98bc3440fe92817881933f9564389eccb396f5f431f33d48b979fa2fbdcf5",
    "rustfmt-1.4.12-x86_64-unknown-linux-gnu": "1894e76913303d66bf40885a601462844eec15fca9e76a6d13c390d7000d64b0",
    "rust-std-1.46.0-x86_64-unknown-linux-gnu": "ac04aef80423f612c0079829b504902de27a6997214eb58ab0765d02f7ec1dbc",
}

This would match for exec_triple = "x86_64-unknown-linux-gnu". If not specified, rules_rust pulls from a non-exhaustive list of known checksums..

See load_arbitrary_tool in @rules_rust//rust:repositories.bzl for more details.

PARAMETERS

Name	Description	Default Value
version	The version of Rust. Either “nightly”, “beta”, or an exact version. Defaults to a modern version.	“1.52.1”
iso_date	The date of the nightly or beta release (or None, if the version is a specific version).	None
rustfmt_version	The version of rustfmt. Either “nightly”, “beta”, or an exact version. Defaults to version if not specified.	None
edition	The rust edition to be used by default (2015 (default) or 2018)	None
dev_components	Whether to download the rustc-dev components (defaults to False). Requires version to be “nightly”.	False
sha256s	A dict associating tool subdirectories to sha256 hashes. Defaults to None.	None
include_rustc_src	Whether to download rustc's src code. This is required in order to use rust-analyzer support. Defaults to False.	False
urls	A list of mirror urls containing the tools from the Rust-lang static file server. These must contain the ‘{}’ used to substitute the tool being fetched (using .format). Defaults to [‘https://static.rust-lang.org/dist/{}.tar.gz’]	[“https://static.rust-lang.org/dist/{}.tar.gz”]

rust_repository_set

Assembles a remote repository for the given toolchain params, produces a proxy repository to contain the toolchain declaration, and registers the toolchains.

N.B. A “proxy repository” is needed to allow for registering the toolchain (with constraints) without actually downloading the toolchain.

PARAMETERS

Name	Description	Default Value
name	The name of the generated repository	none
version	The version of the tool among “nightly”, "beta', or an exact version.	none
exec_triple	The Rust-style target that this compiler runs on	none
include_rustc_src	Whether to download rustc's src code. This is required in order to use rust-analyzer support. Defaults to False.	False
extra_target_triples	Additional rust-style targets that this set of toolchains should support. Defaults to [].	[]
iso_date	The date of the tool. Defaults to None.	None
rustfmt_version	The version of rustfmt to be associated with the toolchain. Defaults to None.	None
edition	The rust edition to be used by default (2015 (if None) or 2018).	None
dev_components	Whether to download the rustc-dev components. Requires version to be “nightly”. Defaults to False.	False
sha256s	A dict associating tool subdirectories to sha256 hashes. See rust_repositories for more details.	None
urls	A list of mirror urls containing the tools from the Rust-lang static file server. These must contain the ‘{}’ used to substitute the tool being fetched (using .format). Defaults to [‘https://static.rust-lang.org/dist/{}.tar.gz’]	[“https://static.rust-lang.org/dist/{}.tar.gz”]