This module provides a single place for all aspects, rules, and macros that are meant to have stardoc generated documentation.

Rules

rust_stdlib_filegroup

A dedicated filegroup-like rule for Rust stdlib artifacts.

name

A unique name for this target.

srcs

The list of targets/files that are components of the rust-stdlib file group


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.

name

A unique name for this target.

allocator_library

Target that provides allocator functions when rust_library targets are embedded in a cc_binary.

binary_ext

The extension for binaries created from rustc.

cargo

The location of the cargo binary. Can be a direct source or a filegroup containing one item.

clippy_driver

The location of the clippy-driver binary. Can be a direct source or a filegroup containing one item.

debug_info

Rustc debug info levels per opt level

default_edition

The edition to use for rust_* rules that don't specify an edition.

dylib_ext

The extension for dynamic libraries created from rustc.

exec_triple

The platform triple for the toolchains execution environment. For more details see: https://docs.bazel.build/versions/master/skylark/rules.html#configurations

opt_level

Rustc optimization levels.

os

The operating system for the current toolchain

rust_doc

The location of the rustdoc binary. Can be a direct source or a filegroup containing one item.

rust_lib

The rust standard library.

rustc

The location of the rustc binary. Can be a direct source or a filegroup containing one item.

rustc_lib

The libraries used by rustc during compilation.

rustc_srcs

The source code of rustc.

rustfmt

The location of the rustfmt binary. Can be a direct source or a filegroup containing one item.

staticlib_ext

The extension for static libraries created from rustc.

stdlib_linkflags

Additional linker flags to use when Rust std lib is linked by a C++ linker (rustc will deal with these automatically). Subject to location expansion with respect to the srcs of the rust_lib attribute.

target_json

Override the target_triple with a custom target specification. For more details see: https://doc.rust-lang.org/rustc/targets/custom.html

target_triple

The platform triple for the toolchains target environment. For more details see: https://docs.bazel.build/versions/master/skylark/rules.html#configurations


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.

name

A unique name for this repository.

auth

Auth object compatible with repository_ctx.download to use when downloading files. See https://docs.bazel.build/versions/main/skylark/lib/repository_ctx.html#download for more details.

dev_components

Whether to download the rustc-dev components (defaults to False). Requires version to be "nightly".

edition

The rust edition to be used by default.

exec_triple

The Rust-style target that this compiler runs on

extra_target_triples

Additional rust-style targets that this set of toolchains should support.

include_rustc_srcs

Whether to download and unpack the rustc source files. These are very large, and slow to unpack, but are required to support rust analyzer. An environment variable RULES_RUST_TOOLCHAIN_INCLUDE_RUSTC_SRCS can also be used to control this attribute. This variable will take precedence over the hard coded attribute. Setting it to true to activates this attribute where all other values deactivate it.

iso_date

The date of the tool (or None, if the version is a specific version).

repo_mapping

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).

rustfmt_version

The version of the tool among "nightly", "beta", or an exact version.

sha256s

A dict associating tool subdirectories to sha256 hashes. See rust_repositories for more details.

toolchain_name_prefix

The per-target prefix expected for the rust_toolchain declarations in the parent workspace.

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).

version

The version of the tool among "nightly", "beta", or an exact version.


rust_toolchain_repository_proxy

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

name

A unique name for this repository.

exec_triple

The Rust-style target triple for the compilation platform

extra_target_triples

The Rust-style triples for extra compilation targets

parent_workspace_name

The name of the other rust_toolchain_repository

repo_mapping

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).

toolchain_name_prefix

The per-target prefix expected for the rust_toolchain declarations in the parent workspace.


Macros and Functions

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.

version

The version of Rust. Either "nightly", "beta", or an exact version. Defaults to a modern version.

iso_date

The date of the nightly or beta release (ignored if the version is a specific version).

rustfmt_version

The version of rustfmt. Either "nightly", "beta", or an exact version. Defaults to version if not specified.

edition

The rust edition to be used by default (2015, 2018 (default), or 2021)

dev_components

Whether to download the rustc-dev components (defaults to False). Requires version to be "nightly".

sha256s

A dict associating tool subdirectories to sha256 hashes. Defaults to None.

include_rustc_srcs

Whether to download rustc's src code. This is required in order to use rust-analyzer support. See rust_toolchain_repository.include_rustc_srcs. for more details

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']


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.

name

The name of the generated repository

version

The version of the tool among "nightly", "beta', or an exact version.

exec_triple

The Rust-style target that this compiler runs on

include_rustc_srcs

Whether to download rustc's src code. This is required in order to use rust-analyzer support. Defaults to 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.

rustfmt_version

The version of rustfmt to be associated with the toolchain. Defaults to None.

edition

The rust edition to be used by default (2015, 2018 (if None), or 2021).

dev_components

Whether to download the rustc-dev components. Requires version to be "nightly". Defaults to False.

sha256s

A dict associating tool subdirectories to sha256 hashes. See rust_repositories for more details.

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']

auth

Auth object compatible with repository_ctx.download to use when downloading files. See https://docs.bazel.build/versions/main/skylark/lib/repository_ctx.html#download for more details.