Cargo

• cargo_bootstrap_repository
• cargo_build_script
• cargo_env

cargo_bootstrap_repository

A rule for bootstrapping a Rust binary using Cargo

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
binary	The binary to build (the --bin parameter for Cargo). If left empty, the repository name will be used.	String	optional	""
build_mode	The build mode the binary should be built with	String	optional	“release”
cargo_lockfile	The lockfile of the crate_universe resolver	Label	required
cargo_toml	The path of the crate_universe resolver manifest (Cargo.toml file)	Label	required
env	A mapping of platform triple to a set of environment variables. See cargo_env for usage details. Additionally, the platform triple * applies to all platforms.	Dictionary: String -> String	optional	{}
env_label	A mapping of platform triple to a set of environment variables. This attribute differs from env in that all variables passed here must be fully qualified labels of files. See cargo_env for usage details. Additionally, the platform triple * applies to all platforms.	Dictionary: String -> String	optional	{}
iso_date	The iso_date of cargo binary the resolver should use. Note: This can only be set if version is beta or nightly	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’), and {tool} (eg. ‘rustc.exe’) will be replaced in the string if present.	String	optional	“@rust_{system}_{arch}//:bin/{tool}”
rust_toolchain_repository_template	Deprecated: Please use rust_toolchain_cargo_template and rust_toolchain_rustc_template	String	optional	""
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’), and {tool} (eg. ‘rustc.exe’) will be replaced in the string if present.	String	optional	“@rust_{system}_{arch}//:bin/{tool}”
srcs	Souce files of the crate to build. Passing source files here can be used to trigger rebuilds when changes are made	List of labels	optional	[]
timeout	Maximum duration of the Cargo build command in seconds	Integer	optional	600
version	The version of cargo the resolver should use	String	optional	“1.58.1”

cargo_build_script

Compile and execute a rust build script to generate build attributes

This rules take the same arguments as rust_binary.

Example:

Suppose you have a crate with a cargo build script build.rs:

[workspace]/
    hello_lib/
        BUILD
        build.rs
        src/
            lib.rs

Then you want to use the build script in the following:

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

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

# This will run the build script from the root of the workspace, and
# collect the outputs.
cargo_build_script(
    name = "build_script",
    srcs = ["build.rs"],
    # Optional environment variables passed during build.rs compilation
    rustc_env = {
       "CARGO_PKG_VERSION": "0.1.2",
    },
    # Optional environment variables passed during build.rs execution.
    # Note that as the build script's working directory is not execroot,
    # execpath/location will return an absolute path, instead of a relative
    # one.
    build_script_env = {
        "SOME_TOOL_OR_FILE": "$(execpath @tool//:binary)"
    }
    # Optional data/tool dependencies
    data = ["@tool//:binary"],
)

rust_library(
    name = "hello_lib",
    srcs = [
        "src/lib.rs",
    ],
    deps = [":build_script"],
)

The hello_lib target will be build with the flags and the environment variables declared by the build script in addition to the file generated by it.

PARAMETERS

Name	Description	Default Value
name	The name for the underlying rule. This should be the name of the package being compiled, optionally with a suffix of _build_script.	none
crate_features	A list of features to enable for the build script.	[]
version	The semantic version (semver) of the crate.	None
deps	The dependencies of the crate.	[]
build_script_env	Environment variables for build scripts.	{}
data	Files needed by the build script.	[]
tools	Tools (executables) needed by the build script.	[]
links	Name of the native library this crate links against.	None
rustc_env	Environment variables to set in rustc when compiling the build script.	{}
visibility	Visibility to apply to the generated build script output.	None
tags	(list of str, optional): Tags to apply to the generated build script output.	None
kwargs	Forwards to the underlying rust_binary rule.	none

cargo_env

A helper for generating platform specific environment variables

load("@rules_rust//rust:defs.bzl", "rust_common")
load("@rules_rust//cargo:defs.bzl", "cargo_bootstrap_repository", "cargo_env")

cargo_bootstrap_repository(
    name = "bootstrapped_bin",
    cargo_lockfile = "//:Cargo.lock",
    cargo_toml = "//:Cargo.toml",
    srcs = ["//:resolver_srcs"],
    version = rust_common.default_version,
    binary = "my-crate-binary",
    env = {
        "x86_64-unknown-linux-gnu": cargo_env({
            "FOO": "BAR",
        }),
    },
    env_label = {
        "aarch64-unknown-linux-musl": cargo_env({
            "DOC": "//:README.md",
        }),
    }
)

PARAMETERS

Name	Description	Default Value
env	A map of environment variables	none

RETURNS

str: A json encoded string of the environment variables