rules_rust

Crate Universe

Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.

Setup

After loading rules_rust in your workspace, set the following to begin using crate_universe:

load("@rules_rust//crate_universe:repositories.bzl", "crate_universe_dependencies")

crate_universe_dependencies()

Note that if the current version of rules_rust is not a release artifact, you may need to set additional flags such as bootstrap = True on the crate_universe_dependencies call above or crates_repository::generator_urls in uses of crates_repository.

Rules

Utility Macros

Workflows

The crates_repository rule (the primary repository rule of rules_rust’s cargo support) supports a number of different ways users can express and organize their dependencies. The most common are listed below though there are more to be found in the ./examples/crate_universe directory.

Cargo Workspaces

One of the simpler ways to wire up dependencies would be to first structure your project into a Cargo workspace. The crates_repository rule can ingest a root Cargo.toml file and generate dependencies from there.

load("@rules_rust//crate_universe:defs.bzl", "crates_repository")

crates_repository(
    name = "crate_index",
    cargo_lockfile = "//:Cargo.lock",
    lockfile = "//:Cargo.Bazel.lock",
    manifests = ["//:Cargo.toml"],
)

load("@crate_index//:defs.bzl", "crate_repositories")

crate_repositories()

The generated crates_repository contains helper macros which make collecting dependencies for Bazel targets simpler. Notably, the all_crate_deps and aliases macros (see Dependencies API) commonly allow the Cargo.toml files to be the single source of truth for dependencies. Since these macros come from the generated repository, the dependencies and alias definitions they return will automatically update BUILD targets.

load("@crate_index//:defs.bzl", "aliases", "all_crate_deps")
load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "lib",
    aliases = aliases(),
    deps = all_crate_deps(
        normal = True,
    ),
    proc_macro_deps = all_crate_deps(
        proc_macro = True,
    ),
)

rust_test(
    name = "unit_test",
    crate = ":lib",
    aliases = aliases(
        normal_dev = True,
        proc_macro_dev = True,
    ),
    deps = all_crate_deps(
        normal_dev = True,
    ),
    proc_macro_deps = all_crate_deps(
        proc_macro_dev = True,
    ),
)

Direct Packages

In cases where Rust targets have heavy interractions with other Bazel targests (Cc, Proto, etc.), maintaining Cargo.toml files may have deminishing returns as things like rust-analyzer begin to be confused about missing targets or environment variables defined only in Bazel. In workspaces like this, it may be desirable to have a “Cargo free” setup. crates_repository supports this through the packages attribute.

load("@rules_rust//crate_universe:defs.bzl", "crate", "crates_repository", "render_config")

crates_repository(
    name = "crate_index",
    cargo_lockfile = "//:Cargo.lock",
    lockfile = "//:Cargo.Bazel.lock",
    packages = {
        "async-trait": crate.spec(
            version = "0.1.51",
        ),
        "mockall": crate.spec(
            version = "0.10.2",
        ),
        "tokio": crate.spec(
            version = "1.12.0",
        ),
    },
    # Setting the default package name to `""` forces the use of the macros defined in this repository
    # to always use the root package when looking for dependencies or aliases. This should be considered
    # optional as the repository also exposes alises for easy access to all dependencies.
    render_config = render_config(
        default_package_name = ""
    ),
)

load("@crate_index//:defs.bzl", "crate_repositories")

crate_repositories()

Consuming dependencies may be more ergonomic in this case through the aliases defined in the new repository.

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "lib",
    deps = [
        "@crate_index//:tokio",
    ],
    proc_macro_deps = [
        "@crate_index//:async-trait",
    ],
)

rust_test(
    name = "unit_test",
    crate = ":lib",
    deps = [
        "@crate_index//:mockall",
    ],
)

Binary dependencies

Neither of the above approaches supports depending on binary-only packages.

In order to depend on a Cargo package that contains binaries and no library, you will need to do one of the following:

# in WORKSPACE.bazel

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rustfilt",
    build_file = "//rustfilt:BUILD.rustfilt.bazel",
    sha256 = "c8d748b182c8f95224336d20dcc5609598af612581ce60cfb29da4dc8d0091f2",
    strip_prefix = "rustfilt-0.2.1",
    type = "tar.gz",
    urls = ["https://crates.io/api/v1/crates/rustfilt/0.2.1/download"],
)

load("@rules_rust//crate_universe:defs.bzl", "crates_repository")

