Crate Universe

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

This doc describes using crate_universe with bzlmod.

If you're using a WORKSPACE file, please see the WORKSPACE equivalent of this doc.

There are some examples of using crate_universe with bzlmod in the example folder.

Table of Contents

1. Setup
2. Dependencies
   • Cargo Workspace
   • Direct Packages
   • Binary Dependencies
   • Vendored Dependencies
3. Crate reference
   • from_cargo
   • from_specs

Setup

To use rules_rust in a project using bzlmod, add the following to your MODULE.bazel file:

bazel_dep(name = "rules_rust", version = "0.57.0")

You find the latest version on the release page.

After adding rules_rust in your MODULE.bazel, set the following to begin using crate_universe:

crate = use_extension("@rules_rust//crate_universe:extensions.bzl", "crate")
//  # ... Dependencies
use_repo(crate, "crates")

Dependencies

There are three different ways to declare dependencies in your MODULE.

1. Cargo workspace
2. Direct Dependencies
3. Binary Dependencies
4. Vendored Dependencies

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 Bazel dependencies from there. You find a complete example in the in the example folder.

crate = use_extension("@rules_rust//crate_universe:extensions.bzl", "crate")

crate.from_cargo(
    name = "crates",
    cargo_lockfile = "//:Cargo.lock",
    manifests = ["//:Cargo.toml"],
)
use_repo(crate, "crates")

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. In your BUILD files, you use these macros for a Rust library as shown below:

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

For a Rust binary that does not depend on any macro, use the following configuration in your build file:

rust_binary(
    name = "bin",
    srcs = ["src/main.rs"],
    deps = all_crate_deps(normal = True),
)

You have to repin before your first build to ensure all Bazel targets for the macros are generated.

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 crates, the easiest way to repin dependencies is to run:

CARGO_BAZEL_REPIN=1 bazel sync --only=crates

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. For more details about repin, please refer to the documentation.

Direct Dependencies

In cases where Rust targets have heavy interactions with other Bazel targets (Cc, Proto, etc.), maintaining Cargo.toml files may have diminishing returns as things like rust-analyzer begin to be confused about missing targets or environment variables defined only in Bazel. In situations like this, it may be desirable to have a "Cargo free" setup. You find an example in the in the example folder.

crates_repository supports this through the packages attribute, as shown below.

crate = use_extension("@rules_rust//crate_universe:extensions.bzl", "crate")

crate.spec(package = "serde", features = ["derive"], version = "1.0")
crate.spec(package = "serde_json", version = "1.0")
crate.spec(package = "tokio", default_features = False, features = ["macros", "net", "rt-multi-thread"], version = "1.38")

crate.from_specs()
use_repo(crate, "crates")

Consuming dependencies may be more ergonomic in this case through the aliases defined in the new repository. In your BUILD files, you use direct dependencies as shown below:

rust_binary(
    name = "bin",
    crate_root = "src/main.rs",
    srcs = glob([
        "src/*.rs",
    ]),
    deps = [
        # External crates
        "@crates//:serde",
        "@crates//:serde_json",
        "@crates//:tokio",
    ],
    visibility = ["//visibility:public"],
)

Notice, direct dependencies do not need repining. Only a cargo workspace needs updating whenever the underlying Cargo.toml file changed.

Binary Dependencies

With cargo you can install binary dependencies (bindeps) as well with cargo install command.

We don't have such easy facilities available in bazel besides specifying it as a dependency. To mimic cargo's bindeps feature we use the unstable feature called artifact-dependencies which integrates well with bazel concepts.

You could use the syntax specified in the above document to place it in Cargo.toml. For that you can consult the following example.

This method has the following consequences:

• if you use shared dependency tree with your project these binary dependencies will interfere with yours (may conflict)
• you have to use nightly host_tools_repo to generate dependencies because

Alternatively you can specify this in a separate repo with cargo.from_specs syntax:

bindeps = use_extension("@rules_rust//crate_universe:extension.bzl", "crate")

bindeps.spec(package = "cargo-machete", version = "=0.7.0", artifact = "bin")
bindeps.annotation(crate = "cargo-machete", gen_all_binaries = True)

bindeps.from_specs(
  name = "bindeps",
  host_tools_repo = "rust_host_tools_nightly",
)

use_repo(bindeps, "bindeps")

You can run the specified binary dependency with the following command or create additional more complex rules on top of it.

bazel run @bindeps//:cargo-machete__cargo-machete

Notice, direct dependencies do not need repining. Only a cargo workspace needs updating whenever the underlying Cargo.toml file changed.

Vendored Dependencies

In some cases, it is require that all external dependencies are vendored, meaning downloaded and stored in the workspace. This helps, for example, to conduct licence scans, apply custom patches, or to ensure full build reproducibility since no download error could possibly occur. You find a complete example in the in the example folder.

For the setup, you need to add the skylib in addition to the rust rules to your MODUE.bazel.

module(
    name = "deps_vendored",
    version = "0.0.0"
)
###############################################################################
# B A Z E L  C E N T R A L  R E G I S T R Y # https://registry.bazel.build/
###############################################################################
# https://github.com/bazelbuild/bazel-skylib/releases/
bazel_dep(name = "bazel_skylib", version = "1.7.1")

# https://github.com/bazelbuild/rules_rust/releases
bazel_dep(name = "rules_rust", version = "0.57.0")

###############################################################################
# T O O L C H A I N S
###############################################################################

