# 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](crate_universe.html).
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](https://doc.rust-lang.org/cargo/reference/config.html) 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](https://doc.rust-lang.org/cargo/reference/build-scripts.html) 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](#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](https://docs.bazel.build/versions/main/repo/http.html#http_archive-patch_args) | List of strings | optional | `[]` |
| patch_tool | The `patch_tool` attribute of a Bazel repository rule. See [http_archive.patch_tool](https://docs.bazel.build/versions/main/repo/http.html#http_archive-patch_tool) | String | optional | `""` |
| patches | The `patches` attribute of a Bazel repository rule. See [http_archive.patches](https://docs.bazel.build/versions/main/repo/http.html#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](https://doc.rust-lang.org/cargo/reference/config.html) 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](https://doc.rust-lang.org/cargo/reference/build-scripts.html) 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 | `""` |