This module provides a single place for all aspects, rules, and macros that are meant to have stardoc generated documentation.
Rules
cargo_bootstrap_repository
A rule for bootstrapping a Rust binary using Cargo
name
A unique name for this repository.
binary
The binary to build (the --bin
parameter for Cargo). If left empty, the repository name will be used.
build_mode
The build mode the binary should be built with
cargo_lockfile
The lockfile of the crate_universe resolver
cargo_toml
The path of the crate_universe resolver manifest (Cargo.toml
file)
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.
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.
iso_date
The iso_date of cargo binary the resolver should use. Note: This can only be set if version
is beta
or nightly
repo_mapping
A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.
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
).
rust_toolchain_repository_template
The template to use for finding the host rust_toolchain
repository. {version}
(eg. '1.53.0'), {triple}
(eg. 'x86_64-unknown-linux-gnu'), {system}
(eg. 'darwin'), and {arch}
(eg. 'aarch64') will be replaced in the string if present.
srcs
Souce files of the crate to build. Passing source files here can be used to trigger rebuilds when changes are made
version
The version of cargo the resolver should use
Macros and Functions
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.
name
The name for the underlying rule. This should be the name of the package being compiled, optionally with a suffix of _build_script.
crate_features
A list of features to enable for the build script.
version
The semantic version (semver) of the crate.
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.
rustc_env
Environment variables to set in rustc when compiling the build script.
visibility
Visibility to apply to the generated build script output.
tags
(list of str, optional): Tags to apply to the generated build script output.
kwargs
Forwards to the underlying rust_binary
rule.
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",
}),
}
)
env
A map of environment variables