# Rust toolchain
RUST_EDITION = "2021"
RUST_VERSION = "1.80.1"

rust = use_extension("@rules_rust//rust:extensions.bzl", "rust")
rust.toolchain(
    edition = RUST_EDITION,
    versions = [RUST_VERSION],
)
use_repo(rust, "rust_toolchains")
register_toolchains("@rust_toolchains//:all")

###############################################################################
# R U S T  C R A T E S
###############################################################################
crate = use_extension("@rules_rust//crate_universe:extensions.bzl", "crate")

Note, it is important to load the crate_universe rules otherwise you will get an error as the rule set is needed in the vendored target.

Assuming you have a package called basic in which you want to vendor dependencies, then you create a folder basic/3rdparty. The folder name can be arbitrary, but by convention, its either thirdparty or 3rdparty to indicate vendored dependencies. In the 3rdparty folder, you add a target crates_vendor to declare your dependencies to vendor. In the example, we vendor a specific version of bzip2.

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

crates_vendor(
    name = "crates_vendor",
    annotations = {
        "bzip2-sys": [crate.annotation(
            gen_build_script = True,
        )],
    },
    cargo_lockfile = "Cargo.Bazel.lock",
    generate_build_scripts = False,
    mode = "remote",
    packages = {
        "bzip2": crate.spec(
            version = "=0.3.3",
        ),
    },
    repository_name = "basic",
    tags = ["manual"],
)

Next, you have to run Cargo build to generate a Cargo.lock file with all resolved dependencies. Then, you rename Cargo.lock to Cargo.Bazel.lock and place it inside the basic/3rdparty folder.

At this point, you have the following folder and files:

basic
    |-- 3rdparty
    |   |-- BUILD.bazel
    |   |-- Cargo.Bazel.lock

Now you can run the crates_vendor target:

bazel run //basic/3rdparty:crates_vendor

This generates a crate folders with all configurations for the vendored dependencies.

basic
    |-- 3rdparty
    |   |-- cratea
    |   |-- BUILD.bazel
    |   |-- Cargo.Bazel.lock

Suppose you have an application in basic/src that is defined in basic/BUILD.bazel and that depends on a vendored dependency. You find a list of all available vendored dependencies in the BUILD file of the generated folder: basic/3rdparty/crates/BUILD.bazel You declare a vendored dependency in you target as following:

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

rust_binary(
    name = "hello_sys",
    srcs = ["src/main.rs"],
    deps = ["//basic/3rdparty/crates:bzip2"],
    visibility = ["//visibility:public"],
)

Note, the vendored dependency is not yet accessible because you have to define first how to load the vendored dependencies. For that, you first create a file sys_deps.bzl and add the following content:

# rename the default name "crate_repositories" in case you import multiple vendored folders.
load("//basic/3rdparty/crates:defs.bzl", basic_crate_repositories = "crate_repositories")

def sys_deps():
    # Load the vendored dependencies
    basic_crate_repositories()

This is straightforward, you import the generated crate_repositories from the crates folder, rename it to avoid name clashes in case you import from multiple vendored folders, and then just load the vendored dependencies.

In a WORKSPACE configuration, you would just load and call sys_deps(), but in a MODULE configuration, you cannot do that. Instead, you create a new file WORKSPACE.bzlmod and add the following content.

load("//:sys_deps.bzl", "sys_deps")
sys_deps()

Now, you can build the project as usual.

There are some more examples of using crate_universe with bzlmod in the example folder.

crate

crate = use_extension("@rules_rust//crate_universe:extensions.bzl", "crate")
crate.annotation(deps, data, additive_build_file, additive_build_file_content, alias_rule,
                 build_script_data, 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, build_script_tools, compile_data, compile_data_glob, crate,
                 crate_features, data_glob, disable_pipelining, extra_aliased_targets,
                 gen_all_binaries, gen_binaries, gen_build_script, override_target_bin,
                 override_target_build_script, override_target_lib, override_target_proc_macro,
                 patch_args, patch_tool, patches, proc_macro_deps, repositories, rustc_env,
                 rustc_env_files, rustc_flags, shallow_since, version)
crate.from_cargo(name, cargo_config, cargo_lockfile, generate_binaries, generate_build_scripts,
                 host_tools_repo, isolated, lockfile, manifests, supported_platform_triples)
crate.from_specs(name, cargo_config, cargo_lockfile, generate_binaries, generate_build_scripts,
                 host_tools_repo, isolated, lockfile, supported_platform_triples)
crate.render_config(build_file_template, crate_alias_template, crate_label_template,
                    crate_repository_template, crates_module_template, default_alias_rule_bzl,
                    default_alias_rule_name, default_package_name, generate_rules_license_metadata,
                    generate_target_compatible_with, platforms_template, regen_command, repositories,
                    vendor_mode)
crate.spec(artifact, branch, default_features, features, git, lib, package, repositories, rev, tag,
           version)
crate.splicing_config(repositories, resolver_version)

Crate universe module extensions.

Environment Variables:

TAG CLASSES

annotation

A collection of extra attributes and settings for a particular crate.

Attributes

from_cargo

Generates a repo @crates from a Cargo.toml / Cargo.lock pair.

Attributes

from_specs

Generates a repo @crates from the defined spec tags.

Attributes

render_config

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

Attributes

spec

A constructor for a crate dependency.

Attributes

splicing_config

Various settings used to configure Cargo manifest splicing behavior.

Attributes