crate_universe_bzlmod.md

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:

• https://github.com/bazelbuild/rules_rust/blob/main/examples/bzlmod/hello_world/MODULE.bazel
• https://github.com/bazelbuild/rules_rust/blob/main/examples/bzlmod/override_target/MODULE.bazel
• https://github.com/bazelbuild/rules_rust/blob/main/examples/bzlmod/all_crate_deps/MODULE.bazel

crate

crate = use_extension("@rules_rust//crate_universe:docs_bzlmod.bzl", "crate")
crate.from_cargo(name, cargo_config, cargo_lockfile, generate_binaries, generate_build_scripts,
                 manifests, supported_platform_triples)
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_specs(name, cargo_config, generate_binaries, generate_build_scripts,
                 supported_platform_triples)
crate.spec(artifact, branch, default_features, features, git, lib, package, rev, tag, version)

TAG CLASSES

from_cargo

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

Attributes

Name	Description	Type	Mandatory	Default
name	The name of the repo to generate	Name	optional	"crates"
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
manifests	A list of Cargo manifests (Cargo.toml files).	List of labels	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"]

annotation

Attributes

Name	Description	Type	Mandatory	Default
deps	A list of labels to add to a crate's rust_library::deps attribute.	List of strings	optional	[]
data	A list of labels to add to a crate's rust_library::data attribute.	List of strings	optional	[]
additive_build_file	A file containing extra contents to write to the bottom of generated BUILD files.	Label	optional	None
additive_build_file_content	Extra contents to write to the bottom of generated BUILD files.	String	optional	""
alias_rule	Alias rule to use instead of native.alias(). Overrides render_config's 'default_alias_rule'.	String	optional	""
build_script_data	A list of labels to add to a crate's cargo_build_script::data attribute.	List of strings	optional	[]
build_script_data_glob	A list of glob patterns to add to a crate's cargo_build_script::data attribute	List of strings	optional	[]
build_script_deps	A list of labels to add to a crate's cargo_build_script::deps attribute.	List of strings	optional	[]
build_script_env	Additional environment variables to set on a crate's cargo_build_script::env attribute.	Dictionary: String -> String	optional	{}
build_script_proc_macro_deps	A list of labels to add to a crate's cargo_build_script::proc_macro_deps attribute.	List of strings	optional	[]
build_script_rundir	An override for the build script's rundir attribute.	String	optional	""
build_script_rustc_env	Additional environment variables to set on a crate's cargo_build_script::env attribute.	Dictionary: String -> String	optional	{}
build_script_toolchains	A list of labels to set on a crates's cargo_build_script::toolchains attribute.	List of labels	optional	[]
build_script_tools	A list of labels to add to a crate's cargo_build_script::tools attribute.	List of strings	optional	[]
compile_data	A list of labels to add to a crate's rust_library::compile_data attribute.	List of strings	optional	[]
compile_data_glob	A list of glob patterns to add to a crate's rust_library::compile_data attribute.	List of strings	optional	[]
crate	The name of the crate the annotation is applied to	String	required
crate_features	A list of strings to add to a crate's rust_library::crate_features attribute.	List of strings	optional	[]
data_glob	A list of glob patterns to add to a crate's rust_library::data attribute.	List of strings	optional	[]
disable_pipelining	If True, disables pipelining for library targets for this crate.	Boolean	optional	False
extra_aliased_targets	A list of targets to add to the generated aliases in the root crate_universe repository.	Dictionary: String -> String	optional	{}
gen_all_binaries	If true, generates rust_binary targets for all of the crates bins	Boolean	optional	False
gen_binaries	As a list, the subset of the crate's bins that should get rust_binary targets produced.	List of strings	optional	[]
gen_build_script	An authorative flag to determine whether or not to produce cargo_build_script targets for the current crate. Supported values are 'on', 'off', and 'auto'.	String	optional	"auto"
override_target_bin	An optional alternate taget to use when something depends on this crate to allow the parent repo to provide its own version of this dependency.	Label	optional	None
override_target_build_script	An optional alternate taget to use when something depends on this crate to allow the parent repo to provide its own version of this dependency.	Label	optional	None
override_target_lib	An optional alternate taget to use when something depends on this crate to allow the parent repo to provide its own version of this dependency.	Label	optional	None
override_target_proc_macro	An optional alternate taget to use when something depends on this crate to allow the parent repo to provide its own version of this dependency.	Label	optional	None
patch_args	The patch_args attribute of a Bazel repository rule. See http_archive.patch_args	List of strings	optional	[]
patch_tool	The patch_tool attribute of a Bazel repository rule. See http_archive.patch_tool	String	optional	""
patches	The patches attribute of a Bazel repository rule. See http_archive.patches	List of labels	optional	[]
proc_macro_deps	A list of labels to add to a crate's rust_library::proc_macro_deps attribute.	List of strings	optional	[]
repositories	A list of repository names specified from crate.from_cargo(name=...) that this annotation is applied to. Defaults to all repositories.	List of strings	optional	[]
rustc_env	Additional variables to set on a crate's rust_library::rustc_env attribute.	Dictionary: String -> String	optional	{}
rustc_env_files	A list of labels to set on a crate's rust_library::rustc_env_files attribute.	List of strings	optional	[]
rustc_flags	A list of strings to set on a crate's rust_library::rustc_flags attribute.	List of strings	optional	[]
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.	String	optional	""
version	The versions of the crate the annotation is applied to. Defaults to all versions.	String	optional	"*"

from_specs

Generates a repo @crates from the defined spec tags

Attributes

Name	Description	Type	Mandatory	Default
name	The name of the repo to generate	Name	optional	"crates"
cargo_config	A Cargo configuration 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
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"]

spec

Attributes

Name	Description	Type	Mandatory	Default
artifact	Set to 'bin' to pull in a binary crate as an artifact dependency. Requires a nightly Cargo.	String	optional	""
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.	String	optional	""
default_features	Maps to the default-features flag.	Boolean	optional	True
features	A list of features to use for the crate.	List of strings	optional	[]
git	The Git url to use for the crate. Cannot be used with version.	String	optional	""
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.	Boolean	optional	False
package	The explicit name of the package.	String	required
rev	The git revision of the remote crate. Tied with the git param. Only one of branch, tag or rev may be specified.	String	optional	""
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.	String	optional	""
version	The exact version of the crate. Cannot be used with git.	String	optional	""