crates_repository(
    name = "rustfilt_deps",
    cargo_lockfile = "//rustfilt:Cargo.lock",
    manifests = ["@rustfilt//:Cargo.toml"],
)

load("@rustfilt_deps//:defs.bzl", rustfilt_deps = "crate_repositories")

rustfilt_deps()
# in rustfilt/BUILD.rustfilt.bazel

load("@rules_rust//rust:defs.bzl", "rust_binary")

rust_binary(
    name = "rustfilt",
    srcs = glob(["src/**/*.rs"]),
    edition = "2018",
    deps = [
        "@rustfilt_deps//:clap",
        "@rustfilt_deps//:lazy_static",
        "@rustfilt_deps//:regex",
        "@rustfilt_deps//:rustc-demangle",
    ],
)

If you use either crates_repository or crates_vendor to depend on a Cargo package that contains both a library crate and binaries, by default only the library gets made available to Bazel. To generate Bazel targets for the binary crates as well, you must opt in to it with an annotation on the package:

load("@rules_rust//crate_universe:defs.bzl", "crates_repository", "crate")

crates_repository(
    name = "crate_index",
    annotations = {
        "thepackage": [crate.annotation(
            gen_binaries = True,
            # Or, to expose just a subset of the package's binaries by name:
            gen_binaries = ["rustfilt"],
        )],
    },
    # Or, to expose every binary of every package:
    generate_binaries = True,
    ...
)

Dependencies API

After rendering dependencies, convenience macros may also be generated to provide convenient accessors to larger sections of the dependency graph.



crates_repository

crates_repository(name, annotations, cargo_config, cargo_lockfile, generate_binaries,
                  generate_build_scripts, generate_target_compatible_with, generator,
                  generator_sha256s, generator_urls, isolated, lockfile, manifests, packages, quiet,
                  render_config, repo_mapping, rust_toolchain_cargo_template,
                  rust_toolchain_rustc_template, rust_version, splicing_config,
                  supported_platform_triples)

A rule for defining and downloading Rust dependencies (crates). This rule handles all the same workflows crate_universe rules do.

Environment Variables:

variable usage
CARGO_BAZEL_GENERATOR_SHA256 The sha256 checksum of the file located at CARGO_BAZEL_GENERATOR_URL
CARGO_BAZEL_GENERATOR_URL The URL of a cargo-bazel binary. This variable takes precedence over attributes and can use file:// for local paths
CARGO_BAZEL_ISOLATED An authorative flag as to whether or not the CARGO_HOME environment variable should be isolated from the host configuration
CARGO_BAZEL_REPIN An indicator that the dependencies represented by the rule should be regenerated. REPIN may also be used. See Repinning / Updating Dependencies for more details.
CARGO_BAZEL_REPIN_ONLY A comma-delimited allowlist for rules to execute repinning. Can be useful if multiple instances of the repository rule are used in a Bazel workspace, but repinning should be limited to one of them.

Example:

Given the following workspace structure:

[workspace]/
    WORKSPACE.bazel
    BUILD.bazel
    Cargo.toml
    Cargo.Bazel.lock
    src/
        main.rs

The following is something that’d be found in the WORKSPACE file:

load("@rules_rust//crate_universe:defs.bzl", "crates_repository", "crate")

crates_repository(
    name = "crate_index",
    annotations = {
        "rand": [crate.annotation(
            default_features = False,
            features = ["small_rng"],
        )],
    },
    cargo_lockfile = "//:Cargo.Bazel.lock",
    lockfile = "//:cargo-bazel-lock.json",
    manifests = ["//:Cargo.toml"],
    # Should match the version represented by the currently registered `rust_toolchain`.
    rust_version = "1.60.0",
)

The above will create an external repository which contains aliases and macros for accessing Rust targets found in the dependency graph defined by the given manifests.

NOTE: The cargo_lockfile and lockfile must be manually created. The rule unfortunately does not yet create it on its own. When initially setting up this rule, an empty file should be created and then populated by repinning dependencies.

Repinning / Updating Dependencies

Dependency syncing and updating is done in the repository rule which means it’s done during the analysis phase of builds. As mentioned in the environments variable table above, the CARGO_BAZEL_REPIN (or REPIN) environment variables can be used to force the rule to update dependencies and potentially render a new lockfile. Given an instance of this repository rule named crate_index, the easiest way to repin dependencies is to run:

