# Rust Repositories
* [rules_rust_dependencies](#rules_rust_dependencies)
* [rust_analyzer_toolchain_repository](#rust_analyzer_toolchain_repository)
* [rust_register_toolchains](#rust_register_toolchains)
* [rust_repositories](#rust_repositories)
* [rust_repository_set](#rust_repository_set)
* [rust_stdlib_filegroup](#rust_stdlib_filegroup)
* [rust_toolchain_repository_proxy](#rust_toolchain_repository_proxy)
* [rust_toolchain_repository](#rust_toolchain_repository)
* [rust_toolchain_tools_repository](#rust_toolchain_tools_repository)
* [rust_toolchain](#rust_toolchain)
## rust_stdlib_filegroup
rust_stdlib_filegroup(name, srcs)
A dedicated filegroup-like rule for Rust stdlib artifacts.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| srcs | The list of targets/files that are components of the rust-stdlib file group | List of labels | required | |
## rust_toolchain
rust_toolchain(name, allocator_library, binary_ext, cargo, cargo_clippy, clippy_driver, debug_info,
default_edition, dylib_ext, env, exec_triple, experimental_link_std_dylib,
experimental_use_cc_common_link, extra_exec_rustc_flags, extra_rustc_flags,
extra_rustc_flags_for_crate_types, global_allocator_library, llvm_cov, llvm_profdata,
llvm_tools, opt_level, per_crate_rustc_flags, rust_doc, rust_std, rustc, rustc_lib,
rustfmt, staticlib_ext, stdlib_linkflags, strip_level, target_json, target_triple)
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:
```python
load('@rules_rust//rust:toolchain.bzl', 'rust_toolchain')
rust_toolchain(
name = "rust_cpuX_impl",
binary_ext = "",
dylib_ext = ".so",
exec_triple = "cpuX-unknown-linux-gnu",
rust_doc = "@rust_cpuX//:rustdoc",
rust_std = "@rust_cpuX//:rust_std",
rustc = "@rust_cpuX//:rustc",
rustc_lib = "@rust_cpuX//:rustc_lib",
staticlib_ext = ".a",
stdlib_linkflags = ["-lpthread", "-ldl"],
target_triple = "cpuX-unknown-linux-gnu",
)
toolchain(
name = "rust_cpuX",
exec_compatible_with = [
"@platforms//cpu:cpuX",
"@platforms//os:linux",
],
target_compatible_with = [
"@platforms//cpu:cpuX",
"@platforms//os:linux",
],
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 | `"@rules_rust//ffi/cc/allocator_library"` |
| 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` |
| cargo_clippy | The location of the `cargo_clippy` 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. If absent, every rule is required to specify its `edition` attribute. | String | optional | `""` |
| dylib_ext | The extension for dynamic libraries created from rustc. | String | required | |
| env | Environment variables to set in actions. | Dictionary: String -> String | optional | `{}` |
| 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 | required | |
| experimental_link_std_dylib | Label to a boolean build setting that controls whether whether to link libstd dynamically. | Label | optional | `"@rules_rust//rust/settings:experimental_link_std_dylib"` |
| experimental_use_cc_common_link | Label to a boolean build setting that controls whether cc_common.link is used to link rust binaries. | Label | optional | `"@rules_rust//rust/settings:experimental_use_cc_common_link"` |
| extra_exec_rustc_flags | Extra flags to pass to rustc in exec configuration | List of strings | optional | `[]` |
| extra_rustc_flags | Extra flags to pass to rustc in non-exec configuration. Subject to location expansion with respect to the srcs of the `rust_std` attribute. | List of strings | optional | `[]` |
| extra_rustc_flags_for_crate_types | Extra flags to pass to rustc based on crate type | Dictionary: String -> List of strings | optional | `{}` |
| global_allocator_library | Target that provides allocator functions for when a global allocator is present. | Label | optional | `"@rules_rust//ffi/cc/global_allocator_library"` |
| llvm_cov | The location of the `llvm-cov` binary. Can be a direct source or a filegroup containing one item. If None, rust code is not instrumented for coverage. | Label | optional | `None` |
| llvm_profdata | The location of the `llvm-profdata` binary. Can be a direct source or a filegroup containing one item. If `llvm_cov` is None, this can be None as well and rust code is not instrumented for coverage. | Label | optional | `None` |
| llvm_tools | LLVM tools that are shipped with the Rust toolchain. | Label | optional | `None` |
| opt_level | Rustc optimization levels. | Dictionary: String -> String | optional | `{"dbg": "0", "fastbuild": "0", "opt": "3"}` |
| per_crate_rustc_flags | Extra flags to pass to rustc in non-exec configuration | List of strings | optional | `[]` |
| rust_doc | The location of the `rustdoc` binary. Can be a direct source or a filegroup containing one item. | Label | required | |
| rust_std | The Rust standard library. | Label | required | |
| rustc | The location of the `rustc` binary. Can be a direct source or a filegroup containing one item. | Label | required | |
| rustc_lib | The libraries used by rustc during compilation. | Label | optional | `None` |
| rustfmt | **Deprecated**: Instead see [rustfmt_toolchain](#rustfmt_toolchain) | Label | optional | `None` |
| staticlib_ext | The extension for static libraries created from rustc. | String | required | |
| stdlib_linkflags | Additional linker flags to use when Rust standard library is linked by a C++ linker (rustc will deal with these automatically). Subject to location expansion with respect to the srcs of the `rust_std` attribute. | List of strings | required | |
| strip_level | Rustc strip levels. For all potential options, see https://doc.rust-lang.org/rustc/codegen-options/index.html#strip | Dictionary: String -> String | optional | `{"dbg": "none", "fastbuild": "none", "opt": "debuginfo"}` |
| target_json | Override the target_triple with a custom target specification. For more details see: https://doc.rust-lang.org/rustc/targets/custom.html | String | optional | `""` |
| 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 | `""` |
## rules_rust_dependencies
rules_rust_dependencies()
Dependencies used in the implementation of `rules_rust`.
## rust_analyzer_toolchain_repository
rust_analyzer_toolchain_repository(name, version, exec_compatible_with, target_compatible_with,
iso_date, sha256s, urls, auth, netrc, auth_patterns)
Assemble a remote rust_analyzer_toolchain target based on the given params.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| name | The name of the toolchain proxy repository contianing the registerable toolchain. | none |
| version | The version of the tool among "nightly", "beta', or an exact version. | none |
| exec_compatible_with | A list of constraints for the execution platform for this toolchain. | `[]` |
| target_compatible_with | A list of constraints for the target platform for this toolchain. | `[]` |
| iso_date | The date of the tool. | `None` |
| sha256s | A dict associating tool subdirectories to sha256 hashes. See [rust_register_toolchains](#rust_register_toolchains) 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.xz'] | `None` |
| auth | Auth object compatible with repository_ctx.download to use when downloading files. See [repository_ctx.download](https://docs.bazel.build/versions/main/skylark/lib/repository_ctx.html#download) for more details. | `None` |
| netrc | .netrc file to use for authentication; mirrors the eponymous attribute from http_archive | `None` |
| auth_patterns | Override mapping of hostnames to authorization patterns; mirrors the eponymous attribute from http_archive | `None` |
**RETURNS**
str: The name of a registerable rust_analyzer_toolchain.
## rust_register_toolchains
rust_register_toolchains(dev_components, edition, allocator_library, global_allocator_library,
iso_date, register_toolchains, rustfmt_version, rust_analyzer_version,
sha256s, extra_target_triples, extra_rustc_flags, extra_exec_rustc_flags,
urls, version, versions)
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 `sha256s` attribute represents a dict associating tool subdirectories to sha256 hashes. As an example:
```python
{
"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 |
| :------------- | :------------- | :------------- |
| dev_components | Whether to download the rustc-dev components (defaults to False). Requires version to be "nightly". | `False` |
| edition | The rust edition to be used by default (2015, 2018, or 2021). If absent, every target is required to specify its `edition` attribute. | `None` |
| allocator_library | Target that provides allocator functions when rust_library targets are embedded in a cc_binary. | `None` |
| global_allocator_library | Target that provides allocator functions when global allocator is used with cc_common.link. | `None` |
| iso_date | **Deprecated**: Use `versions` instead. | `None` |
| register_toolchains | If true, repositories will be generated to produce and register `rust_toolchain` targets. | `True` |
| rustfmt_version | The version of rustfmt. If none is supplied and only a single version in `versions` is given, then this defaults to that version, otherwise will default to the default nightly version. | `None` |
| rust_analyzer_version | The version of Rustc to pair with rust-analyzer. | `None` |
| sha256s | A dict associating tool subdirectories to sha256 hashes. | `None` |
| extra_target_triples | Additional rust-style targets that rust toolchains should support. | `["wasm32-unknown-unknown", "wasm32-wasi"]` |
| extra_rustc_flags | Dictionary of target triples to list of extra flags to pass to rustc in non-exec configuration. | `None` |
| extra_exec_rustc_flags | Extra flags to pass to rustc in exec configuration. | `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). | `["https://static.rust-lang.org/dist/{}.tar.xz"]` |
| version | **Deprecated**: Use `versions` instead. | `None` |
| versions | A list of toolchain versions to download. This paramter only accepts one versions per channel. E.g. `["1.65.0", "nightly/2022-11-02", "beta/2020-12-30"]`. | `[]` |
## rust_repositories
rust_repositories(kwargs)
**Deprecated**: Use [rules_rust_dependencies](#rules_rust_dependencies) and [rust_register_toolchains](#rust_register_toolchains) directly.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| kwargs | Keyword arguments for the `rust_register_toolchains` macro. | none |
## rust_repository_set
rust_repository_set(name, exec_triple, target_settings, version, versions, allocator_library,
global_allocator_library, extra_target_triples, iso_date, rustfmt_version,
edition, dev_components, extra_rustc_flags, extra_exec_rustc_flags, opt_level,
sha256s, urls, auth, netrc, auth_patterns, register_toolchain,
exec_compatible_with, default_target_compatible_with)
Assembles a remote repository for the given toolchain params, produces a proxy repository to contain the toolchain declaration, and registers the toolchains.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| name | The name of the generated repository | none |
| exec_triple | The Rust-style target that this compiler runs on | none |
| target_settings | A list of config_settings that must be satisfied by the target configuration in order for this set of toolchains to be selected during toolchain resolution. | `[]` |
| version | The version of the tool among "nightly", "beta', or an exact version. | `None` |
| versions | A list of toolchain versions to download. This paramter only accepts one versions per channel. E.g. `["1.65.0", "nightly/2022-11-02", "beta/2020-12-30"]`. | `[]` |
| allocator_library | Target that provides allocator functions when rust_library targets are embedded in a cc_binary. | `None` |
| global_allocator_library | Target that provides allocator functions a global allocator is used with cc_common.link. | `None` |
| extra_target_triples | Additional rust-style targets that this set of toolchains should support. If a map, values should be (optional) target_compatible_with lists for that particular target triple. | `{}` |
| iso_date | The date of the tool. | `None` |
| rustfmt_version | The version of rustfmt to be associated with the toolchain. | `None` |
| edition | The rust edition to be used by default (2015, 2018, or 2021). If absent, every rule is required to specify its `edition` attribute. | `None` |
| dev_components | Whether to download the rustc-dev components. Requires version to be "nightly". | `False` |
| extra_rustc_flags | Dictionary of target triples to list of extra flags to pass to rustc in non-exec configuration. | `None` |
| extra_exec_rustc_flags | Extra flags to pass to rustc in exec configuration. | `None` |
| opt_level | Dictionary of target triples to optimiztion config. | `None` |
| sha256s | A dict associating tool subdirectories to sha256 hashes. See [rust_register_toolchains](#rust_register_toolchains) 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). | `["https://static.rust-lang.org/dist/{}.tar.xz"]` |
| auth | Auth object compatible with repository_ctx.download to use when downloading files. See [repository_ctx.download](https://docs.bazel.build/versions/main/skylark/lib/repository_ctx.html#download) for more details. | `None` |
| netrc | .netrc file to use for authentication; mirrors the eponymous attribute from http_archive | `None` |
| auth_patterns | Override mapping of hostnames to authorization patterns; mirrors the eponymous attribute from http_archive | `None` |
| register_toolchain | If True, the generated `rust_toolchain` target will become a registered toolchain. | `True` |
| exec_compatible_with | A list of constraints for the execution platform for this toolchain. | `None` |
| default_target_compatible_with | A list of constraints for the target platform for this toolchain when the exec platform is the same as the target platform. | `None` |
## rust_toolchain_repository
rust_toolchain_repository(name, version, exec_triple, target_triple, exec_compatible_with,
target_compatible_with, target_settings, channel, allocator_library,
global_allocator_library, iso_date, rustfmt_version, edition,
dev_components, extra_rustc_flags, extra_exec_rustc_flags, opt_level,
sha256s, urls, auth, netrc, auth_patterns)
Assembles a remote repository for the given toolchain params, produces a proxy repository to contain the toolchain declaration, and registers the toolchains.
**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 |
| target_triple | The Rust-style target to build for. | none |
| exec_compatible_with | A list of constraints for the execution platform for this toolchain. | `None` |
| target_compatible_with | A list of constraints for the target platform for this toolchain. | `None` |
| target_settings | A list of config_settings that must be satisfied by the target configuration in order for this toolchain to be selected during toolchain resolution. | `[]` |
| channel | The channel of the Rust toolchain. | `None` |
| allocator_library | Target that provides allocator functions when rust_library targets are embedded in a cc_binary. | `None` |
| global_allocator_library | Target that provides allocator functions when a global allocator is used with cc_common.link. | `None` |
| iso_date | The date of the tool. | `None` |
| rustfmt_version | The version of rustfmt to be associated with the toolchain. | `None` |
| edition | The rust edition to be used by default (2015, 2018, or 2021). If absent, every rule is required to specify its `edition` attribute. | `None` |
| dev_components | Whether to download the rustc-dev components. Requires version to be "nightly". Defaults to False. | `False` |
| extra_rustc_flags | Extra flags to pass to rustc in non-exec configuration. | `None` |
| extra_exec_rustc_flags | Extra flags to pass to rustc in exec configuration. | `None` |
| opt_level | Optimization level config for this toolchain. | `None` |
| sha256s | A dict associating tool subdirectories to sha256 hashes. See [rust_register_toolchains](#rust_register_toolchains) 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.xz'] | `["https://static.rust-lang.org/dist/{}.tar.xz"]` |
| auth | Auth object compatible with repository_ctx.download to use when downloading files. See [repository_ctx.download](https://docs.bazel.build/versions/main/skylark/lib/repository_ctx.html#download) for more details. | `None` |
| netrc | .netrc file to use for authentication; mirrors the eponymous attribute from http_archive | `None` |
| auth_patterns | A list of patterns to match against urls for which the auth object should be used. | `None` |
**RETURNS**
str: The name of the registerable toolchain created by this rule.
## rust_toolchain_repository_proxy
rust_toolchain_repository_proxy(name, exec_compatible_with, repo_mapping, target_compatible_with,
target_settings, toolchain, toolchain_type)
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_compatible_with | A list of constraints for the execution platform for this toolchain. | List of strings | optional | `[]` |
| repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.
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`).
This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | Dictionary: String -> String | optional | |
| target_compatible_with | A list of constraints for the target platform for this toolchain. | List of strings | optional | `[]` |
| target_settings | A list of config_settings that must be satisfied by the target configuration in order for this toolchain to be selected during toolchain resolution. | List of strings | optional | `[]` |
| toolchain | The name of the toolchain implementation target. | String | required | |
| toolchain_type | The toolchain type of the toolchain to declare | String | required | |
## rust_toolchain_tools_repository
rust_toolchain_tools_repository(name, allocator_library, auth, auth_patterns, dev_components,
edition, exec_triple, extra_exec_rustc_flags, extra_rustc_flags,
global_allocator_library, iso_date, netrc, opt_level, repo_mapping,
rustfmt_version, sha256s, target_triple, urls, version)
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 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 | |
| allocator_library | Target that provides allocator functions when rust_library targets are embedded in a cc_binary. | String | optional | `"@rules_rust//ffi/cc/allocator_library"` |
| auth | Auth object compatible with repository_ctx.download to use when downloading files. See [repository_ctx.download](https://docs.bazel.build/versions/main/skylark/lib/repository_ctx.html#download) for more details. | Dictionary: String -> String | optional | `{}` |
| auth_patterns | A list of patterns to match against urls for which the auth object should be used. | List of strings | optional | `[]` |
| 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 (2015, 2018, or 2021). If absent, every rule is required to specify its `edition` attribute. | String | optional | `""` |
| exec_triple | The Rust-style target that this compiler runs on | String | required | |
| extra_exec_rustc_flags | Extra flags to pass to rustc in exec configuration | List of strings | optional | `[]` |
| extra_rustc_flags | Extra flags to pass to rustc in non-exec configuration | List of strings | optional | `[]` |
| global_allocator_library | Target that provides allocator functions when a global allocator is used with cc_common.link. | String | optional | `"@rules_rust//ffi/cc/global_allocator_library"` |
| iso_date | The date of the tool (or None, if the version is a specific version). | String | optional | `""` |
| netrc | .netrc file to use for authentication; mirrors the eponymous attribute from http_archive | String | optional | `""` |
| opt_level | Rustc optimization levels. For more details see the documentation for `rust_toolchain.opt_level`. | Dictionary: String -> String | optional | `{}` |
| repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.
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`).
This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | Dictionary: String -> 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_register_toolchains](#rust_register_toolchains) for more details. | Dictionary: String -> String | optional | `{}` |
| target_triple | The Rust-style target that this compiler builds for. | String | required | |
| 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.xz"]` |
| version | The version of the tool among "nightly", "beta", or an exact version. | String | required | |