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:

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.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
annotations	Extra settings to apply to crates. See crate.annotations.	Dictionary: String -> List of strings	optional	{}
cargo_config	A Cargo configuration file	Label	optional	None
extra_workspace_member_url_template	The registry url to use when fetching extra workspace members	String	optional	"https://crates.io/api/v1/crates/{name}/{version}/download"
extra_workspace_members	Additional crates to download and include as a workspace member. This is unfortunately required in order to add information about "binary-only" crates so that a `rust_binary` may be generated for it. rust-lang/cargo#9096 tracks an RFC which may solve for this.	Dictionary: String -> String	optional	{}
generate_build_scripts	Whether or not to generate cargo build scripts by default.	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. Two kinds of lock files are supported, Cargo (`Cargo.lock` files) and Bazel (custom files generated by this rule, naming is irrelevant). Bazel lockfiles should be the prefered kind as they're desigend with Bazel's notions of reporducibility in mind. Cargo lockfiles can be used in cases where it's intended to be the source of truth, but more work will need to be done to generate BUILD files which are not guaranteed to be determinsitic.	Label	required
lockfile_kind	Two different kinds of lockfiles are supported, the custom "Bazel" lockfile, which is generated by this rule, and Cargo lockfiles (`Cargo.lock`). This attribute allows for explicitly defining the type in cases where it may not be auto-detectable.	String	optional	"auto"
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 `@cargo_bazel//: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'), and `{tool}` (eg. 'rustc.exe') will be replaced in the string if present.	String	optional	"@rust_{system}_{arch}//: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'), and `{tool}` (eg. 'cargo.exe') will be replaced in the string if present.	String	optional	"@rust_{system}_{arch}//: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.59.0"
splicing_config	The configuration flags to use for splicing Cargo maniests. Use `@cargo_bazel//: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	["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", "aarch64-apple-darwin", "aarch64-apple-ios", "aarch64-linux-android", "aarch64-unknown-linux-gnu", "arm-unknown-linux-gnueabi", "armv7-unknown-linux-gnueabi", "i686-linux-android", "i686-unknown-freebsd", "powerpc-unknown-linux-gnu", "s390x-unknown-linux-gnu", "wasm32-unknown-unknown", "wasm32-wasi", "x86_64-apple-ios", "x86_64-linux-android", "x86_64-unknown-freebsd"]

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

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
annotations	Extra settings to apply to crates. See crate.annotations.	Dictionary: String -> List of strings	optional	{}
buildifier	The path to a buildifier binary used to format generated BUILD files.	Label	optional	//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
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	[]
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	{}
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 `@cargo_bazel//: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	["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", "aarch64-apple-darwin", "aarch64-apple-ios", "aarch64-linux-android", "aarch64-unknown-linux-gnu", "arm-unknown-linux-gnueabi", "armv7-unknown-linux-gnueabi", "i686-linux-android", "i686-unknown-freebsd", "powerpc-unknown-linux-gnu", "s390x-unknown-linux-gnu", "wasm32-unknown-unknown", "wasm32-wasi", "x86_64-apple-ios", "x86_64-linux-android", "x86_64-unknown-freebsd"]
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"

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

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`
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`
rev	The git revision of the remote crate. Tied with the `git` param.	`None`

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

Name	Description	Default Value
version	The version or semver-conditions to match with a crate.	`"*"`
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`
build_script_data	A list of labels to add to a crate's `cargo_build_script::data` 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_rustc_env	Additional environment variables to set on a crate's `cargo_build_script::env` 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`
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

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

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_package_name	The default package name to in the rendered macros. This affects the auto package detection of things like `all_crate_deps`.	`None`
platforms_template	The base template to use for platform names. See platforms documentation. The available format keys are [`{triple}`].	`"@rules_rust//rust/platform:{triple}"`
vendor_mode	An optional configuration for rendirng content to be rendered into repositories.	`None`

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

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`.	`"1"`

RETURNS

str: A json encoded string of the parameters provided

Cargo->Bazel