CARGO_BAZEL_REPIN=1 bazel sync --only=crate_index

This will result in all dependencies being updated for a project. The CARGO_BAZEL_REPIN environment variable can also be used to customize how dependencies are updated. The following table shows translations from environment variable values to the equivilant cargo update command that is called behind the scenes to update dependencies.

Value Cargo command
Any of [true, 1, yes, on, workspace] cargo update --workspace
Any of [full, eager, all] cargo update
package_name cargo upgrade --package package_name
package_name@1.2.3 cargo upgrade --package package_name@1.2.3
package_name@1.2.3=4.5.6 cargo upgrade --package package_name@1.2.3 --precise=4.5.6

If the crates_repository is used multiple times in the same Bazel workspace (e.g. for multiple independent Rust workspaces), it may additionally be useful to use the CARGO_BAZEL_REPIN_ONLY environment variable, which limits execution of the repinning to one or multiple instances of the crates_repository rule via a comma-delimited allowlist:

CARGO_BAZEL_REPIN=1 CARGO_BAZEL_REPIN_ONLY=crate_index bazel sync --only=crate_index

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required  
annotations Extra settings to apply to crates. See crate.annotation. Dictionary: String -> List of strings optional {}
cargo_config A Cargo configuration file Label optional None
cargo_lockfile The path used to store the crates_repository specific Cargo.lock file. In the case that your crates_repository corresponds directly with an existing Cargo.toml file which has a paired Cargo.lock file, that Cargo.lock file should be used here, which will keep the versions used by cargo and bazel in sync. Label required  
generate_binaries Whether to generate rust_binary targets for all the binary crates in every package. By default only the rust_library targets are generated. Boolean optional False
generate_build_scripts Whether or not to generate cargo build scripts by default. Boolean optional True
generate_target_compatible_with DEPRECATED: Moved to render_config. Boolean optional True
generator The absolute label of a generator. Eg. @cargo_bazel_bootstrap//:cargo-bazel. This is typically used when bootstrapping String optional ""
generator_sha256s Dictionary of host_triple -> sha256 for a cargo-bazel binary. Dictionary: String -> String optional {}
generator_urls URL template from which to download the cargo-bazel binary. {host_triple} and will be filled in according to the host platform. Dictionary: String -> String optional {}
isolated If true, CARGO_HOME will be overwritten to a directory within the generated repository in order to prevent other uses of Cargo from impacting having any effect on the generated targets produced by this rule. For users who either have multiple crate_repository definitions in a WORKSPACE or rapidly re-pin dependencies, setting this to false may improve build times. This variable is also controled by CARGO_BAZEL_ISOLATED environment variable. Boolean optional True
lockfile The path to a file to use for reproducible renderings. If set, this file must exist within the workspace (but can be empty) before this rule will work. Label optional None
manifests A list of Cargo manifests (Cargo.toml files). List of labels optional []
packages A set of crates (packages) specifications to depend on. See crate.spec. Dictionary: String -> String optional {}
quiet If stdout and stderr should not be printed to the terminal. Boolean optional True
render_config The configuration flags to use for rendering. Use //crate_universe:defs.bzl\%render_config to generate the value for this field. If unset, the defaults defined there will be used. 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  
rust_toolchain_cargo_template The template to use for finding the host cargo binary. {version} (eg. ‘1.53.0’), {triple} (eg. ‘x86_64-unknown-linux-gnu’), {arch} (eg. ‘aarch64’), {vendor} (eg. ‘unknown’), {system} (eg. ‘darwin’), {cfg} (eg. ‘exec’), {channel} (eg. ‘stable’), and {tool} (eg. ‘rustc.exe’) will be replaced in the string if present. String optional "@rust_{system}_{arch}__{triple}__{channel}_tools//:bin/{tool}"
rust_toolchain_rustc_template The template to use for finding the host rustc binary. {version} (eg. ‘1.53.0’), {triple} (eg. ‘x86_64-unknown-linux-gnu’), {arch} (eg. ‘aarch64’), {vendor} (eg. ‘unknown’), {system} (eg. ‘darwin’), {cfg} (eg. ‘exec’), {channel} (eg. ‘stable’), and {tool} (eg. ‘cargo.exe’) will be replaced in the string if present. String optional "@rust_{system}_{arch}__{triple}__{channel}_tools//:bin/{tool}"
rust_version The version of Rust the currently registered toolchain is using. Eg. 1.56.0, or nightly/2021-09-08 String optional "1.77.0"
splicing_config The configuration flags to use for splicing Cargo maniests. Use //crate_universe:defs.bzl\%rsplicing_config to generate the value for this field. If unset, the defaults defined there will be used. String optional ""
supported_platform_triples A set of all platform triples to consider when generating dependencies. List of strings optional ["aarch64-unknown-linux-gnu", "aarch64-unknown-nixos-gnu", "i686-apple-darwin", "i686-pc-windows-msvc", "i686-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc", "x86_64-unknown-linux-gnu", "x86_64-unknown-nixos-gnu", "aarch64-apple-darwin", "aarch64-apple-ios-sim", "aarch64-apple-ios", "aarch64-fuchsia", "aarch64-linux-android", "aarch64-pc-windows-msvc", "arm-unknown-linux-gnueabi", "armv7-linux-androideabi", "armv7-unknown-linux-gnueabi", "i686-linux-android", "i686-unknown-freebsd", "powerpc-unknown-linux-gnu", "riscv32imc-unknown-none-elf", "riscv64gc-unknown-none-elf", "s390x-unknown-linux-gnu", "thumbv7em-none-eabi", "thumbv8m.main-none-eabi", "wasm32-unknown-unknown", "wasm32-wasi", "x86_64-apple-ios", "x86_64-fuchsia", "x86_64-linux-android", "x86_64-unknown-freebsd", "x86_64-unknown-none", "aarch64-unknown-nto-qnx710"]

