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('@io_bazel_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 @io_bazel_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 | |
| 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 | {“opt”: “0”, “dbg”: “2”, “fastbuild”: “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 | {“opt”: “3”, “dbg”: “0”, “fastbuild”: “0”} |
| 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 |
| 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 | "" |
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 | [] |
| iso_date | The date of the tool (or None, if the version is a specific version). | String | optional | "" |
| 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 | "" |
| version | The version of the tool among “nightly”, “beta”, or an exact version. | String | required |
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 | |
| toolchain_name_prefix | The per-target prefix expected for the rust_toolchain declarations in the parent workspace. | String | optional | "" |
Emits a default set of toolchains for Linux, OSX, 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 @io_bazel_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. | “1.44.0” |
| 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. | “1.4.18” |
| 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. | None |
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 |
| 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 |