Skip to content

rust_repositories.md

Latest commit

 

History

History
242 lines (176 loc) · 22.1 KB

rust_repositories.md

File metadata and controls

242 lines (176 loc) · 22.1 KB
Raw

Rust Repositories

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, clippy_driver, debug_info,
               default_edition, dylib_ext, exec_triple, opt_level, os, rust_doc, rust_lib, rustc,
               rustc_lib, rustc_srcs, rustfmt, staticlib_ext, stdlib_linkflags, 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:

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 "2018"
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_srcs 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_json Override the target_triple with a custom target specification. For more details see: https://doc.rust-lang.org/rustc/targets/custom.html Label optional None
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

rust_toolchain_repository(name, auth, dev_components, edition, exec_triple, extra_target_triples,
                          include_rustc_srcs, iso_date, repo_mapping, rustfmt_version, sha256s,
                          toolchain_name_prefix, 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 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
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. Dictionary: String -> String 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. String optional "2018"
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_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. 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

rust_toolchain_repository_proxy(name, exec_triple, extra_target_triples, parent_workspace_name,
                                repo_mapping, toolchain_name_prefix)

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

rust_repositories(version, iso_date, rustfmt_version, edition, dev_components, sha256s,
                  include_rustc_srcs, urls)

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.56.0"
iso_date The date of the nightly or beta release (ignored 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, 2018 (default), or 2021) 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_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 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

rust_repository_set(name, version, exec_triple, include_rustc_srcs, extra_target_triples, iso_date,
                    rustfmt_version, edition, dev_components, sha256s, urls, auth)

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_srcs 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, 2018 (if None), or 2021). 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"]
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. None