1<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2# Defs 3 4* [rust_binary](#rust_binary) 5* [rust_library](#rust_library) 6* [rust_library_group](#rust_library_group) 7* [rust_static_library](#rust_static_library) 8* [rust_shared_library](#rust_shared_library) 9* [rust_proc_macro](#rust_proc_macro) 10* [rust_test](#rust_test) 11* [rust_test_suite](#rust_test_suite) 12* [error_format](#error_format) 13* [extra_rustc_flag](#extra_rustc_flag) 14* [extra_rustc_flags](#extra_rustc_flags) 15* [capture_clippy_output](#capture_clippy_output) 16 17<a id="capture_clippy_output"></a> 18 19## capture_clippy_output 20 21<pre> 22capture_clippy_output(<a href="#capture_clippy_output-name">name</a>) 23</pre> 24 25Control whether to print clippy output or store it to a file, using the configured error_format. 26 27**ATTRIBUTES** 28 29 30| Name | Description | Type | Mandatory | Default | 31| :------------- | :------------- | :------------- | :------------- | :------------- | 32| <a id="capture_clippy_output-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 33 34 35<a id="error_format"></a> 36 37## error_format 38 39<pre> 40error_format(<a href="#error_format-name">name</a>) 41</pre> 42 43Change the [--error-format](https://doc.rust-lang.org/rustc/command-line-arguments.html#option-error-format) flag from the command line with `--@rules_rust//:error_format`. See rustc documentation for valid values. 44 45**ATTRIBUTES** 46 47 48| Name | Description | Type | Mandatory | Default | 49| :------------- | :------------- | :------------- | :------------- | :------------- | 50| <a id="error_format-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 51 52 53<a id="extra_rustc_flag"></a> 54 55## extra_rustc_flag 56 57<pre> 58extra_rustc_flag(<a href="#extra_rustc_flag-name">name</a>) 59</pre> 60 61Add additional rustc_flag from the command line with `--@rules_rust//:extra_rustc_flag`. Multiple uses are accumulated and appended after the extra_rustc_flags. 62 63**ATTRIBUTES** 64 65 66| Name | Description | Type | Mandatory | Default | 67| :------------- | :------------- | :------------- | :------------- | :------------- | 68| <a id="extra_rustc_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 69 70 71<a id="extra_rustc_flags"></a> 72 73## extra_rustc_flags 74 75<pre> 76extra_rustc_flags(<a href="#extra_rustc_flags-name">name</a>) 77</pre> 78 79Add 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 not applied to the exec configuration (proc-macros, cargo_build_script, etc); use `--@rules_rust//:extra_exec_rustc_flags` to apply flags to the exec configuration. 80 81**ATTRIBUTES** 82 83 84| Name | Description | Type | Mandatory | Default | 85| :------------- | :------------- | :------------- | :------------- | :------------- | 86| <a id="extra_rustc_flags-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 87 88 89<a id="rust_binary"></a> 90 91## rust_binary 92 93<pre> 94rust_binary(<a href="#rust_binary-name">name</a>, <a href="#rust_binary-deps">deps</a>, <a href="#rust_binary-srcs">srcs</a>, <a href="#rust_binary-data">data</a>, <a href="#rust_binary-aliases">aliases</a>, <a href="#rust_binary-alwayslink">alwayslink</a>, <a href="#rust_binary-compile_data">compile_data</a>, <a href="#rust_binary-crate_features">crate_features</a>, <a href="#rust_binary-crate_name">crate_name</a>, 95 <a href="#rust_binary-crate_root">crate_root</a>, <a href="#rust_binary-crate_type">crate_type</a>, <a href="#rust_binary-edition">edition</a>, <a href="#rust_binary-env">env</a>, <a href="#rust_binary-experimental_use_cc_common_link">experimental_use_cc_common_link</a>, <a href="#rust_binary-linker_script">linker_script</a>, 96 <a href="#rust_binary-malloc">malloc</a>, <a href="#rust_binary-out_binary">out_binary</a>, <a href="#rust_binary-platform">platform</a>, <a href="#rust_binary-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_binary-rustc_env">rustc_env</a>, <a href="#rust_binary-rustc_env_files">rustc_env_files</a>, <a href="#rust_binary-rustc_flags">rustc_flags</a>, 97 <a href="#rust_binary-stamp">stamp</a>, <a href="#rust_binary-version">version</a>) 98</pre> 99 100Builds a Rust binary crate. 101 102Example: 103 104Suppose you have the following directory structure for a Rust project with a 105library crate, `hello_lib`, and a binary crate, `hello_world` that uses the 106`hello_lib` library: 107 108```output 109[workspace]/ 110 WORKSPACE 111 hello_lib/ 112 BUILD 113 src/ 114 lib.rs 115 hello_world/ 116 BUILD 117 src/ 118 main.rs 119``` 120 121`hello_lib/src/lib.rs`: 122```rust 123pub struct Greeter { 124 greeting: String, 125} 126 127impl Greeter { 128 pub fn new(greeting: &str) -> Greeter { 129 Greeter { greeting: greeting.to_string(), } 130 } 131 132 pub fn greet(&self, thing: &str) { 133 println!("{} {}", &self.greeting, thing); 134 } 135} 136``` 137 138`hello_lib/BUILD`: 139```python 140package(default_visibility = ["//visibility:public"]) 141 142load("@rules_rust//rust:defs.bzl", "rust_library") 143 144rust_library( 145 name = "hello_lib", 146 srcs = ["src/lib.rs"], 147) 148``` 149 150`hello_world/src/main.rs`: 151```rust 152extern crate hello_lib; 153 154fn main() { 155 let hello = hello_lib::Greeter::new("Hello"); 156 hello.greet("world"); 157} 158``` 159 160`hello_world/BUILD`: 161```python 162load("@rules_rust//rust:defs.bzl", "rust_binary") 163 164rust_binary( 165 name = "hello_world", 166 srcs = ["src/main.rs"], 167 deps = ["//hello_lib"], 168) 169``` 170 171Build and run `hello_world`: 172``` 173$ bazel run //hello_world 174INFO: Found 1 target... 175Target //examples/rust/hello_world:hello_world up-to-date: 176bazel-bin/examples/rust/hello_world/hello_world 177INFO: Elapsed time: 1.308s, Critical Path: 1.22s 178 179INFO: Running command line: bazel-bin/examples/rust/hello_world/hello_world 180Hello world 181``` 182 183On Windows, a PDB file containing debugging information is available under 184the key `pdb_file` in `OutputGroupInfo`. Similarly on macOS, a dSYM folder 185is available under the key `dsym_folder` in `OutputGroupInfo`. 186 187**ATTRIBUTES** 188 189 190| Name | Description | Type | Mandatory | Default | 191| :------------- | :------------- | :------------- | :------------- | :------------- | 192| <a id="rust_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 193| <a id="rust_binary-deps"></a>deps | List of other libraries to be linked to this library target.<br><br>These can be either other `rust_library` targets or `cc_library` targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 194| <a id="rust_binary-srcs"></a>srcs | List of Rust `.rs` source files used to build the library.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 195| <a id="rust_binary-data"></a>data | List of files used by this rule at compile time and runtime.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 196| <a id="rust_binary-aliases"></a>aliases | Remap crates to a new name or moniker for linkage to this target<br><br>These are other `rust_library` targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` | 197| <a id="rust_binary-alwayslink"></a>alwayslink | If 1, any binary that depends (directly or indirectly) on this library will link in all the object files even if some contain no symbols referenced by the binary.<br><br>This attribute is used by the C++ Starlark API when passing CcInfo providers. | Boolean | optional | `False` | 198| <a id="rust_binary-compile_data"></a>compile_data | List of files used by this rule at compile time.<br><br>This attribute can be used to specify any data files that are embedded into the library, such as via the [`include_str!`](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 199| <a id="rust_binary-crate_features"></a>crate_features | List of features to enable for this crate.<br><br>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 | `[]` | 200| <a id="rust_binary-crate_name"></a>crate_name | Crate name to use for this target.<br><br>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 | `""` | 201| <a id="rust_binary-crate_root"></a>crate_root | The file that will be passed to `rustc` to be used for building this crate.<br><br>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. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 202| <a id="rust_binary-crate_type"></a>crate_type | Crate type that will be passed to `rustc` to be used for building this crate.<br><br>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"` | 203| <a id="rust_binary-edition"></a>edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | `""` | 204| <a id="rust_binary-env"></a>env | Specifies additional environment variables to set when the target is executed by bazel run. Values are subject to `$(rootpath)`, `$(execpath)`, location, and ["Make variable"](https://docs.bazel.build/versions/master/be/make-variables.html) substitution.<br><br>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. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` | 205| <a id="rust_binary-experimental_use_cc_common_link"></a>experimental_use_cc_common_link | Whether to use cc_common.link to link rust binaries. Possible values: [-1, 0, 1]. -1 means use the value of the toolchain.experimental_use_cc_common_link boolean build setting to determine. 0 means do not use cc_common.link (use rustc instead). 1 means use cc_common.link. | Integer | optional | `-1` | 206| <a id="rust_binary-linker_script"></a>linker_script | Link script to forward into linker via rustc options. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 207| <a id="rust_binary-malloc"></a>malloc | Override the default dependency on `malloc`.<br><br>By default, Rust binaries linked with cc_common.link are linked against `@bazel_tools//tools/cpp:malloc"`, which is an empty library and the resulting binary will use libc's `malloc`. This label must refer to a `cc_library` rule. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `"@bazel_tools//tools/cpp:malloc"` | 208| <a id="rust_binary-out_binary"></a>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` | 209| <a id="rust_binary-platform"></a>platform | Optional platform to transition the binary to. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 210| <a id="rust_binary-proc_macro_deps"></a>proc_macro_deps | List of `rust_proc_macro` targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 211| <a id="rust_binary-rustc_env"></a>rustc_env | Dictionary of additional `"key": "value"` environment variables to set for rustc.<br><br>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. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` | 212| <a id="rust_binary-rustc_env_files"></a>rustc_env_files | Files containing additional environment variables to set for rustc.<br><br>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 (`\\`).<br><br>The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.<br><br>Note that the variables here are subject to [workspace status](https://docs.bazel.build/versions/main/user-manual.html#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}`. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 213| <a id="rust_binary-rustc_flags"></a>rustc_flags | List of compiler flags passed to `rustc`.<br><br>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 | `[]` | 214| <a id="rust_binary-stamp"></a>stamp | Whether to encode build information into the `Rustc` action. Possible values:<br><br>- `stamp = 1`: Always stamp the build information into the `Rustc` action, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.<br><br>- `stamp = 0`: Always replace build information by constant values. This gives good build result caching.<br><br>- `stamp = -1`: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag.<br><br>Stamped targets are not rebuilt unless their dependencies change.<br><br>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`](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | `-1` | 215| <a id="rust_binary-version"></a>version | A version to inject in the cargo environment variable. | String | optional | `"0.0.0"` | 216 217 218<a id="rust_library"></a> 219 220## rust_library 221 222<pre> 223rust_library(<a href="#rust_library-name">name</a>, <a href="#rust_library-deps">deps</a>, <a href="#rust_library-srcs">srcs</a>, <a href="#rust_library-data">data</a>, <a href="#rust_library-aliases">aliases</a>, <a href="#rust_library-alwayslink">alwayslink</a>, <a href="#rust_library-compile_data">compile_data</a>, <a href="#rust_library-crate_features">crate_features</a>, <a href="#rust_library-crate_name">crate_name</a>, 224 <a href="#rust_library-crate_root">crate_root</a>, <a href="#rust_library-disable_pipelining">disable_pipelining</a>, <a href="#rust_library-edition">edition</a>, <a href="#rust_library-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_library-rustc_env">rustc_env</a>, <a href="#rust_library-rustc_env_files">rustc_env_files</a>, 225 <a href="#rust_library-rustc_flags">rustc_flags</a>, <a href="#rust_library-stamp">stamp</a>, <a href="#rust_library-version">version</a>) 226</pre> 227 228Builds a Rust library crate. 229 230Example: 231 232Suppose you have the following directory structure for a simple Rust library crate: 233 234```output 235[workspace]/ 236 WORKSPACE 237 hello_lib/ 238 BUILD 239 src/ 240 greeter.rs 241 lib.rs 242``` 243 244`hello_lib/src/greeter.rs`: 245```rust 246pub struct Greeter { 247 greeting: String, 248} 249 250impl Greeter { 251 pub fn new(greeting: &str) -> Greeter { 252 Greeter { greeting: greeting.to_string(), } 253 } 254 255 pub fn greet(&self, thing: &str) { 256 println!("{} {}", &self.greeting, thing); 257 } 258} 259``` 260 261`hello_lib/src/lib.rs`: 262 263```rust 264pub mod greeter; 265``` 266 267`hello_lib/BUILD`: 268```python 269package(default_visibility = ["//visibility:public"]) 270 271load("@rules_rust//rust:defs.bzl", "rust_library") 272 273rust_library( 274 name = "hello_lib", 275 srcs = [ 276 "src/greeter.rs", 277 "src/lib.rs", 278 ], 279) 280``` 281 282Build the library: 283```output 284$ bazel build //hello_lib 285INFO: Found 1 target... 286Target //examples/rust/hello_lib:hello_lib up-to-date: 287bazel-bin/examples/rust/hello_lib/libhello_lib.rlib 288INFO: Elapsed time: 1.245s, Critical Path: 1.01s 289``` 290 291**ATTRIBUTES** 292 293 294| Name | Description | Type | Mandatory | Default | 295| :------------- | :------------- | :------------- | :------------- | :------------- | 296| <a id="rust_library-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 297| <a id="rust_library-deps"></a>deps | List of other libraries to be linked to this library target.<br><br>These can be either other `rust_library` targets or `cc_library` targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 298| <a id="rust_library-srcs"></a>srcs | List of Rust `.rs` source files used to build the library.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 299| <a id="rust_library-data"></a>data | List of files used by this rule at compile time and runtime.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 300| <a id="rust_library-aliases"></a>aliases | Remap crates to a new name or moniker for linkage to this target<br><br>These are other `rust_library` targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` | 301| <a id="rust_library-alwayslink"></a>alwayslink | If 1, any binary that depends (directly or indirectly) on this library will link in all the object files even if some contain no symbols referenced by the binary.<br><br>This attribute is used by the C++ Starlark API when passing CcInfo providers. | Boolean | optional | `False` | 302| <a id="rust_library-compile_data"></a>compile_data | List of files used by this rule at compile time.<br><br>This attribute can be used to specify any data files that are embedded into the library, such as via the [`include_str!`](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 303| <a id="rust_library-crate_features"></a>crate_features | List of features to enable for this crate.<br><br>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 | `[]` | 304| <a id="rust_library-crate_name"></a>crate_name | Crate name to use for this target.<br><br>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 | `""` | 305| <a id="rust_library-crate_root"></a>crate_root | The file that will be passed to `rustc` to be used for building this crate.<br><br>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. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 306| <a id="rust_library-disable_pipelining"></a>disable_pipelining | Disables pipelining for this rule if it is globally enabled. This will cause this rule to not produce a `.rmeta` file and all the dependent crates will instead use the `.rlib` file. | Boolean | optional | `False` | 307| <a id="rust_library-edition"></a>edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | `""` | 308| <a id="rust_library-proc_macro_deps"></a>proc_macro_deps | List of `rust_proc_macro` targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 309| <a id="rust_library-rustc_env"></a>rustc_env | Dictionary of additional `"key": "value"` environment variables to set for rustc.<br><br>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. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` | 310| <a id="rust_library-rustc_env_files"></a>rustc_env_files | Files containing additional environment variables to set for rustc.<br><br>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 (`\\`).<br><br>The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.<br><br>Note that the variables here are subject to [workspace status](https://docs.bazel.build/versions/main/user-manual.html#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}`. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 311| <a id="rust_library-rustc_flags"></a>rustc_flags | List of compiler flags passed to `rustc`.<br><br>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 | `[]` | 312| <a id="rust_library-stamp"></a>stamp | Whether to encode build information into the `Rustc` action. Possible values:<br><br>- `stamp = 1`: Always stamp the build information into the `Rustc` action, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.<br><br>- `stamp = 0`: Always replace build information by constant values. This gives good build result caching.<br><br>- `stamp = -1`: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag.<br><br>Stamped targets are not rebuilt unless their dependencies change.<br><br>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`](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | `0` | 313| <a id="rust_library-version"></a>version | A version to inject in the cargo environment variable. | String | optional | `"0.0.0"` | 314 315 316<a id="rust_library_group"></a> 317 318## rust_library_group 319 320<pre> 321rust_library_group(<a href="#rust_library_group-name">name</a>, <a href="#rust_library_group-deps">deps</a>) 322</pre> 323 324Functions as an alias for a set of dependencies. 325 326Specifically, the following are equivalent: 327 328```starlark 329rust_library_group( 330 name = "crate_group", 331 deps = [ 332 ":crate1", 333 ":crate2", 334 ], 335) 336 337rust_library( 338 name = "foobar", 339 deps = [":crate_group"], 340 ... 341) 342``` 343 344and 345 346```starlark 347rust_library( 348 name = "foobar", 349 deps = [ 350 ":crate1", 351 ":crate2", 352 ], 353 ... 354) 355``` 356 357**ATTRIBUTES** 358 359 360| Name | Description | Type | Mandatory | Default | 361| :------------- | :------------- | :------------- | :------------- | :------------- | 362| <a id="rust_library_group-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 363| <a id="rust_library_group-deps"></a>deps | Other dependencies to forward through this crate group. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 364 365 366<a id="rust_proc_macro"></a> 367 368## rust_proc_macro 369 370<pre> 371rust_proc_macro(<a href="#rust_proc_macro-name">name</a>, <a href="#rust_proc_macro-deps">deps</a>, <a href="#rust_proc_macro-srcs">srcs</a>, <a href="#rust_proc_macro-data">data</a>, <a href="#rust_proc_macro-aliases">aliases</a>, <a href="#rust_proc_macro-alwayslink">alwayslink</a>, <a href="#rust_proc_macro-compile_data">compile_data</a>, <a href="#rust_proc_macro-crate_features">crate_features</a>, 372 <a href="#rust_proc_macro-crate_name">crate_name</a>, <a href="#rust_proc_macro-crate_root">crate_root</a>, <a href="#rust_proc_macro-edition">edition</a>, <a href="#rust_proc_macro-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_proc_macro-rustc_env">rustc_env</a>, <a href="#rust_proc_macro-rustc_env_files">rustc_env_files</a>, 373 <a href="#rust_proc_macro-rustc_flags">rustc_flags</a>, <a href="#rust_proc_macro-stamp">stamp</a>, <a href="#rust_proc_macro-version">version</a>) 374</pre> 375 376Builds a Rust proc-macro crate. 377 378**ATTRIBUTES** 379 380 381| Name | Description | Type | Mandatory | Default | 382| :------------- | :------------- | :------------- | :------------- | :------------- | 383| <a id="rust_proc_macro-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 384| <a id="rust_proc_macro-deps"></a>deps | List of other libraries to be linked to this library target.<br><br>These can be either other `rust_library` targets or `cc_library` targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 385| <a id="rust_proc_macro-srcs"></a>srcs | List of Rust `.rs` source files used to build the library.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 386| <a id="rust_proc_macro-data"></a>data | List of files used by this rule at compile time and runtime.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 387| <a id="rust_proc_macro-aliases"></a>aliases | Remap crates to a new name or moniker for linkage to this target<br><br>These are other `rust_library` targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` | 388| <a id="rust_proc_macro-alwayslink"></a>alwayslink | If 1, any binary that depends (directly or indirectly) on this library will link in all the object files even if some contain no symbols referenced by the binary.<br><br>This attribute is used by the C++ Starlark API when passing CcInfo providers. | Boolean | optional | `False` | 389| <a id="rust_proc_macro-compile_data"></a>compile_data | List of files used by this rule at compile time.<br><br>This attribute can be used to specify any data files that are embedded into the library, such as via the [`include_str!`](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 390| <a id="rust_proc_macro-crate_features"></a>crate_features | List of features to enable for this crate.<br><br>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 | `[]` | 391| <a id="rust_proc_macro-crate_name"></a>crate_name | Crate name to use for this target.<br><br>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 | `""` | 392| <a id="rust_proc_macro-crate_root"></a>crate_root | The file that will be passed to `rustc` to be used for building this crate.<br><br>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. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 393| <a id="rust_proc_macro-edition"></a>edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | `""` | 394| <a id="rust_proc_macro-proc_macro_deps"></a>proc_macro_deps | List of `rust_proc_macro` targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 395| <a id="rust_proc_macro-rustc_env"></a>rustc_env | Dictionary of additional `"key": "value"` environment variables to set for rustc.<br><br>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. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` | 396| <a id="rust_proc_macro-rustc_env_files"></a>rustc_env_files | Files containing additional environment variables to set for rustc.<br><br>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 (`\\`).<br><br>The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.<br><br>Note that the variables here are subject to [workspace status](https://docs.bazel.build/versions/main/user-manual.html#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}`. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 397| <a id="rust_proc_macro-rustc_flags"></a>rustc_flags | List of compiler flags passed to `rustc`.<br><br>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 | `[]` | 398| <a id="rust_proc_macro-stamp"></a>stamp | Whether to encode build information into the `Rustc` action. Possible values:<br><br>- `stamp = 1`: Always stamp the build information into the `Rustc` action, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.<br><br>- `stamp = 0`: Always replace build information by constant values. This gives good build result caching.<br><br>- `stamp = -1`: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag.<br><br>Stamped targets are not rebuilt unless their dependencies change.<br><br>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`](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | `0` | 399| <a id="rust_proc_macro-version"></a>version | A version to inject in the cargo environment variable. | String | optional | `"0.0.0"` | 400 401 402<a id="rust_shared_library"></a> 403 404## rust_shared_library 405 406<pre> 407rust_shared_library(<a href="#rust_shared_library-name">name</a>, <a href="#rust_shared_library-deps">deps</a>, <a href="#rust_shared_library-srcs">srcs</a>, <a href="#rust_shared_library-data">data</a>, <a href="#rust_shared_library-aliases">aliases</a>, <a href="#rust_shared_library-alwayslink">alwayslink</a>, <a href="#rust_shared_library-compile_data">compile_data</a>, <a href="#rust_shared_library-crate_features">crate_features</a>, 408 <a href="#rust_shared_library-crate_name">crate_name</a>, <a href="#rust_shared_library-crate_root">crate_root</a>, <a href="#rust_shared_library-edition">edition</a>, <a href="#rust_shared_library-experimental_use_cc_common_link">experimental_use_cc_common_link</a>, <a href="#rust_shared_library-malloc">malloc</a>, 409 <a href="#rust_shared_library-platform">platform</a>, <a href="#rust_shared_library-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_shared_library-rustc_env">rustc_env</a>, <a href="#rust_shared_library-rustc_env_files">rustc_env_files</a>, <a href="#rust_shared_library-rustc_flags">rustc_flags</a>, <a href="#rust_shared_library-stamp">stamp</a>, 410 <a href="#rust_shared_library-version">version</a>) 411</pre> 412 413Builds a Rust shared library. 414 415This shared library will contain all transitively reachable crates and native objects. 416It is meant to be used when producing an artifact that is then consumed by some other build system 417(for example to produce a shared library that Python program links against). 418 419This rule provides CcInfo, so it can be used everywhere Bazel expects `rules_cc`. 420 421When building the whole binary in Bazel, use `rust_library` instead. 422 423**ATTRIBUTES** 424 425 426| Name | Description | Type | Mandatory | Default | 427| :------------- | :------------- | :------------- | :------------- | :------------- | 428| <a id="rust_shared_library-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 429| <a id="rust_shared_library-deps"></a>deps | List of other libraries to be linked to this library target.<br><br>These can be either other `rust_library` targets or `cc_library` targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 430| <a id="rust_shared_library-srcs"></a>srcs | List of Rust `.rs` source files used to build the library.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 431| <a id="rust_shared_library-data"></a>data | List of files used by this rule at compile time and runtime.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 432| <a id="rust_shared_library-aliases"></a>aliases | Remap crates to a new name or moniker for linkage to this target<br><br>These are other `rust_library` targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` | 433| <a id="rust_shared_library-alwayslink"></a>alwayslink | If 1, any binary that depends (directly or indirectly) on this library will link in all the object files even if some contain no symbols referenced by the binary.<br><br>This attribute is used by the C++ Starlark API when passing CcInfo providers. | Boolean | optional | `False` | 434| <a id="rust_shared_library-compile_data"></a>compile_data | List of files used by this rule at compile time.<br><br>This attribute can be used to specify any data files that are embedded into the library, such as via the [`include_str!`](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 435| <a id="rust_shared_library-crate_features"></a>crate_features | List of features to enable for this crate.<br><br>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 | `[]` | 436| <a id="rust_shared_library-crate_name"></a>crate_name | Crate name to use for this target.<br><br>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 | `""` | 437| <a id="rust_shared_library-crate_root"></a>crate_root | The file that will be passed to `rustc` to be used for building this crate.<br><br>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. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 438| <a id="rust_shared_library-edition"></a>edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | `""` | 439| <a id="rust_shared_library-experimental_use_cc_common_link"></a>experimental_use_cc_common_link | Whether to use cc_common.link to link rust binaries. Possible values: [-1, 0, 1]. -1 means use the value of the toolchain.experimental_use_cc_common_link boolean build setting to determine. 0 means do not use cc_common.link (use rustc instead). 1 means use cc_common.link. | Integer | optional | `-1` | 440| <a id="rust_shared_library-malloc"></a>malloc | Override the default dependency on `malloc`.<br><br>By default, Rust binaries linked with cc_common.link are linked against `@bazel_tools//tools/cpp:malloc"`, which is an empty library and the resulting binary will use libc's `malloc`. This label must refer to a `cc_library` rule. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `"@bazel_tools//tools/cpp:malloc"` | 441| <a id="rust_shared_library-platform"></a>platform | Optional platform to transition the shared library to. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 442| <a id="rust_shared_library-proc_macro_deps"></a>proc_macro_deps | List of `rust_proc_macro` targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 443| <a id="rust_shared_library-rustc_env"></a>rustc_env | Dictionary of additional `"key": "value"` environment variables to set for rustc.<br><br>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. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` | 444| <a id="rust_shared_library-rustc_env_files"></a>rustc_env_files | Files containing additional environment variables to set for rustc.<br><br>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 (`\\`).<br><br>The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.<br><br>Note that the variables here are subject to [workspace status](https://docs.bazel.build/versions/main/user-manual.html#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}`. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 445| <a id="rust_shared_library-rustc_flags"></a>rustc_flags | List of compiler flags passed to `rustc`.<br><br>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 | `[]` | 446| <a id="rust_shared_library-stamp"></a>stamp | Whether to encode build information into the `Rustc` action. Possible values:<br><br>- `stamp = 1`: Always stamp the build information into the `Rustc` action, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.<br><br>- `stamp = 0`: Always replace build information by constant values. This gives good build result caching.<br><br>- `stamp = -1`: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag.<br><br>Stamped targets are not rebuilt unless their dependencies change.<br><br>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`](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | `0` | 447| <a id="rust_shared_library-version"></a>version | A version to inject in the cargo environment variable. | String | optional | `"0.0.0"` | 448 449 450<a id="rust_static_library"></a> 451 452## rust_static_library 453 454<pre> 455rust_static_library(<a href="#rust_static_library-name">name</a>, <a href="#rust_static_library-deps">deps</a>, <a href="#rust_static_library-srcs">srcs</a>, <a href="#rust_static_library-data">data</a>, <a href="#rust_static_library-aliases">aliases</a>, <a href="#rust_static_library-alwayslink">alwayslink</a>, <a href="#rust_static_library-compile_data">compile_data</a>, <a href="#rust_static_library-crate_features">crate_features</a>, 456 <a href="#rust_static_library-crate_name">crate_name</a>, <a href="#rust_static_library-crate_root">crate_root</a>, <a href="#rust_static_library-edition">edition</a>, <a href="#rust_static_library-platform">platform</a>, <a href="#rust_static_library-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_static_library-rustc_env">rustc_env</a>, 457 <a href="#rust_static_library-rustc_env_files">rustc_env_files</a>, <a href="#rust_static_library-rustc_flags">rustc_flags</a>, <a href="#rust_static_library-stamp">stamp</a>, <a href="#rust_static_library-version">version</a>) 458</pre> 459 460Builds a Rust static library. 461 462This static library will contain all transitively reachable crates and native objects. 463It is meant to be used when producing an artifact that is then consumed by some other build system 464(for example to produce an archive that Python program links against). 465 466This rule provides CcInfo, so it can be used everywhere Bazel expects `rules_cc`. 467 468When building the whole binary in Bazel, use `rust_library` instead. 469 470**ATTRIBUTES** 471 472 473| Name | Description | Type | Mandatory | Default | 474| :------------- | :------------- | :------------- | :------------- | :------------- | 475| <a id="rust_static_library-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 476| <a id="rust_static_library-deps"></a>deps | List of other libraries to be linked to this library target.<br><br>These can be either other `rust_library` targets or `cc_library` targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 477| <a id="rust_static_library-srcs"></a>srcs | List of Rust `.rs` source files used to build the library.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 478| <a id="rust_static_library-data"></a>data | List of files used by this rule at compile time and runtime.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 479| <a id="rust_static_library-aliases"></a>aliases | Remap crates to a new name or moniker for linkage to this target<br><br>These are other `rust_library` targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` | 480| <a id="rust_static_library-alwayslink"></a>alwayslink | If 1, any binary that depends (directly or indirectly) on this library will link in all the object files even if some contain no symbols referenced by the binary.<br><br>This attribute is used by the C++ Starlark API when passing CcInfo providers. | Boolean | optional | `False` | 481| <a id="rust_static_library-compile_data"></a>compile_data | List of files used by this rule at compile time.<br><br>This attribute can be used to specify any data files that are embedded into the library, such as via the [`include_str!`](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 482| <a id="rust_static_library-crate_features"></a>crate_features | List of features to enable for this crate.<br><br>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 | `[]` | 483| <a id="rust_static_library-crate_name"></a>crate_name | Crate name to use for this target.<br><br>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 | `""` | 484| <a id="rust_static_library-crate_root"></a>crate_root | The file that will be passed to `rustc` to be used for building this crate.<br><br>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. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 485| <a id="rust_static_library-edition"></a>edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | `""` | 486| <a id="rust_static_library-platform"></a>platform | Optional platform to transition the static library to. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 487| <a id="rust_static_library-proc_macro_deps"></a>proc_macro_deps | List of `rust_proc_macro` targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 488| <a id="rust_static_library-rustc_env"></a>rustc_env | Dictionary of additional `"key": "value"` environment variables to set for rustc.<br><br>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. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` | 489| <a id="rust_static_library-rustc_env_files"></a>rustc_env_files | Files containing additional environment variables to set for rustc.<br><br>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 (`\\`).<br><br>The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.<br><br>Note that the variables here are subject to [workspace status](https://docs.bazel.build/versions/main/user-manual.html#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}`. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 490| <a id="rust_static_library-rustc_flags"></a>rustc_flags | List of compiler flags passed to `rustc`.<br><br>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 | `[]` | 491| <a id="rust_static_library-stamp"></a>stamp | Whether to encode build information into the `Rustc` action. Possible values:<br><br>- `stamp = 1`: Always stamp the build information into the `Rustc` action, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.<br><br>- `stamp = 0`: Always replace build information by constant values. This gives good build result caching.<br><br>- `stamp = -1`: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag.<br><br>Stamped targets are not rebuilt unless their dependencies change.<br><br>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`](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | `0` | 492| <a id="rust_static_library-version"></a>version | A version to inject in the cargo environment variable. | String | optional | `"0.0.0"` | 493 494 495<a id="rust_test"></a> 496 497## rust_test 498 499<pre> 500rust_test(<a href="#rust_test-name">name</a>, <a href="#rust_test-deps">deps</a>, <a href="#rust_test-srcs">srcs</a>, <a href="#rust_test-data">data</a>, <a href="#rust_test-aliases">aliases</a>, <a href="#rust_test-alwayslink">alwayslink</a>, <a href="#rust_test-compile_data">compile_data</a>, <a href="#rust_test-crate">crate</a>, <a href="#rust_test-crate_features">crate_features</a>, 501 <a href="#rust_test-crate_name">crate_name</a>, <a href="#rust_test-crate_root">crate_root</a>, <a href="#rust_test-edition">edition</a>, <a href="#rust_test-env">env</a>, <a href="#rust_test-experimental_use_cc_common_link">experimental_use_cc_common_link</a>, <a href="#rust_test-malloc">malloc</a>, <a href="#rust_test-platform">platform</a>, 502 <a href="#rust_test-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_test-rustc_env">rustc_env</a>, <a href="#rust_test-rustc_env_files">rustc_env_files</a>, <a href="#rust_test-rustc_flags">rustc_flags</a>, <a href="#rust_test-stamp">stamp</a>, <a href="#rust_test-use_libtest_harness">use_libtest_harness</a>, 503 <a href="#rust_test-version">version</a>) 504</pre> 505 506Builds a Rust test crate. 507 508Examples: 509 510Suppose you have the following directory structure for a Rust library crate with unit test code in the library sources: 511 512```output 513[workspace]/ 514 WORKSPACE 515 hello_lib/ 516 BUILD 517 src/ 518 lib.rs 519``` 520 521`hello_lib/src/lib.rs`: 522```rust 523pub struct Greeter { 524 greeting: String, 525} 526 527impl Greeter { 528 pub fn new(greeting: &str) -> Greeter { 529 Greeter { greeting: greeting.to_string(), } 530 } 531 532 pub fn greet(&self, thing: &str) -> String { 533 format!("{} {}", &self.greeting, thing) 534 } 535} 536 537#[cfg(test)] 538mod test { 539 use super::Greeter; 540 541 #[test] 542 fn test_greeting() { 543 let hello = Greeter::new("Hi"); 544 assert_eq!("Hi Rust", hello.greet("Rust")); 545 } 546} 547``` 548 549To build and run the tests, simply add a `rust_test` rule with no `srcs` 550and only depends on the `hello_lib` `rust_library` target via the 551`crate` attribute: 552 553`hello_lib/BUILD`: 554```python 555load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") 556 557rust_library( 558 name = "hello_lib", 559 srcs = ["src/lib.rs"], 560) 561 562rust_test( 563 name = "hello_lib_test", 564 crate = ":hello_lib", 565 # You may add other deps that are specific to the test configuration 566 deps = ["//some/dev/dep"], 567) 568``` 569 570Run the test with `bazel test //hello_lib:hello_lib_test`. The crate 571will be built using the same crate name as the underlying ":hello_lib" 572crate. 573 574### Example: `test` directory 575 576Integration tests that live in the [`tests` directory][int-tests], 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: 577 578[int-tests]: http://doc.rust-lang.org/book/testing.html#the-tests-directory 579 580```output 581[workspace]/ 582 WORKSPACE 583 hello_lib/ 584 BUILD 585 src/ 586 lib.rs 587 tests/ 588 greeting.rs 589``` 590 591`hello_lib/tests/greeting.rs`: 592```rust 593extern crate hello_lib; 594 595use hello_lib; 596 597#[test] 598fn test_greeting() { 599 let hello = greeter::Greeter::new("Hello"); 600 assert_eq!("Hello world", hello.greeting("world")); 601} 602``` 603 604To build the `greeting.rs` integration test, simply add a `rust_test` target 605with `greeting.rs` in `srcs` and a dependency on the `hello_lib` target: 606 607`hello_lib/BUILD`: 608```python 609load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") 610 611rust_library( 612 name = "hello_lib", 613 srcs = ["src/lib.rs"], 614) 615 616rust_test( 617 name = "greeting_test", 618 srcs = ["tests/greeting.rs"], 619 deps = [":hello_lib"], 620) 621``` 622 623Run the test with `bazel test //hello_lib:greeting_test`. 624 625**ATTRIBUTES** 626 627 628| Name | Description | Type | Mandatory | Default | 629| :------------- | :------------- | :------------- | :------------- | :------------- | 630| <a id="rust_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 631| <a id="rust_test-deps"></a>deps | List of other libraries to be linked to this library target.<br><br>These can be either other `rust_library` targets or `cc_library` targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 632| <a id="rust_test-srcs"></a>srcs | List of Rust `.rs` source files used to build the library.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 633| <a id="rust_test-data"></a>data | List of files used by this rule at compile time and runtime.<br><br>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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 634| <a id="rust_test-aliases"></a>aliases | Remap crates to a new name or moniker for linkage to this target<br><br>These are other `rust_library` targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` | 635| <a id="rust_test-alwayslink"></a>alwayslink | If 1, any binary that depends (directly or indirectly) on this library will link in all the object files even if some contain no symbols referenced by the binary.<br><br>This attribute is used by the C++ Starlark API when passing CcInfo providers. | Boolean | optional | `False` | 636| <a id="rust_test-compile_data"></a>compile_data | List of files used by this rule at compile time.<br><br>This attribute can be used to specify any data files that are embedded into the library, such as via the [`include_str!`](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 637| <a id="rust_test-crate"></a>crate | Target inline tests declared in the given crate<br><br>These tests are typically those that would be held out under `#[cfg(test)]` declarations. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 638| <a id="rust_test-crate_features"></a>crate_features | List of features to enable for this crate.<br><br>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 | `[]` | 639| <a id="rust_test-crate_name"></a>crate_name | Crate name to use for this target.<br><br>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 | `""` | 640| <a id="rust_test-crate_root"></a>crate_root | The file that will be passed to `rustc` to be used for building this crate.<br><br>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. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 641| <a id="rust_test-edition"></a>edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | `""` | 642| <a id="rust_test-env"></a>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"](https://docs.bazel.build/versions/master/be/make-variables.html) substitution. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` | 643| <a id="rust_test-experimental_use_cc_common_link"></a>experimental_use_cc_common_link | Whether to use cc_common.link to link rust binaries. Possible values: [-1, 0, 1]. -1 means use the value of the toolchain.experimental_use_cc_common_link boolean build setting to determine. 0 means do not use cc_common.link (use rustc instead). 1 means use cc_common.link. | Integer | optional | `-1` | 644| <a id="rust_test-malloc"></a>malloc | Override the default dependency on `malloc`.<br><br>By default, Rust binaries linked with cc_common.link are linked against `@bazel_tools//tools/cpp:malloc"`, which is an empty library and the resulting binary will use libc's `malloc`. This label must refer to a `cc_library` rule. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `"@bazel_tools//tools/cpp:malloc"` | 645| <a id="rust_test-platform"></a>platform | Optional platform to transition the test to. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 646| <a id="rust_test-proc_macro_deps"></a>proc_macro_deps | List of `rust_proc_macro` targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 647| <a id="rust_test-rustc_env"></a>rustc_env | Dictionary of additional `"key": "value"` environment variables to set for rustc.<br><br>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. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` | 648| <a id="rust_test-rustc_env_files"></a>rustc_env_files | Files containing additional environment variables to set for rustc.<br><br>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 (`\\`).<br><br>The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.<br><br>Note that the variables here are subject to [workspace status](https://docs.bazel.build/versions/main/user-manual.html#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}`. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 649| <a id="rust_test-rustc_flags"></a>rustc_flags | List of compiler flags passed to `rustc`.<br><br>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 | `[]` | 650| <a id="rust_test-stamp"></a>stamp | Whether to encode build information into the `Rustc` action. Possible values:<br><br>- `stamp = 1`: Always stamp the build information into the `Rustc` action, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.<br><br>- `stamp = 0`: Always replace build information by constant values. This gives good build result caching.<br><br>- `stamp = -1`: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag.<br><br>Stamped targets are not rebuilt unless their dependencies change.<br><br>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`](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | `0` | 651| <a id="rust_test-use_libtest_harness"></a>use_libtest_harness | Whether to use `libtest`. For targets using this flag, individual tests can be run by using the [--test_arg](https://docs.bazel.build/versions/4.0.0/command-line-reference.html#flag--test_arg) flag. E.g. `bazel test //src:rust_test --test_arg=foo::test::test_fn`. | Boolean | optional | `True` | 652| <a id="rust_test-version"></a>version | A version to inject in the cargo environment variable. | String | optional | `"0.0.0"` | 653 654 655<a id="rust_test_suite"></a> 656 657## rust_test_suite 658 659<pre> 660rust_test_suite(<a href="#rust_test_suite-name">name</a>, <a href="#rust_test_suite-srcs">srcs</a>, <a href="#rust_test_suite-shared_srcs">shared_srcs</a>, <a href="#rust_test_suite-kwargs">kwargs</a>) 661</pre> 662 663A rule for creating a test suite for a set of `rust_test` targets. 664 665This rule can be used for setting up typical rust [integration tests][it]. Given the following 666directory structure: 667 668```text 669[crate]/ 670 BUILD.bazel 671 src/ 672 lib.rs 673 main.rs 674 tests/ 675 integrated_test_a.rs 676 integrated_test_b.rs 677 integrated_test_c.rs 678 patterns/ 679 fibonacci_test.rs 680 helpers/ 681 mod.rs 682``` 683 684The rule can be used to generate [rust_test](#rust_test) targets for each source file under `tests` 685and a [test_suite][ts] which encapsulates all tests. 686 687```python 688load("//rust:defs.bzl", "rust_binary", "rust_library", "rust_test_suite") 689 690rust_library( 691 name = "math_lib", 692 srcs = ["src/lib.rs"], 693) 694 695rust_binary( 696 name = "math_bin", 697 srcs = ["src/main.rs"], 698) 699 700rust_test_suite( 701 name = "integrated_tests_suite", 702 srcs = glob(["tests/**"]), 703 shared_srcs=glob(["tests/helpers/**"]), 704 deps = [":math_lib"], 705) 706``` 707 708[it]: https://doc.rust-lang.org/rust-by-example/testing/integration_testing.html 709[ts]: https://docs.bazel.build/versions/master/be/general.html#test_suite 710 711 712**PARAMETERS** 713 714 715| Name | Description | Default Value | 716| :------------- | :------------- | :------------- | 717| <a id="rust_test_suite-name"></a>name | The name of the `test_suite`. | none | 718| <a id="rust_test_suite-srcs"></a>srcs | All test sources, typically `glob(["tests/**/*.rs"])`. | none | 719| <a id="rust_test_suite-shared_srcs"></a>shared_srcs | Optional argument for sources shared among tests, typically helper functions. | `[]` | 720| <a id="rust_test_suite-kwargs"></a>kwargs | Additional keyword arguments for the underyling [rust_test](#rust_test) targets. The `tags` argument is also passed to the generated `test_suite` target. | none | 721 722 723