Cargo->Bazel

cargo-bazel is a Bazel repository rule for generating Rust targets using Cargo.

Setup

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

# To get an accurate and up to date repository definition, See the releases page
# https://github.com/abrisco/cargo-bazel/releases
http_archive(
    name = "cargo_bazel",
    sha256 = "{sha256}",
    urls = ["https://github.com/abrisco/cargo-bazel/releases/download/{version}/cargo_bazel.tar.gz"],
)

load("@cargo_bazel//:deps.bzl", "cargo_bazel_deps")

cargo_bazel_deps()

# It's important to set a constant for desired Rust version so it
# can easily be passed to each `crates_repository` definition.
RUST_VERSION = "1.54.0"

load("@rules_rust//rust:repositories.bzl", "rust_repositories")

rust_repositories(version = RUST_VERSION)

crates_repository Workflows

The crates_repository rule (the primary repository rule of cargo-bazel) 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 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 the root Cargo.toml file and generate dependencies from there.

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

crates_repository(
    name = "crate_index",
    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 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("@cargo_bazel//:defs.bzl", "crate", "crates_repository", "render_config")

crates_repository(
    name = "crate_index",
    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",
    ],
)

Rules

• crates_repository
• crates_vendor
• crate.spec
• crate.workspace_member
• crate.annotation
• render_config
• splicing_config

crates_repository

crates_repository(name, annotations, cargo_config, extra_workspace_member_url_template,
                  extra_workspace_members, generate_build_scripts, generator, generator_sha256s,
                  generator_urls, isolated, lockfile, lockfile_kind, 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).

Environment Variables:

ATTRIBUTES

crates_vendor

crates_vendor(name, annotations, buildifier, cargo_bazel, generate_build_scripts, manifests, mode,
              packages, 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

ATTRIBUTES

crate.spec

crate.spec(package, version, default_features, features, git, rev)

A constructor for a crate dependency.

See specifying dependencies in the Cargo book for more details.

PARAMETERS

RETURNS

string: A json encoded string of all inputs

crate.annotation

crate.annotation(version, additive_build_file, additive_build_file_content, build_script_data,
                 build_script_data_glob, build_script_deps, build_script_env,
                 build_script_proc_macro_deps, build_script_rustc_env, compile_data,
                 compile_data_glob, crate_features, data, data_glob, deps, 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

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

RETURNS

string: A json encoded string of all inputs

render_config

render_config(build_file_template, crate_label_template, crate_repository_template,
              crates_module_template, default_package_name, platforms_template, vendor_mode)

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

PARAMETERS

RETURNS

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

splicing_config

splicing_config(resolver_version)

arious settings used to configure Cargo manifest splicing behavior.

PARAMETERS

RETURNS

str: A json encoded string of the parameters provided

crates_repository API

• aliases
• crate_deps
• all_crate_deps
• crate_repositories

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

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

RETURNS

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

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

RETURNS

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

crate_repositories

crate_repositories()

A macro for defining repositories for all generated crates