Rust rules

capture_clippy_output

capture_clippy_output(name)

Control whether to print clippy output or store it to a file, using the configured error_format.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required

cargo_bootstrap_repository

cargo_bootstrap_repository(name, binary, build_mode, cargo_lockfile, cargo_toml, env, env_label,
                           iso_date, repo_mapping, rust_toolchain_repository_template, srcs, version)

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_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. String optional "rust*{system}*{arch}"
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 []
version The version of cargo the resolver should use String optional "1.57.0"

crate_universe

crate_universe(name, additional_registries, cargo_toml_files,
               default_registry_download_url_template, iso_date, lockfile, overrides, packages,
               repo_mapping, resolver, resolver_download_url_template, resolver_sha256s,
               rust_toolchain_repository_template, rust_toolchain_repository_tool_path, sha256s,
               supported_targets, version)

A rule for downloading Rust dependencies (crates).

WARNING: This rule experimental and subject to change without warning.

Environment Variables:

  • REPIN: Re-pin the lockfile if set (useful for repinning deps from multiple rulesets).
  • RULES_RUST_REPIN: Re-pin the lockfile if set (useful for only repinning Rust deps).
  • RULES_RUST_CRATE_UNIVERSE_RESOLVER_URL_OVERRIDE: Override URL to use to download resolver binary
    • for local paths use a file:// URL.
  • RULES_RUST_CRATE_UNIVERSE_RESOLVER_URL_OVERRIDE_SHA256: An optional sha256 value for the binary at the override url location.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
additional_registries Additional registries used by Cargo (see https://doc.rust-lang.org/cargo/reference/registries.html).

Dict of registry_name: index_url.
Dictionary: String -> String optional {}
cargo_toml_files A list of Cargo manifests (Cargo.toml files). List of labels optional []
default_registry_download_url_template A template for where to download crates from for the default crate registry. This must contain {version} and {crate} templates. String optional "https://crates.io/api/v1/crates/{crate}/{version}/download"
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 ""
lockfile The path to a file which stores pinned information about the generated dependency graph. this target must be a file and will be updated by the repository rule when the REPIN environment variable is set. If this is not set, dependencies will be re-resolved more often, setting this allows caching resolves, but will error if the cache is stale. Label optional None
overrides Mapping of crate name to specification overrides. See crate.override for more details. Dictionary: String -> String optional {}
packages A list of crate specifications. See crate.spec for more details. List of strings 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
resolver The label of a crate_universe resolver. Resolvers can be built using cargo_bootstrap_repository but if possible, it's recommended to stick with downloading a resoler via resolver_download_url_template. Label optional None
resolver_download_url_template URL template from which to download the resolver binary. {host_triple} and {extension} will be filled in according to the host platform. String optional "{host_triple}{extension}"
resolver_sha256s Dictionary of host_triple -> sha256 for resolver binary. Dictionary: String -> String optional {"aarch64-apple-darwin": "{aarch64-apple-darwin--sha256}", "aarch64-unknown-linux-gnu": "{aarch64-unknown-linux-gnu--sha256}", "x86_64-apple-darwin": "{x86_64-apple-darwin--sha256}", "x86_64-pc-windows-gnu": "{x86_64-pc-windows-gnu--sha256}", "x86_64-unknown-linux-gnu": "{x86_64-unknown-linux-gnu--sha256}"}
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. String optional "rust*{system}*{arch}"
rust_toolchain_repository_tool_path The relative path of the tools in the repository Dictionary: String -> String optional {"cargo": ":bin/cargo", "rustc": ":bin/rustc"}
sha256s The sha256 checksum of the desired rust artifacts Dictionary: String -> String optional {}
supported_targets A list of supported platform triples to consider when resoliving dependencies. List of strings optional ["aarch64-apple-darwin", "aarch64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc", "x86_64-unknown-freebsd", "x86_64-unknown-linux-gnu"]
version The version of cargo the resolver should use String optional "1.57.0"

error_format

error_format(name)

Change the --error-format flag from the command line with --@rules_rust//:error_format. See rustc documentation for valid values.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required

extra_rustc_flags

extra_rustc_flags(name)

Add additional rustc_flags from the command line with --@rules_rust//:extra_rustc_flags. This flag should only be used for flags that need to be applied across the entire build. For options that apply to individual crates, use the rustc_flags attribute on the individual crate's rule instead. NOTE: These flags are currently excluded from the exec configuration (proc-macros, cargo_build_script, etc).

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required

incompatible_flag

incompatible_flag(name, issue)

A rule defining an incompatible flag.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
issue The link to the github issue associated with this flag String required

rust_analyzer

rust_analyzer(name, targets)

Deprecated: gen_rust_project can now create a rust-project.json without a rust_analyzer rule.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
targets List of all targets to be included in the index List of labels optional []

rust_binary

rust_binary(name, aliases, compile_data, crate_features, crate_name, crate_root, crate_type, data,
            deps, edition, linker_script, out_binary, proc_macro_deps, rustc_env, rustc_env_files,
            rustc_flags, srcs, stamp, version)

Builds a Rust binary crate.

Example:

Suppose you have the following directory structure for a Rust project with a library crate, hello_lib, and a binary crate, hello_world that uses the hello_lib library:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs
    hello_world/
        BUILD
        src/
            main.rs

hello_lib/src/lib.rs:

pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) {
        println!("{} {}", &self.greeting, thing);
    }
}

hello_lib/BUILD:

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

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

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

hello_world/src/main.rs:

extern crate hello_lib;

fn main() {
    let hello = hello_lib::Greeter::new("Hello");
    hello.greet("world");
}

hello_world/BUILD:

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

rust_binary(
    name = "hello_world",
    srcs = ["src/main.rs"],
    deps = ["//hello_lib"],
)

Build and run hello_world:

$ bazel run //hello_world
INFO: Found 1 target...
Target //examples/rust/hello_world:hello_world up-to-date:
bazel-bin/examples/rust/hello_world/hello_world
INFO: Elapsed time: 1.308s, Critical Path: 1.22s

INFO: Running command line: bazel-bin/examples/rust/hello_world/hello_world
Hello world

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
aliases Remap crates to a new name or moniker for linkage to this target

These are other rust_library targets and will be presented as the new name given.
Dictionary: Label -> String optional {}
compile_data List of files used by this rule at compile time.

This attribute can be used to specify any data files that are embedded into the library, such as via the include_str! macro.
List of labels optional []
crate_features List of features to enable for this crate.

Features are defined in the code using the #[cfg(feature = "foo")] configuration option. The features listed here will be passed to rustc with --cfg feature="${feature_name}" flags.
List of strings optional []
crate_name Crate name to use for this target.

This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores.
String optional ""
crate_root The file that will be passed to rustc to be used for building this crate.

If crate_root is not set, then this rule will look for a lib.rs file (or main.rs for rust_binary) or the single file in srcs if srcs contains only one file.
Label optional None
crate_type Crate type that will be passed to rustc to be used for building this crate.