crates_vendor

crates_vendor(name, annotations, bazel, buildifier, cargo_bazel, cargo_config, cargo_lockfile,
              generate_binaries, generate_build_scripts, generate_target_compatible_with, manifests,
              mode, packages, render_config, repository_name, splicing_config,
              supported_platform_triples, vendor_path)

A rule for defining Rust dependencies (crates) and writing targets for them to the current workspace. This rule is useful for users whose workspaces are expected to be consumed in other workspaces as the rendered BUILD files reduce the number of workspace dependencies, allowing for easier loads. This rule handles all the same workflows crate_universe rules do.

Example:

Given the following workspace structure:

[workspace]/
    WORKSPACE
    BUILD
    Cargo.toml
    3rdparty/
        BUILD
    src/
        main.rs

The following is something that’d be found in 3rdparty/BUILD:

load("@rules_rust//crate_universe:defs.bzl", "crates_vendor", "crate")

crates_vendor(
    name = "crates_vendor",
    annotations = {
        "rand": [crate.annotation(
            default_features = False,
            features = ["small_rng"],
        )],
    },
    cargo_lockfile = "//:Cargo.Bazel.lock",
    manifests = ["//:Cargo.toml"],
    mode = "remote",
    vendor_path = "crates",
    tags = ["manual"],
)

The above creates a target that can be run to write BUILD files into the 3rdparty directory next to where the target is defined. To run it, simply call:

bazel run //3rdparty:crates_vendor

<a id=”#crates_vendor_repinning_updating_dependencies”></a>

Repinning / Updating Dependencies

Repinning dependencies is controlled by both the CARGO_BAZEL_REPIN environment variable or the --repin flag to the crates_vendor binary. To update dependencies, simply add the flag ro your bazel run invocation.

bazel run //3rdparty:crates_vendor -- --repin

Under the hood, --repin will trigger a cargo update call against the generated workspace. The following table describes how to control particular values passed to the cargo update command.