This option is a temporary workaround and should be used only when building for WebAssembly targets (//rust/platform:wasi and //rust/platform:wasm).
String optional "bin"
data List of files used by this rule at compile time and runtime.

If including data at compile time with include_str!() and similar, prefer compile_data over data, to prevent the data also being included in the runfiles.
List of labels optional []
deps List of other libraries to be linked to this library target.

These can be either other rust_library targets or cc_library targets if linking a native library.
List of labels optional []
edition The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. String optional ""
linker_script Link script to forward into linker via rustc options. Label optional None
out_binary Force a target, regardless of it's crate_type, to always mark the file as executable. This attribute is only used to support wasm targets but is expected to be removed following a resolution to https://github.com/bazelbuild/rules_rust/issues/771. Boolean optional False
proc_macro_deps List of rust_library targets with kind proc-macro used to help build this library target. List of labels optional []
rustc_env Dictionary of additional "key": "value" environment variables to set for rustc.

rust_test()/rust_binary() rules can use $(rootpath //package:target) to pass in the location of a generated file or external tool. Cargo build scripts that wish to expand locations should use cargo_build_script()'s build_script_env argument instead, as build scripts are run in a different environment - see cargo_build_script()'s documentation for more.
Dictionary: String -> String optional {}
rustc_env_files Files containing additional environment variables to set for rustc.

These files should contain a single variable per line, of format NAME=value, and newlines may be included in a value by ending a line with a trailing back-slash (\).

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.

Note that the variables here are subject to workspace status stamping should the stamp attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. NAME={WORKSPACE_STATUS_VARIABLE}.
List of labels optional []
rustc_flags List of compiler flags passed to rustc.

These strings are subject to Make variable expansion for predefined source/output path variables like $location, $execpath, and $rootpath. This expansion is useful if you wish to pass a generated file of arguments to rustc: @$(location //package:target).
List of strings optional []
srcs List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate.
List of labels optional []
stamp Whether to encode build information into the Rustc action. Possible values:

- stamp = 1: Always stamp the build information into the Rustc action, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.

- stamp = 0: Always replace build information by constant values. This gives good build result caching.

- stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.

Stamped targets are not rebuilt unless their dependencies change.

For example if a rust_library is stamped, and a rust_binary depends on that library, the stamped library won't be rebuilt when we change sources of the rust_binary. This is different from how cc_library.linkstamps behaves.
Integer optional -1
version A version to inject in the cargo environment variable. String optional "0.0.0"

rust_bindgen

rust_bindgen(name, bindgen_flags, cc_lib, clang_flags, header, rustfmt)

Generates a rust source file from a cc_library and a header.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
bindgen_flags Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. List of strings optional []
cc_lib The cc_library that contains the .h file. This is used to find the transitive includes. Label optional None
clang_flags Flags to pass directly to the clang executable. List of strings optional []
header The .h file to generate bindings for. Label optional None
rustfmt Enable or disable running rustfmt on the generated file. Boolean optional True

rust_bindgen_toolchain

rust_bindgen_toolchain(name, bindgen, clang, libclang, libstdcxx, rustfmt)

The tools required for the rust_bindgen rule.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
bindgen The label of a bindgen executable. Label optional None
clang The label of a clang executable. Label optional None
libclang A cc_library that provides bindgen's runtime dependency on libclang. Label optional None
libstdcxx A cc_library that satisfies libclang's libstdc++ dependency. This is used to make the execution of clang hermetic. If None, system libraries will be used instead. Label optional None
rustfmt The label of a rustfmt executable. If this is not provided, falls back to the rust_toolchain rustfmt. Label optional None

rust_clippy

rust_clippy(name, deps)

Executes the clippy checker on a specific target.

Similar to rust_clippy_aspect, but allows specifying a list of dependencies within the build system.

For example, given the following example targets:

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

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

rust_test(
    name = "greeting_test",
    srcs = ["tests/greeting.rs"],
    deps = [":hello_lib"],
)

Rust clippy can be set as a build target with the following:

load("@rules_rust//rust:defs.bzl", "rust_clippy")

rust_clippy(
    name = "hello_library_clippy",
    testonly = True,
    deps = [
        ":hello_lib",
        ":greeting_test",
    ],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Rust targets to run clippy on. List of labels optional []

rust_doc

rust_doc(name, crate, dep, html_after_content, html_before_content, html_in_header, markdown_css)

Generates code documentation.

Example: Suppose you have the following directory structure for a Rust library crate:

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

To build rustdoc documentation for the hello_lib crate, define a rust_doc rule that depends on the the hello_lib rust_library target:

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

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc")

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

rust_doc(
    name = "hello_lib_doc",
    crate = ":hello_lib",
)

Running bazel build //hello_lib:hello_lib_doc will build a zip file containing the documentation for the hello_lib library crate generated by rustdoc.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
crate The label of the target to generate code documentation for.

rust_doc can generate HTML code documentation for the source files of rust_library or rust_binary targets.
Label optional None
dep deprecated: use crate Label optional None
html_after_content File to add in <body>, after content. Label optional None
html_before_content File to add in <body>, before content. Label optional None
html_in_header File to add to <head>. Label optional None
markdown_css CSS files to include via <link> in a rendered Markdown file. List of labels optional []

rust_doc_test

rust_doc_test(name, crate, dep)

Runs Rust documentation tests.

Example:

Suppose you have the following directory structure for a Rust library crate:

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

To run documentation tests for the hello_lib crate, define a rust_doc_test target that depends on the hello_lib rust_library target:

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

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc_test")

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

rust_doc_test(
    name = "hello_lib_doc_test",
    crate = ":hello_lib",
)

Running bazel test //hello_lib:hello_lib_doc_test will run all documentation tests for the hello_lib library crate.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
crate The label of the target to generate code documentation for. rust_doc_test can generate HTML code documentation for the source files of rust_library or rust_binary targets. Label optional None
dep deprecated: use crate Label optional None

rust_grpc_library

rust_grpc_library(name, deps, rust_deps)

Builds a Rust library crate from a set of proto_librarys suitable for gRPC.

Example:

load("//proto:proto.bzl", "rust_grpc_library")

proto_library(
    name = "my_proto",
    srcs = ["my.proto"]
)

rust_grpc_library(
    name = "rust",
    deps = [":my_proto"],
)

rust_binary(
    name = "my_service",
    srcs = ["my_service.rs"],
    deps = [":rust"],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding gRPC stubs. List of labels required
rust_deps The crates the generated library depends on. List of labels optional []

rust_library

rust_library(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
             edition, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, stamp, version)

Builds a Rust library crate.

Example:

Suppose you have the following directory structure for a simple Rust library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            greeter.rs
            lib.rs

hello_lib/src/greeter.rs:

pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) {
        println!("{} {}", &self.greeting, thing);
    }
}

hello_lib/src/lib.rs:

pub mod greeter;

hello_lib/BUILD:

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

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

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

Build the library:

$ bazel build //hello_lib
INFO: Found 1 target...
Target //examples/rust/hello_lib:hello_lib up-to-date:
bazel-bin/examples/rust/hello_lib/libhello_lib.rlib
INFO: Elapsed time: 1.245s, Critical Path: 1.01s

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
aliases Remap crates to a new name or moniker for linkage to this target

These are other rust_library targets and will be presented as the new name given.
Dictionary: Label -> String optional {}
compile_data List of files used by this rule at compile time.

This attribute can be used to specify any data files that are embedded into the library, such as via the include_str! macro.
List of labels optional []
crate_features List of features to enable for this crate.

Features are defined in the code using the #[cfg(feature = "foo")] configuration option. The features listed here will be passed to rustc with --cfg feature="${feature_name}" flags.
List of strings optional []
crate_name Crate name to use for this target.

This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores.
String optional ""
crate_root The file that will be passed to rustc to be used for building this crate.

If crate_root is not set, then this rule will look for a lib.rs file (or main.rs for rust_binary) or the single file in srcs if srcs contains only one file.
Label optional None
data List of files used by this rule at compile time and runtime.

If including data at compile time with include_str!() and similar, prefer compile_data over data, to prevent the data also being included in the runfiles.
List of labels optional []
deps List of other libraries to be linked to this library target.

These can be either other rust_library targets or cc_library targets if linking a native library.
List of labels optional []
edition The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. String optional ""
proc_macro_deps List of rust_library targets with kind proc-macro used to help build this library target. List of labels optional []
rustc_env Dictionary of additional "key": "value" environment variables to set for rustc.

rust_test()/rust_binary() rules can use $(rootpath //package:target) to pass in the location of a generated file or external tool. Cargo build scripts that wish to expand locations should use cargo_build_script()'s build_script_env argument instead, as build scripts are run in a different environment - see cargo_build_script()'s documentation for more.
Dictionary: String -> String optional {}
rustc_env_files Files containing additional environment variables to set for rustc.

These files should contain a single variable per line, of format NAME=value, and newlines may be included in a value by ending a line with a trailing back-slash (\).

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.

Note that the variables here are subject to workspace status stamping should the stamp attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. NAME={WORKSPACE_STATUS_VARIABLE}.
List of labels optional []
rustc_flags List of compiler flags passed to rustc.

These strings are subject to Make variable expansion for predefined source/output path variables like $location, $execpath, and $rootpath. This expansion is useful if you wish to pass a generated file of arguments to rustc: @$(location //package:target).
List of strings optional []
srcs List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate.
List of labels optional []
stamp Whether to encode build information into the Rustc action. Possible values:

- stamp = 1: Always stamp the build information into the Rustc action, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.

- stamp = 0: Always replace build information by constant values. This gives good build result caching.

- stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.

Stamped targets are not rebuilt unless their dependencies change.

For example if a rust_library is stamped, and a rust_binary depends on that library, the stamped library won't be rebuilt when we change sources of the rust_binary. This is different from how cc_library.linkstamps behaves.
Integer optional -1
version A version to inject in the cargo environment variable. String optional "0.0.0"

rust_proc_macro

rust_proc_macro(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
                edition, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, stamp,
                version)

Builds a Rust proc-macro crate.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
aliases Remap crates to a new name or moniker for linkage to this target

These are other rust_library targets and will be presented as the new name given.
Dictionary: Label -> String optional {}
compile_data List of files used by this rule at compile time.

This attribute can be used to specify any data files that are embedded into the library, such as via the include_str! macro.
List of labels optional []
crate_features List of features to enable for this crate.

Features are defined in the code using the #[cfg(feature = "foo")] configuration option. The features listed here will be passed to rustc with --cfg feature="${feature_name}" flags.
List of strings optional []
crate_name Crate name to use for this target.

This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores.
String optional ""
crate_root The file that will be passed to rustc to be used for building this crate.

If crate_root is not set, then this rule will look for a lib.rs file (or main.rs for rust_binary) or the single file in srcs if srcs contains only one file.
Label optional None
data List of files used by this rule at compile time and runtime.

If including data at compile time with include_str!() and similar, prefer compile_data over data, to prevent the data also being included in the runfiles.
List of labels optional []
deps List of other libraries to be linked to this library target.

These can be either other rust_library targets or cc_library targets if linking a native library.
List of labels optional []
edition The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. String optional ""
proc_macro_deps List of rust_library targets with kind proc-macro used to help build this library target. List of labels optional []
rustc_env Dictionary of additional "key": "value" environment variables to set for rustc.

rust_test()/rust_binary() rules can use $(rootpath //package:target) to pass in the location of a generated file or external tool. Cargo build scripts that wish to expand locations should use cargo_build_script()'s build_script_env argument instead, as build scripts are run in a different environment - see cargo_build_script()'s documentation for more.
Dictionary: String -> String optional {}
rustc_env_files Files containing additional environment variables to set for rustc.

These files should contain a single variable per line, of format NAME=value, and newlines may be included in a value by ending a line with a trailing back-slash (\).

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.

Note that the variables here are subject to workspace status stamping should the stamp attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. NAME={WORKSPACE_STATUS_VARIABLE}.
List of labels optional []
rustc_flags List of compiler flags passed to rustc.

These strings are subject to Make variable expansion for predefined source/output path variables like $location, $execpath, and $rootpath. This expansion is useful if you wish to pass a generated file of arguments to rustc: @$(location //package:target).
List of strings optional []
srcs List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate.
List of labels optional []
stamp Whether to encode build information into the Rustc action. Possible values:

- stamp = 1: Always stamp the build information into the Rustc action, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.

- stamp = 0: Always replace build information by constant values. This gives good build result caching.

- stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.

Stamped targets are not rebuilt unless their dependencies change.

For example if a rust_library is stamped, and a rust_binary depends on that library, the stamped library won't be rebuilt when we change sources of the rust_binary. This is different from how cc_library.linkstamps behaves.
Integer optional -1
version A version to inject in the cargo environment variable. String optional "0.0.0"

rust_proto_library

rust_proto_library(name, deps, rust_deps)

Builds a Rust library crate from a set of proto_librarys.

Example:

load("@rules_rust//proto:proto.bzl", "rust_proto_library")

proto_library(
    name = "my_proto",
    srcs = ["my.proto"]
)

rust_proto_library(
    name = "rust",
    deps = [":my_proto"],
)

rust_binary(
    name = "my_proto_binary",
    srcs = ["my_proto_binary.rs"],
    deps = [":rust"],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding stubs. List of labels required
rust_deps The crates the generated library depends on. List of labels optional []

rust_proto_toolchain

rust_proto_toolchain(name, edition, grpc_compile_deps, grpc_plugin, proto_compile_deps,
                     proto_plugin, protoc)

Declares a Rust Proto toolchain for use.

This is used to configure proto compilation and can be used to set different protobuf compiler plugin.

Example:

Suppose a new nicer gRPC plugin has came out. The new plugin can be used in Bazel by defining a new toolchain definition and declaration:

load('@rules_rust//proto:toolchain.bzl', 'rust_proto_toolchain')

rust_proto_toolchain(
   name="rust_proto_impl",
   grpc_plugin="@rust_grpc//:grpc_plugin",
   grpc_compile_deps=["@rust_grpc//:grpc_deps"],
)

toolchain(
    name="rust_proto",
    exec_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    target_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    toolchain = ":rust_proto_impl",
)

Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the --extra_toolchains flag for Bazel, and it will be used.

See @rules_rust//proto:BUILD for examples of defining the toolchain.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
edition The edition used by the generated rust source. String optional "2018"
grpc_compile_deps The crates the generated grpc libraries depends on. List of labels optional [Label("//proto/raze:protobuf"), Label("//proto/raze:grpc"), Label("//proto/raze:tls_api"), Label("//proto/raze:tls_api_stub")]
grpc_plugin The location of the Rust protobuf compiler plugin to generate rust gRPC stubs. Label optional //proto:protoc_gen_rust_grpc
proto_compile_deps The crates the generated protobuf libraries depends on. List of labels optional [Label("//proto/raze:protobuf")]
proto_plugin The location of the Rust protobuf compiler plugin used to generate rust sources. Label optional //proto:protoc_gen_rust
protoc The location of the protoc binary. It should be an executable target. Label optional @com_google_protobuf//:protoc

rust_shared_library

rust_shared_library(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
                    edition, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, stamp,
                    version)

Builds a Rust shared library.

This shared library will contain all transitively reachable crates and native objects. It is meant to be used when producing an artifact that is then consumed by some other build system (for example to produce a shared library that Python program links against).

This rule provides CcInfo, so it can be used everywhere Bazel expects rules_cc.

When building the whole binary in Bazel, use rust_library instead.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
aliases Remap crates to a new name or moniker for linkage to this target

These are other rust_library targets and will be presented as the new name given.
Dictionary: Label -> String optional {}
compile_data List of files used by this rule at compile time.

This attribute can be used to specify any data files that are embedded into the library, such as via the include_str! macro.
List of labels optional []
crate_features List of features to enable for this crate.

Features are defined in the code using the #[cfg(feature = "foo")] configuration option. The features listed here will be passed to rustc with --cfg feature="${feature_name}" flags.
List of strings optional []
crate_name Crate name to use for this target.

This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores.
String optional ""
crate_root The file that will be passed to rustc to be used for building this crate.

If crate_root is not set, then this rule will look for a lib.rs file (or main.rs for rust_binary) or the single file in srcs if srcs contains only one file.
Label optional None
data List of files used by this rule at compile time and runtime.

If including data at compile time with include_str!() and similar, prefer compile_data over data, to prevent the data also being included in the runfiles.
List of labels optional []
deps List of other libraries to be linked to this library target.

These can be either other rust_library targets or cc_library targets if linking a native library.
List of labels optional []
edition The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. String optional ""
proc_macro_deps List of rust_library targets with kind proc-macro used to help build this library target. List of labels optional []
rustc_env Dictionary of additional "key": "value" environment variables to set for rustc.

rust_test()/rust_binary() rules can use $(rootpath //package:target) to pass in the location of a generated file or external tool. Cargo build scripts that wish to expand locations should use cargo_build_script()'s build_script_env argument instead, as build scripts are run in a different environment - see cargo_build_script()'s documentation for more.
Dictionary: String -> String optional {}
rustc_env_files Files containing additional environment variables to set for rustc.

These files should contain a single variable per line, of format NAME=value, and newlines may be included in a value by ending a line with a trailing back-slash (\).

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.

Note that the variables here are subject to workspace status stamping should the stamp attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. NAME={WORKSPACE_STATUS_VARIABLE}.
List of labels optional []
rustc_flags List of compiler flags passed to rustc.

These strings are subject to Make variable expansion for predefined source/output path variables like $location, $execpath, and $rootpath. This expansion is useful if you wish to pass a generated file of arguments to rustc: @$(location //package:target).
List of strings optional []
srcs List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate.
List of labels optional []
stamp Whether to encode build information into the Rustc action. Possible values:

- stamp = 1: Always stamp the build information into the Rustc action, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.

- stamp = 0: Always replace build information by constant values. This gives good build result caching.

- stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.

Stamped targets are not rebuilt unless their dependencies change.

For example if a rust_library is stamped, and a rust_binary depends on that library, the stamped library won't be rebuilt when we change sources of the rust_binary. This is different from how cc_library.linkstamps behaves.
Integer optional -1
version A version to inject in the cargo environment variable. String optional "0.0.0"

rust_static_library

rust_static_library(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
                    edition, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, stamp,
                    version)

Builds a Rust static library.

This static library will contain all transitively reachable crates and native objects. It is meant to be used when producing an artifact that is then consumed by some other build system (for example to produce an archive that Python program links against).

This rule provides CcInfo, so it can be used everywhere Bazel expects rules_cc.

When building the whole binary in Bazel, use rust_library instead.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
aliases Remap crates to a new name or moniker for linkage to this target

These are other rust_library targets and will be presented as the new name given.
Dictionary: Label -> String optional {}
compile_data List of files used by this rule at compile time.

This attribute can be used to specify any data files that are embedded into the library, such as via the include_str! macro.
List of labels optional []
crate_features List of features to enable for this crate.

Features are defined in the code using the #[cfg(feature = "foo")] configuration option. The features listed here will be passed to rustc with --cfg feature="${feature_name}" flags.
List of strings optional []
crate_name Crate name to use for this target.

This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores.
String optional ""
crate_root The file that will be passed to rustc to be used for building this crate.

If crate_root is not set, then this rule will look for a lib.rs file (or main.rs for rust_binary) or the single file in srcs if srcs contains only one file.
Label optional None
data List of files used by this rule at compile time and runtime.

If including data at compile time with include_str!() and similar, prefer compile_data over data, to prevent the data also being included in the runfiles.
List of labels optional []
deps List of other libraries to be linked to this library target.

These can be either other rust_library targets or cc_library targets if linking a native library.
List of labels optional []
edition The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. String optional ""
proc_macro_deps List of rust_library targets with kind proc-macro used to help build this library target. List of labels optional []
rustc_env Dictionary of additional "key": "value" environment variables to set for rustc.

rust_test()/rust_binary() rules can use $(rootpath //package:target) to pass in the location of a generated file or external tool. Cargo build scripts that wish to expand locations should use cargo_build_script()'s build_script_env argument instead, as build scripts are run in a different environment - see cargo_build_script()'s documentation for more.
Dictionary: String -> String optional {}
rustc_env_files Files containing additional environment variables to set for rustc.

These files should contain a single variable per line, of format NAME=value, and newlines may be included in a value by ending a line with a trailing back-slash (\).

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.

Note that the variables here are subject to workspace status stamping should the stamp attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. NAME={WORKSPACE_STATUS_VARIABLE}.
List of labels optional []
rustc_flags List of compiler flags passed to rustc.

These strings are subject to Make variable expansion for predefined source/output path variables like $location, $execpath, and $rootpath. This expansion is useful if you wish to pass a generated file of arguments to rustc: @$(location //package:target).
List of strings optional []
srcs List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate.
List of labels optional []
stamp Whether to encode build information into the Rustc action. Possible values:

- stamp = 1: Always stamp the build information into the Rustc action, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.

- stamp = 0: Always replace build information by constant values. This gives good build result caching.

- stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.

Stamped targets are not rebuilt unless their dependencies change.

For example if a rust_library is stamped, and a rust_binary depends on that library, the stamped library won't be rebuilt when we change sources of the rust_binary. This is different from how cc_library.linkstamps behaves.
Integer optional -1
version A version to inject in the cargo environment variable. String optional "0.0.0"

rust_stdlib_filegroup

rust_stdlib_filegroup(name, srcs)

A dedicated filegroup-like rule for Rust stdlib artifacts.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs The list of targets/files that are components of the rust-stdlib file group List of labels required

rust_test

rust_test(name, aliases, compile_data, crate, crate_features, crate_name, crate_root, data, deps,
          edition, env, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, stamp,
          use_libtest_harness, version)

Builds a Rust test crate.

Examples:

Suppose you have the following directory structure for a Rust library crate with unit test code in the library sources:

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

hello_lib/src/lib.rs:

pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) -> String {
        format!("{} {}", &self.greeting, thing)
    }
}

#[cfg(test)]
mod test {
    use super::Greeter;

    #[test]
    fn test_greeting() {
        let hello = Greeter::new("Hi");
        assert_eq!("Hi Rust", hello.greet("Rust"));
    }
}

To build and run the tests, simply add a rust_test rule with no srcs and only depends on the hello_lib rust_library target:

hello_lib/BUILD:

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

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

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

rust_test(
    name = "hello_lib_test",
    deps = [":hello_lib"],
)

Run the test with bazel build //hello_lib:hello_lib_test.

To run a crate or lib with the #[cfg(test)] configuration, handling inline tests, you should specify the crate directly like so.

rust_test(
    name = "hello_lib_test",
    crate = ":hello_lib",
    # You may add other deps that are specific to the test configuration
    deps = ["//some/dev/dep"],
)

Example: test directory

Integration tests that live in the tests directory, they are essentially built as separate crates. Suppose you have the following directory structure where greeting.rs is an integration test for the hello_lib library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs
        tests/
            greeting.rs

hello_lib/tests/greeting.rs:

extern crate hello_lib;

use hello_lib;

#[test]
fn test_greeting() {
    let hello = greeter::Greeter::new("Hello");
    assert_eq!("Hello world", hello.greeting("world"));
}

To build the greeting.rs integration test, simply add a rust_test target with greeting.rs in srcs and a dependency on the hello_lib target:

hello_lib/BUILD:

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

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

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

rust_test(
    name = "greeting_test",
    srcs = ["tests/greeting.rs"],
    deps = [":hello_lib"],
)

Run the test with bazel build //hello_lib:hello_lib_test.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
aliases Remap crates to a new name or moniker for linkage to this target

These are other rust_library targets and will be presented as the new name given.
Dictionary: Label -> String optional {}
compile_data List of files used by this rule at compile time.

This attribute can be used to specify any data files that are embedded into the library, such as via the include_str! macro.
List of labels optional []
crate Target inline tests declared in the given crate

These tests are typically those that would be held out under #[cfg(test)] declarations.
Label optional None
crate_features List of features to enable for this crate.

Features are defined in the code using the #[cfg(feature = "foo")] configuration option. The features listed here will be passed to rustc with --cfg feature="${feature_name}" flags.
List of strings optional []
crate_name Crate name to use for this target.

This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores.
String optional ""
crate_root The file that will be passed to rustc to be used for building this crate.

If crate_root is not set, then this rule will look for a lib.rs file (or main.rs for rust_binary) or the single file in srcs if srcs contains only one file.
Label optional None
data List of files used by this rule at compile time and runtime.

If including data at compile time with include_str!() and similar, prefer compile_data over data, to prevent the data also being included in the runfiles.
List of labels optional []
deps List of other libraries to be linked to this library target.

These can be either other rust_library targets or cc_library targets if linking a native library.
List of labels optional []
edition The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. String optional ""
env Specifies additional environment variables to set when the test is executed by bazel test. Values are subject to $(rootpath), $(execpath), location, and "Make variable" substitution.

Execpath returns absolute path, and in order to be able to construct the absolute path we need to wrap the test binary in a launcher. Using a launcher comes with complications, such as more complicated debugger attachment.
Dictionary: String -> String optional {}
proc_macro_deps List of rust_library targets with kind proc-macro used to help build this library target. List of labels optional []
rustc_env Dictionary of additional "key": "value" environment variables to set for rustc.

rust_test()/rust_binary() rules can use $(rootpath //package:target) to pass in the location of a generated file or external tool. Cargo build scripts that wish to expand locations should use cargo_build_script()'s build_script_env argument instead, as build scripts are run in a different environment - see cargo_build_script()'s documentation for more.
Dictionary: String -> String optional {}
rustc_env_files Files containing additional environment variables to set for rustc.

These files should contain a single variable per line, of format NAME=value, and newlines may be included in a value by ending a line with a trailing back-slash (\).

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.

Note that the variables here are subject to workspace status stamping should the stamp attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. NAME={WORKSPACE_STATUS_VARIABLE}.
List of labels optional []
rustc_flags List of compiler flags passed to rustc.

These strings are subject to Make variable expansion for predefined source/output path variables like $location, $execpath, and $rootpath. This expansion is useful if you wish to pass a generated file of arguments to rustc: @$(location //package:target).
List of strings optional []
srcs List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate.
List of labels optional []
stamp Whether to encode build information into the Rustc action. Possible values:

- stamp = 1: Always stamp the build information into the Rustc action, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.

- stamp = 0: Always replace build information by constant values. This gives good build result caching.

- stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.

Stamped targets are not rebuilt unless their dependencies change.

For example if a rust_library is stamped, and a rust_binary depends on that library, the stamped library won't be rebuilt when we change sources of the rust_binary. This is different from how cc_library.linkstamps behaves.
Integer optional -1
use_libtest_harness Whether to use libtest. Boolean optional True
version A version to inject in the cargo environment variable. String optional "0.0.0"

rust_toolchain

rust_toolchain(name, allocator_library, binary_ext, cargo, clippy_driver, debug_info,
               default_edition, dylib_ext, exec_triple, opt_level, os, rust_doc, rust_lib, rustc,
               rustc_lib, rustc_srcs, rustfmt, staticlib_ext, stdlib_linkflags, target_json,
               target_triple)

Declares a Rust toolchain for use.

This is for declaring a custom toolchain, eg. for configuring a particular version of rust or supporting a new platform.

Example:

Suppose the core rust team has ported the compiler to a new target CPU, called cpuX. This support can be used in Bazel by defining a new toolchain definition and declaration:

load('@rules_rust//rust:toolchain.bzl', 'rust_toolchain')

rust_toolchain(
    name = "rust_cpuX_impl",
    rustc = "@rust_cpuX//:rustc",
    rustc_lib = "@rust_cpuX//:rustc_lib",
    rust_lib = "@rust_cpuX//:rust_lib",
    rust_doc = "@rust_cpuX//:rustdoc",
    binary_ext = "",
    staticlib_ext = ".a",
    dylib_ext = ".so",
    stdlib_linkflags = ["-lpthread", "-ldl"],
    os = "linux",
)

toolchain(
    name = "rust_cpuX",
    exec_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    target_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    toolchain = ":rust_cpuX_impl",
)

Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the "--extra_toolchains" flag for Bazel, and it will be used.

See @rules_rust//rust:repositories.bzl for examples of defining the @rust_cpuX repository with the actual binaries and libraries.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
allocator_library Target that provides allocator functions when rust_library targets are embedded in a cc_binary. Label optional None
binary_ext The extension for binaries created from rustc. String required
cargo The location of the cargo binary. Can be a direct source or a filegroup containing one item. Label optional None
clippy_driver The location of the clippy-driver binary. Can be a direct source or a filegroup containing one item. Label optional None
debug_info Rustc debug info levels per opt level Dictionary: String -> String optional {"dbg": "2", "fastbuild": "0", "opt": "0"}
default_edition The edition to use for rust_* rules that don't specify an edition. String optional "2018"
dylib_ext The extension for dynamic libraries created from rustc. String required
exec_triple The platform triple for the toolchains execution environment. For more details see: https://docs.bazel.build/versions/master/skylark/rules.html#configurations String optional ""
opt_level Rustc optimization levels. Dictionary: String -> String optional {"dbg": "0", "fastbuild": "0", "opt": "3"}
os The operating system for the current toolchain String required
rust_doc The location of the rustdoc binary. Can be a direct source or a filegroup containing one item. Label optional None
rust_lib The rust standard library. Label optional None
rustc The location of the rustc binary. Can be a direct source or a filegroup containing one item. Label optional None
rustc_lib The libraries used by rustc during compilation. Label optional None
rustc_srcs The source code of rustc. Label optional None
rustfmt The location of the rustfmt binary. Can be a direct source or a filegroup containing one item. Label optional None
staticlib_ext The extension for static libraries created from rustc. String required
stdlib_linkflags Additional linker flags to use when Rust std lib is linked by a C++ linker (rustc will deal with these automatically). Subject to location expansion with respect to the srcs of the rust_lib attribute. List of strings required
target_json Override the target_triple with a custom target specification. For more details see: https://doc.rust-lang.org/rustc/targets/custom.html Label optional None
target_triple The platform triple for the toolchains target environment. For more details see: https://docs.bazel.build/versions/master/skylark/rules.html#configurations String optional ""

rust_toolchain_repository

rust_toolchain_repository(name, auth, dev_components, edition, exec_triple, extra_target_triples,
                          include_rustc_srcs, iso_date, repo_mapping, rustfmt_version, sha256s,
                          toolchain_name_prefix, urls, version)

Composes a single workspace containing the toolchain components for compiling on a given platform to a series of target platforms.

A given instance of this rule should be accompanied by a rust_toolchain_repository_proxy invocation to declare its toolchains to Bazel; the indirection allows separating toolchain selection from toolchain fetching.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
auth Auth object compatible with repository_ctx.download to use when downloading files. See https://docs.bazel.build/versions/main/skylark/lib/repository_ctx.html#download for more details. Dictionary: String -> String optional {}
dev_components Whether to download the rustc-dev components (defaults to False). Requires version to be "nightly". Boolean optional False
edition The rust edition to be used by default. String optional "2018"
exec_triple The Rust-style target that this compiler runs on String required
extra_target_triples Additional rust-style targets that this set of toolchains should support. List of strings optional []
include_rustc_srcs Whether to download and unpack the rustc source files. These are very large, and slow to unpack, but are required to support rust analyzer. An environment variable RULES_RUST_TOOLCHAIN_INCLUDE_RUSTC_SRCS can also be used to control this attribute. This variable will take precedence over the hard coded attribute. Setting it to true to activates this attribute where all other values deactivate it. Boolean optional False
iso_date The date of the tool (or None, if the version is a specific version). 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
rustfmt_version The version of the tool among "nightly", "beta", or an exact version. String optional ""
sha256s A dict associating tool subdirectories to sha256 hashes. See rust_repositories for more details. Dictionary: String -> String optional {}
toolchain_name_prefix The per-target prefix expected for the rust_toolchain declarations in the parent workspace. String optional ""
urls A list of mirror urls containing the tools from the Rust-lang static file server. These must contain the '{}' used to substitute the tool being fetched (using .format). List of strings optional ["https://static.rust-lang.org/dist/{}.tar.gz"]
version The version of the tool among "nightly", "beta", or an exact version. String required

rust_toolchain_repository_proxy

rust_toolchain_repository_proxy(name, exec_triple, extra_target_triples, parent_workspace_name,
                                repo_mapping, toolchain_name_prefix)

Generates a toolchain-bearing repository that declares the toolchains from some other rust_toolchain_repository.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
exec_triple The Rust-style target triple for the compilation platform String required
extra_target_triples The Rust-style triples for extra compilation targets List of strings optional []
parent_workspace_name The name of the other rust_toolchain_repository String required
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
toolchain_name_prefix The per-target prefix expected for the rust_toolchain declarations in the parent workspace. String optional ""

rust_wasm_bindgen

rust_wasm_bindgen(name, bindgen_flags, target, wasm_file)

Generates javascript and typescript bindings for a webassembly module using wasm-bindgen.

To use the Rust WebAssembly bindgen rules, add the following to your WORKSPACE file to add the external repositories for the Rust bindgen toolchain (in addition to the Rust rules setup):

load("@rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositories")

rust_wasm_bindgen_repositories()

For more details on rust_wasm_bindgen_repositories, see here.

An example of this rule in use can be seen at @rules_rust//examples/wasm

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
bindgen_flags Flags to pass directly to the bindgen executable. See https://github.com/rustwasm/wasm-bindgen/ for details. List of strings optional []
target The type of output to generate. See https://rustwasm.github.io/wasm-bindgen/reference/deployment.html for details. String optional "bundler"
wasm_file The .wasm file or crate to generate bindings for. Label required

rust_wasm_bindgen_toolchain

rust_wasm_bindgen_toolchain(name, bindgen)

The tools required for the rust_wasm_bindgen rule.

In cases where users want to control or change the version of wasm-bindgen used by rust_wasm_bindgen, a unique toolchain can be created as in the example below:

load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")

rust_bindgen_toolchain(
    bindgen = "//my/cargo_raze:cargo_bin_wasm_bindgen",
)

toolchain(
    name = "wasm_bindgen_toolchain",
    toolchain = "wasm_bindgen_toolchain_impl",
    toolchain_type = "@rules_rust//wasm_bindgen:wasm_bindgen_toolchain",
)

Now that you have your own toolchain, you need to register it by inserting the following statement in your WORKSPACE file:

register_toolchains("//my/toolchains:wasm_bindgen_toolchain")

For additional information, see the Bazel toolchains documentation.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
bindgen The label of a wasm-bindgen-cli executable. Label optional None

rustfmt_test

rustfmt_test(name, targets)

A test rule for performing rustfmt --check on a set of targets

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
targets Rust targets to run rustfmt --check on. List of labels optional []

CrateInfo

CrateInfo(aliases, compile_data, deps, edition, is_test, name, output, owner, proc_macro_deps, root,
          rustc_env, srcs, type, wrapped_crate_type)

A provider containing general Crate information.

FIELDS

| Name | Description | | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | aliases | Dict[Label, String]: Renamed and aliased crates | | compile_data | depset[File]: Compile data required by this crate. | | deps | depset[DepVariantInfo | Target]: This crate's (rust or cc) dependencies' providers. | | edition | str: The edition of this crate. | | is_test | bool: If the crate is being compiled in a test context | | name | str: The name of this crate. | | output | File: The output File that will be produced, depends on crate type. | | owner | Label: The label of the target that produced this CrateInfo | | proc_macro_deps | depset[DepVariantInfo | Target]: This crate's rust proc_macro dependencies' providers. | | root | File: The source File entrypoint to this crate, eg. lib.rs | | rustc_env | Dict[String, String]: Additional "key": "value" environment variables to set for rustc. | | srcs | depset[File]: All source Files that are part of the crate. | | type | str: The type of this crate (see rustc --crate-type). | | wrapped_crate_type | str, optional: The original crate type for targets generated using a previously defined crate (typically tests using the rust_test::crate attribute) |

DepInfo

DepInfo(dep_env, direct_crates, transitive_build_infos, transitive_crate_outputs, transitive_crates,
        transitive_libs, transitive_noncrates)

A provider containing information about a Crate's dependencies.

FIELDS

Name Description
dep_env File: File with environment variables direct dependencies build scripts rely upon.
direct_crates depset[AliasableDepInfo]
transitive_build_infos depset[BuildInfo]
transitive_crate_outputs depset[File]: All transitive crate outputs.
transitive_crates depset[CrateInfo]
transitive_libs List[File]: (Deprecated, see https://github.com/bazelbuild/rules_rust/issues/1051) All transitive dependencies, not filtered by type.
transitive_noncrates depset[LinkerInput]: All transitive dependencies that aren't crates.

StdLibInfo

StdLibInfo(alloc_files, between_alloc_and_core_files, between_core_and_std_files, core_files,
           dot_a_files, self_contained_files, srcs, std_files, std_rlibs)

A collection of files either found within the rust-stdlib artifact or generated based on existing files.

FIELDS

Name Description
alloc_files List[File]: .a files related to the alloc module.
between_alloc_and_core_files List[File]: .a files related to the compiler_builtins module.
between_core_and_std_files List[File]: .a files related to all modules except adler, alloc, compiler_builtins, core, and std.
core_files List[File]: .a files related to the core and adler modules
dot_a_files Depset[File]: Generated .a files
self_contained_files List[File]: All .o files from the self-contained directory.
srcs List[Target]: All targets from the original srcs attribute.
std_files Depset[File]: .a files associated with the std module.
std_rlibs List[File]: All .rlib files

cargo_build_script

cargo_build_script(name, crate_features, version, deps, build_script_env, data, tools, links,
                   rustc_env, visibility, tags, kwargs)

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

cargo_env(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

crate.spec

crate.spec(name, semver, features)

A simple crate definition for use in the crate_universe rule.

WARNING: This rule experimental and subject to change without warning.

Example:

load("@rules_rust//crate_universe:defs.bzl", "crate_universe", "crate")

crate_universe(
    name = "spec_example",
    packages = [
        crate.spec(
            name = "lazy_static",
            semver = "=1.4",
        ),
    ],
)

PARAMETERS

Name Description Default Value
name The name of the crate as it would appear in a crate registry. none
semver The desired version (semver) of the crate none
features A list of desired features. None

RETURNS

str: A json encoded struct of crate info

crate.override

crate.override(extra_bazel_data_deps, extra_bazel_deps, extra_build_script_bazel_data_deps,
               extra_build_script_bazel_deps, extra_build_script_env_vars, extra_rustc_env_vars,
               features_to_remove)

A map of overrides for a particular crate

WARNING: This rule experimental and subject to change without warning.

Example:

load("@rules_rust//crate_universe:defs.bzl", "crate_universe", "crate")

crate_universe(
    name = "override_example",
    # [...]
    overrides = {
        "tokio": crate.override(
            extra_rustc_env_vars = {
                "MY_ENV_VAR": "MY_ENV_VALUE",
            },
            extra_build_script_env_vars = {
                "MY_BUILD_SCRIPT_ENV_VAR": "MY_ENV_VALUE",
            },
            extra_bazel_deps = {
                # Extra dependencies are per target. They are additive.
                "cfg(unix)": ["@somerepo//:foo"],  # cfg() predicate.
                "x86_64-apple-darwin": ["@somerepo//:bar"],  # Specific triple.
                "cfg(all())": ["@somerepo//:baz"],  # Applies to all targets ("regular dependency").
            },
            extra_build_script_bazel_deps = {
                # Extra dependencies are per target. They are additive.
                "cfg(unix)": ["@buildscriptdep//:foo"],
                "x86_64-apple-darwin": ["@buildscriptdep//:bar"],
                "cfg(all())": ["@buildscriptdep//:baz"],
            },
            extra_bazel_data_deps = {
                # ...
            },
            extra_build_script_bazel_data_deps = {
                # ...
            },
        ),
    },
)

PARAMETERS

Name Description Default Value
extra_bazel_data_deps Targets to add to the data attribute of the generated target (eg: rust_library.data). None
extra_bazel_deps Targets to add to the deps attribute of the generated target (eg: rust_library.deps). None
extra_build_script_bazel_data_deps Targets to add to the data attribute of the generated cargo_build_script target. None
extra_build_script_bazel_deps Targets to add to the deps attribute of the generated cargo_build_script target. None
extra_build_script_env_vars Environment variables to add to the build_script_env attribute of the generated cargo_build_script target. None
extra_rustc_env_vars Environment variables to add to the rustc_env attribute for the generated target (eg: rust_library.rustc_env). None
features_to_remove A list of features to remove from a generated target. []

RETURNS

str: A json encoded struct of crate overrides

rust_bindgen_library

rust_bindgen_library(name, header, cc_lib, bindgen_flags, clang_flags, rustfmt, kwargs)

Generates a rust source file for header, and builds a rust_library.

Arguments are the same as rust_bindgen, and kwargs are passed directly to rust_library.

PARAMETERS

Name Description Default Value
name A unique name for this target. none
header The label of the .h file to generate bindings for. none
cc_lib The label of the cc_library that contains the .h file. This is used to find the transitive includes. none
bindgen_flags Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. None
clang_flags Flags to pass directly to the clang executable. None
rustfmt Enable or disable running rustfmt on the generated file. True
kwargs Arguments to forward to the underlying rust_library rule. none

rust_bindgen_repositories

rust_bindgen_repositories()

Declare dependencies needed for bindgen.

rust_proto_repositories

rust_proto_repositories(register_default_toolchain)

Declare dependencies needed for proto compilation.

PARAMETERS

Name Description Default Value
register_default_toolchain If True, the default rust_proto_toolchain (@rules_rust//proto:default-proto-toolchain) is registered. This toolchain requires a set of dependencies that were generated using cargo raze. These will also be loaded. True

rust_proto_transitive_repositories

rust_proto_transitive_repositories()

Load transitive dependencies of the @rules_rust//proto rules.

This macro should be called immediately after the rust_proto_repositories macro.

rust_repositories

rust_repositories(version, iso_date, rustfmt_version, edition, dev_components, sha256s,
                  include_rustc_srcs, urls)

Emits a default set of toolchains for Linux, MacOS, and Freebsd

Skip this macro and call the rust_repository_set macros directly if you need a compiler for other hosts or for additional target triples.

The sha256 attribute represents a dict associating tool subdirectories to sha256 hashes. As an example:

{
    "rust-1.46.0-x86_64-unknown-linux-gnu": "e3b98bc3440fe92817881933f9564389eccb396f5f431f33d48b979fa2fbdcf5",
    "rustfmt-1.4.12-x86_64-unknown-linux-gnu": "1894e76913303d66bf40885a601462844eec15fca9e76a6d13c390d7000d64b0",
    "rust-std-1.46.0-x86_64-unknown-linux-gnu": "ac04aef80423f612c0079829b504902de27a6997214eb58ab0765d02f7ec1dbc",
}

This would match for exec_triple = "x86_64-unknown-linux-gnu". If not specified, rules_rust pulls from a non-exhaustive list of known checksums..

See load_arbitrary_tool in @rules_rust//rust:repositories.bzl for more details.

PARAMETERS

Name Description Default Value
version The version of Rust. Either "nightly", "beta", or an exact version. Defaults to a modern version. "1.57.0"
iso_date The date of the nightly or beta release (ignored if the version is a specific version). None
rustfmt_version The version of rustfmt. Either "nightly", "beta", or an exact version. Defaults to version if not specified. None
edition The rust edition to be used by default (2015, 2018 (default), or 2021) None
dev_components Whether to download the rustc-dev components (defaults to False). Requires version to be "nightly". False
sha256s A dict associating tool subdirectories to sha256 hashes. Defaults to None. None
include_rustc_srcs Whether to download rustc's src code. This is required in order to use rust-analyzer support. See rust_toolchain_repository.include_rustc_srcs. for more details False
urls A list of mirror urls containing the tools from the Rust-lang static file server. These must contain the '{}' used to substitute the tool being fetched (using .format). Defaults to ['https://static.rust-lang.org/dist/{}.tar.gz'] ["https://static.rust-lang.org/dist/{}.tar.gz"]

rust_repository_set

rust_repository_set(name, version, exec_triple, include_rustc_srcs, extra_target_triples, iso_date,
                    rustfmt_version, edition, dev_components, sha256s, urls, auth)

Assembles a remote repository for the given toolchain params, produces a proxy repository to contain the toolchain declaration, and registers the toolchains.

N.B. A "proxy repository" is needed to allow for registering the toolchain (with constraints) without actually downloading the toolchain.

PARAMETERS

Name Description Default Value
name The name of the generated repository none
version The version of the tool among "nightly", "beta', or an exact version. none
exec_triple The Rust-style target that this compiler runs on none
include_rustc_srcs Whether to download rustc's src code. This is required in order to use rust-analyzer support. Defaults to False. False
extra_target_triples Additional rust-style targets that this set of toolchains should support. Defaults to []. []
iso_date The date of the tool. Defaults to None. None
rustfmt_version The version of rustfmt to be associated with the toolchain. Defaults to None. None
edition The rust edition to be used by default (2015, 2018 (if None), or 2021). None
dev_components Whether to download the rustc-dev components. Requires version to be "nightly". Defaults to False. False
sha256s A dict associating tool subdirectories to sha256 hashes. See rust_repositories for more details. None
urls A list of mirror urls containing the tools from the Rust-lang static file server. These must contain the '{}' used to substitute the tool being fetched (using .format). Defaults to ['https://static.rust-lang.org/dist/{}.tar.gz'] ["https://static.rust-lang.org/dist/{}.tar.gz"]
auth Auth object compatible with repository_ctx.download to use when downloading files. See https://docs.bazel.build/versions/main/skylark/lib/repository_ctx.html#download for more details. None

rust_test_suite

rust_test_suite(name, srcs, kwargs)

A rule for creating a test suite for a set of rust_test targets.

This rule can be used for setting up typical rust integration tests. Given the following directory structure:

[crate]/
    BUILD.bazel
    src/
        lib.rs
        main.rs
    tests/
        integrated_test_a.rs
        integrated_test_b.rs
        integrated_test_c.rs
        patterns/
            fibonacci_test.rs

The rule can be used to generate rust_test targets for each source file under tests and a test_suite which encapsulates all tests.

load("//rust:defs.bzl", "rust_binary", "rust_library", "rust_test_suite")

rust_library(
    name = "math_lib",
    srcs = ["src/lib.rs"],
)

rust_binary(
    name = "math_bin",
    srcs = ["src/main.rs"],
)

rust_test_suite(
    name = "integrated_tests_suite",
    srcs = glob(["tests/**"]),
    deps = [":math_lib"],
)

PARAMETERS

Name Description Default Value
name The name of the test_suite. none
srcs All test sources, typically glob(["tests/**/*.rs"]). none
kwargs Additional keyword arguments for the underyling rust_test targets. The tags argument is also passed to the generated test_suite target. none

rust_wasm_bindgen_repositories

rust_wasm_bindgen_repositories(register_default_toolchain)

Declare dependencies needed for rust_wasm_bindgen.

PARAMETERS

Name Description Default Value
register_default_toolchain If True, the default rust_wasm_bindgen_toolchain (@rules_rust//wasm_bindgen:default_wasm_bindgen_toolchain) is registered. This toolchain requires a set of dependencies that were generated using cargo raze. These will also be loaded. True

rust_analyzer_aspect

rust_analyzer_aspect(name)

Annotates rust rules with RustAnalyzerInfo later used to build a rust-project.json

ASPECT ATTRIBUTES

Name Type
deps String
proc_macro_deps String
crate String

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required

rust_clippy_aspect

rust_clippy_aspect(name)

Executes the clippy checker on specified targets.

This aspect applies to existing rust_library, rust_test, and rust_binary rules.

As an example, if the following is defined in examples/hello_lib/BUILD.bazel:

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

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

rust_test(
    name = "greeting_test",
    srcs = ["tests/greeting.rs"],
    deps = [":hello_lib"],
)

Then the targets can be analyzed with clippy using the following command:

$ bazel build --aspects=@rules_rust//rust:defs.bzl%rust_clippy_aspect               --output_groups=clippy_checks //hello_lib:all

ASPECT ATTRIBUTES

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required

rustfmt_aspect

rustfmt_aspect(name)

This aspect is used to gather information about a crate for use in rustfmt and perform rustfmt checks

Output Groups:

  • rustfmt_manifest: A manifest used by rustfmt binaries to provide crate specific settings.
  • rustfmt_checks: Executes rustfmt --check on the specified target.

The build setting @rules_rust//:rustfmt.toml is used to control the Rustfmt configuration settings used at runtime.

This aspect is executed on any target which provides the CrateInfo provider. However users may tag a target with norustfmt to have it skipped. Additionally, generated source files are also ignored by this aspect.

ASPECT ATTRIBUTES

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required