Value Cargo command
Any of [true, 1, yes, on, workspace] cargo update --workspace
Any of [full, eager, all] cargo update
package_name cargo upgrade --package package_name
package_name@1.2.3 cargo upgrade --package package_name --precise 1.2.3

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required  
annotations Extra settings to apply to crates. See crate.annotation. Dictionary: String -> List of strings optional {}
bazel The path to a bazel binary used to locate the output_base for the current workspace. Label optional None
buildifier The path to a buildifier binary used to format generated BUILD files. Label optional //crate_universe/private/vendor:buildifier
cargo_bazel The cargo-bazel binary to use for vendoring. If this attribute is not set, then a CARGO_BAZEL_GENERATOR_PATH action env will be used. Label optional @cargo_bazel_bootstrap//:binary
cargo_config A Cargo configuration file. Label optional None
cargo_lockfile The path to an existing Cargo.lock file Label optional None
generate_binaries Whether to generate rust_binary targets for all the binary crates in every package. By default only the rust_library targets are generated. Boolean optional False
generate_build_scripts Whether or not to generate cargo build scripts by default. Boolean optional True
generate_target_compatible_with DEPRECATED: Moved to render_config. Boolean optional True
manifests A list of Cargo manifests (Cargo.toml files). List of labels optional []
mode Flags determining how crates should be vendored. local is where crate source and BUILD files are written to the repository. remote is where only BUILD files are written and repository rules used to fetch source code. String optional "remote"
packages A set of crates (packages) specifications to depend on. See crate.spec. Dictionary: String -> String optional {}
render_config The configuration flags to use for rendering. Use //crate_universe:defs.bzl\%render_config to generate the value for this field. If unset, the defaults defined there will be used. String optional ""
repository_name The name of the repository to generate for remote vendor modes. If unset, the label name will be used String optional ""
splicing_config The configuration flags to use for splicing Cargo maniests. Use //crate_universe:defs.bzl\%rsplicing_config to generate the value for this field. If unset, the defaults defined there will be used. String optional ""
supported_platform_triples A set of all platform triples to consider when generating dependencies. List of strings optional ["aarch64-unknown-linux-gnu", "aarch64-unknown-nixos-gnu", "i686-apple-darwin", "i686-pc-windows-msvc", "i686-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc", "x86_64-unknown-linux-gnu", "x86_64-unknown-nixos-gnu", "aarch64-apple-darwin", "aarch64-apple-ios-sim", "aarch64-apple-ios", "aarch64-fuchsia", "aarch64-linux-android", "aarch64-pc-windows-msvc", "arm-unknown-linux-gnueabi", "armv7-linux-androideabi", "armv7-unknown-linux-gnueabi", "i686-linux-android", "i686-unknown-freebsd", "powerpc-unknown-linux-gnu", "riscv32imc-unknown-none-elf", "riscv64gc-unknown-none-elf", "s390x-unknown-linux-gnu", "thumbv7em-none-eabi", "thumbv8m.main-none-eabi", "wasm32-unknown-unknown", "wasm32-wasi", "x86_64-apple-ios", "x86_64-fuchsia", "x86_64-linux-android", "x86_64-unknown-freebsd", "x86_64-unknown-none", "aarch64-unknown-nto-qnx710"]
vendor_path The path to a directory to write files into. Absolute paths will be treated as relative to the workspace root String optional "crates"

aliases

aliases(normal, normal_dev, proc_macro, proc_macro_dev, build, build_proc_macro, package_name)

Produces a map of Crate alias names to their original label

If no dependency kinds are specified, normal and proc_macro are used by default. Setting any one flag will otherwise determine the contents of the returned dict.

PARAMETERS

Name Description Default Value
normal If True, normal dependencies are included in the output list. False
normal_dev If True, normal dev dependencies will be included in the output list.. False
proc_macro If True, proc_macro dependencies are included in the output list. False
proc_macro_dev If True, dev proc_macro dependencies are included in the output list. False
build If True, build dependencies are included in the output list. False
build_proc_macro If True, build proc_macro dependencies are included in the output list. False
package_name The package name of the set of dependencies to look up. Defaults to native.package_name() when unset. None

RETURNS

dict: The aliases of all associated packages

all_crate_deps

all_crate_deps(normal, normal_dev, proc_macro, proc_macro_dev, build, build_proc_macro,
               package_name)

Finds the fully qualified label of all requested direct crate dependencies for the package where this macro is called.

If no parameters are set, all normal dependencies are returned. Setting any one flag will otherwise impact the contents of the returned list.

PARAMETERS

Name Description Default Value
normal If True, normal dependencies are included in the output list. False
normal_dev If True, normal dev dependencies will be included in the output list.. False
proc_macro If True, proc_macro dependencies are included in the output list. False
proc_macro_dev If True, dev proc_macro dependencies are included in the output list. False
build If True, build dependencies are included in the output list. False
build_proc_macro If True, build proc_macro dependencies are included in the output list. False
package_name The package name of the set of dependencies to look up. Defaults to native.package_name() when unset. None

RETURNS

list: A list of labels to generated rust targets (str)

crate.spec

crate.spec(package, version, artifact, lib, default_features, features, git, branch, tag, rev)

A constructor for a crate dependency.

See specifying dependencies in the Cargo book for more details.

PARAMETERS

Name Description Default Value
package The explicit name of the package (used when attempting to alias a crate). None
version The exact version of the crate. Cannot be used with git. None
artifact Set to “bin” to pull in a binary crate as an artifact dependency. Requires a nightly Cargo. None
lib If using artifact = "bin", additionally setting lib = True declares a dependency on both the package’s library and binary, as opposed to just the binary. None
default_features Maps to the default-features flag. True
features A list of features to use for the crate []
git The Git url to use for the crate. Cannot be used with version. None
branch The git branch of the remote crate. Tied with the git param. Only one of branch, tag or rev may be specified. Specifying rev is recommended for fully-reproducible builds. None
tag The git tag of the remote crate. Tied with the git param. Only one of branch, tag or rev may be specified. Specifying rev is recommended for fully-reproducible builds. None
rev The git revision of the remote crate. Tied with the git param. Only one of branch, tag or rev may be specified. None

RETURNS

string: A json encoded string of all inputs

crate.annotation

crate.annotation(version, additive_build_file, additive_build_file_content, alias_rule,
                 build_script_data, build_script_tools, build_script_data_glob, build_script_deps,
                 build_script_env, build_script_proc_macro_deps, build_script_rundir,
                 build_script_rustc_env, build_script_toolchains, compile_data, compile_data_glob,
                 crate_features, data, data_glob, deps, extra_aliased_targets, gen_binaries,
                 disable_pipelining, gen_build_script, patch_args, patch_tool, patches,
                 proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, shallow_since)

A collection of extra attributes and settings for a particular crate

PARAMETERS

Name Description Default Value
version The version or semver-conditions to match with a crate. The wildcard * matches any version, including prerelease versions. "*"
additive_build_file A file containing extra contents to write to the bottom of generated BUILD files. None
additive_build_file_content Extra contents to write to the bottom of generated BUILD files. None
alias_rule Alias rule to use instead of native.alias(). Overrides render_config’s ‘default_alias_rule’. None
build_script_data A list of labels to add to a crate’s cargo_build_script::data attribute. None
build_script_tools A list of labels to add to a crate’s cargo_build_script::tools attribute. None
build_script_data_glob A list of glob patterns to add to a crate’s cargo_build_script::data attribute. None
build_script_deps A list of labels to add to a crate’s cargo_build_script::deps attribute. None
build_script_env Additional environment variables to set on a crate’s cargo_build_script::env attribute. None
build_script_proc_macro_deps A list of labels to add to a crate’s cargo_build_script::proc_macro_deps attribute. None
build_script_rundir An override for the build script’s rundir attribute. None
build_script_rustc_env Additional environment variables to set on a crate’s cargo_build_script::env attribute. None
build_script_toolchains A list of labels to set on a crates’s cargo_build_script::toolchains attribute. None
compile_data A list of labels to add to a crate’s rust_library::compile_data attribute. None
compile_data_glob A list of glob patterns to add to a crate’s rust_library::compile_data attribute. None
crate_features A list of strings to add to a crate’s rust_library::crate_features attribute. None
data A list of labels to add to a crate’s rust_library::data attribute. None
data_glob A list of glob patterns to add to a crate’s rust_library::data attribute. None
deps A list of labels to add to a crate’s rust_library::deps attribute. None
extra_aliased_targets A list of targets to add to the generated aliases in the root crate_universe repository. None
gen_binaries As a list, the subset of the crate’s bins that should get rust_binary targets produced. Or True to generate all, False to generate none. None
disable_pipelining If True, disables pipelining for library targets for this crate. False
gen_build_script An authorative flag to determine whether or not to produce cargo_build_script targets for the current crate. None
patch_args The patch_args attribute of a Bazel repository rule. See http_archive.patch_args None
patch_tool The patch_tool attribute of a Bazel repository rule. See http_archive.patch_tool None
patches The patches attribute of a Bazel repository rule. See http_archive.patches None
proc_macro_deps A list of labels to add to a crate’s rust_library::proc_macro_deps attribute. None
rustc_env Additional variables to set on a crate’s rust_library::rustc_env attribute. None
rustc_env_files A list of labels to set on a crate’s rust_library::rustc_env_files attribute. None
rustc_flags A list of strings to set on a crate’s rust_library::rustc_flags attribute. None
shallow_since An optional timestamp used for crates originating from a git repository instead of a crate registry. This flag optimizes fetching the source code. None

RETURNS

string: A json encoded string containing the specified version and separately all other inputs.

crate.workspace_member

crate.workspace_member(version, sha256)

Define information for extra workspace members

PARAMETERS

Name Description Default Value
version The semver of the crate to download. Must be an exact version. none
sha256 The sha256 checksum of the .crate file. None

RETURNS

string: A json encoded string of all inputs

crate.select

crate.select(common, selects)

A Starlark Select for crate.annotation().

PARAMETERS

Name Description Default Value
common A value that applies to all configurations. none
selects A dict of target_triple to values. none

RETURNS

struct: A struct representing the Starlark Select.

crate_deps

crate_deps(deps, package_name)

Finds the fully qualified label of the requested crates for the package where this macro is called.

PARAMETERS

Name Description Default Value
deps The desired list of crate targets. none
package_name The package name of the set of dependencies to look up. Defaults to native.package_name(). None

RETURNS

list: A list of labels to generated rust targets (str)

crate_repositories

crate_repositories()

A macro for defining repositories for all generated crates.

RETURNS

A list of repos visible to the module through the module extension.

crate_universe_dependencies

crate_universe_dependencies(rust_version, bootstrap, kwargs)

Define dependencies of the cargo-bazel Rust target

PARAMETERS

Name Description Default Value
rust_version The version of rust to use when generating dependencies. "1.77.0"
bootstrap If true, a cargo_bootstrap_repository target will be generated. False
kwargs Arguments to pass through to cargo_bazel_bootstrap. none

RETURNS

list[struct(repo=str, is_dev_dep=bool)]: A list of the repositories defined by this macro.

render_config

render_config(build_file_template, crate_label_template, crate_repository_template,
              crates_module_template, default_alias_rule, default_package_name,
              generate_target_compatible_with, platforms_template, regen_command, vendor_mode,
              generate_rules_license_metadata)

Various settings used to configure rendered outputs

The template parameters each support a select number of format keys. A description of each key can be found below where the supported keys for each template can be found in the parameter docs

key definition
name The name of the crate. Eg tokio
repository The rendered repository name for the crate. Directly relates to crate_repository_template.
triple A platform triple. Eg x86_64-unknown-linux-gnu
version The crate version. Eg 1.2.3
target The library or binary target of the crate
file The basename of a file

PARAMETERS

Name Description Default Value
build_file_template The base template to use for BUILD file names. The available format keys are [{name}, {version}]. "//:BUILD.{name}-{version}.bazel"
crate_label_template The base template to use for crate labels. The available format keys are [{repository}, {name}, {version}, {target}]. "@{repository}__{name}-{version}//:{target}"
crate_repository_template The base template to use for Crate label repository names. The available format keys are [{repository}, {name}, {version}]. "{repository}__{name}-{version}"
crates_module_template The pattern to use for the defs.bzl and BUILD.bazel file names used for the crates module. The available format keys are [{file}]. "//:{file}"
default_alias_rule Alias rule to use when generating aliases for all crates. Acceptable values are ‘alias’, ‘dbg’/’fastbuild’/’opt’ (transitions each crate’s compilation_mode) or a string representing a rule in the form ‘<label to .bzl>:<rule>’ that takes a single label parameter ‘actual’. See ‘@crate_index//:alias_rules.bzl’ for an example. "alias"
default_package_name The default package name to use in the rendered macros. This affects the auto package detection of things like all_crate_deps. None
generate_target_compatible_with Whether to generate target_compatible_with annotations on the generated BUILD files. This catches a target_triplebeing targeted that isn’t declared in supported_platform_triples. True
platforms_template The base template to use for platform names. See platforms documentation. The available format keys are [{triple}]. "@rules_rust//rust/platform:{triple}"
regen_command An optional command to demonstrate how generated files should be regenerated. None
vendor_mode An optional configuration for rendirng content to be rendered into repositories. None
generate_rules_license_metadata Whether to generate rules license metedata False

RETURNS

string: A json encoded struct to match the Rust config::RenderConfig struct

splicing_config

splicing_config(resolver_version)

Various settings used to configure Cargo manifest splicing behavior.

PARAMETERS

Name Description Default Value
resolver_version The resolver version to use in generated Cargo manifests. This flag is only used when splicing a manifest from direct package definitions. See crates_repository::packages. "2"

RETURNS

str: A json encoded string of the parameters provided