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-aliases">aliases</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>, <a href="#rust_binary-crate_root">crate_root</a>, <a href="#rust_binary-crate_type">crate_type</a>, <a href="#rust_binary-data">data</a>, 95 <a href="#rust_binary-deps">deps</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>, <a href="#rust_binary-malloc">malloc</a>, <a href="#rust_binary-out_binary">out_binary</a>, 96 <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>, <a href="#rust_binary-srcs">srcs</a>, <a href="#rust_binary-stamp">stamp</a>, <a href="#rust_binary-version">version</a>) 97</pre> 98 99Builds a Rust binary crate. 100 101Example: 102 103Suppose you have the following directory structure for a Rust project with a 104library crate, `hello_lib`, and a binary crate, `hello_world` that uses the 105`hello_lib` library: 106 107```output 108[workspace]/ 109 WORKSPACE 110 hello_lib/ 111 BUILD 112 src/ 113 lib.rs 114 hello_world/ 115 BUILD 116 src/ 117 main.rs 118``` 119 120`hello_lib/src/lib.rs`: 121```rust 122pub struct Greeter { 123 greeting: String, 124} 125 126impl Greeter { 127 pub fn new(greeting: &str) -> Greeter { 128 Greeter { greeting: greeting.to_string(), } 129 } 130 131 pub fn greet(&self, thing: &str) { 132 println!("{} {}", &self.greeting, thing); 133 } 134} 135``` 136 137`hello_lib/BUILD`: 138```python 139package(default_visibility = ["//visibility:public"]) 140 141load("@rules_rust//rust:defs.bzl", "rust_library") 142 143rust_library( 144 name = "hello_lib", 145 srcs = ["src/lib.rs"], 146) 147``` 148 149`hello_world/src/main.rs`: 150```rust 151extern crate hello_lib; 152 153fn main() { 154 let hello = hello_lib::Greeter::new("Hello"); 155 hello.greet("world"); 156} 157``` 158 159`hello_world/BUILD`: 160```python 161load("@rules_rust//rust:defs.bzl", "rust_binary") 162 163rust_binary( 164 name = "hello_world", 165 srcs = ["src/main.rs"], 166 deps = ["//hello_lib"], 167) 168``` 169 170Build and run `hello_world`: 171``` 172$ bazel run //hello_world 173INFO: Found 1 target... 174Target //examples/rust/hello_world:hello_world up-to-date: 175bazel-bin/examples/rust/hello_world/hello_world 176INFO: Elapsed time: 1.308s, Critical Path: 1.22s 177 178INFO: Running command line: bazel-bin/examples/rust/hello_world/hello_world 179Hello world 180``` 181 182On Windows, a PDB file containing debugging information is available under 183the key `pdb_file` in `OutputGroupInfo`. Similarly on macOS, a dSYM folder 184is available under the key `dsym_folder` in `OutputGroupInfo`. 185 186**ATTRIBUTES** 187 188 189| Name | Description | Type | Mandatory | Default | 190| :------------- | :------------- | :------------- | :------------- | :------------- | 191| <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 | | 192| <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 <code>rust_library</code> targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{}</code> | 193| <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 [<code>include_str!</code>](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 194| <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 <code>#[cfg(feature = "foo")]</code> configuration option. The features listed here will be passed to <code>rustc</code> with <code>--cfg feature="${feature_name}"</code> flags. | List of strings | optional | <code>[]</code> | 195| <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 | <code>""</code> | 196| <a id="rust_binary-crate_root"></a>crate_root | The file that will be passed to <code>rustc</code> to be used for building this crate.<br><br>If <code>crate_root</code> is not set, then this rule will look for a <code>lib.rs</code> file (or <code>main.rs</code> for rust_binary) or the single file in <code>srcs</code> if <code>srcs</code> contains only one file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 197| <a id="rust_binary-crate_type"></a>crate_type | Crate type that will be passed to <code>rustc</code> 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 | <code>"bin"</code> | 198| <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 <code>compile_data</code> over <code>data</code>, to prevent the data also being included in the runfiles. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 199| <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 <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 200| <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 | <code>""</code> | 201| <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 <code>$(rootpath)</code>, <code>$(execpath)</code>, 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 | <code>{}</code> | 202| <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 | <code>-1</code> | 203| <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 | <code>None</code> | 204| <a id="rust_binary-malloc"></a>malloc | Override the default dependency on <code>malloc</code>.<br><br>By default, Rust binaries linked with cc_common.link are linked against <code>@bazel_tools//tools/cpp:malloc"</code>, which is an empty library and the resulting binary will use libc's <code>malloc</code>. This label must refer to a <code>cc_library</code> rule. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>@bazel_tools//tools/cpp:malloc</code> | 205| <a id="rust_binary-out_binary"></a>out_binary | Force a target, regardless of it's <code>crate_type</code>, 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 | <code>False</code> | 206| <a id="rust_binary-platform"></a>platform | Optional platform to transition the binary to. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 207| <a id="rust_binary-proc_macro_deps"></a>proc_macro_deps | List of <code>rust_proc_macro</code> targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 208| <a id="rust_binary-rustc_env"></a>rustc_env | Dictionary of additional <code>"key": "value"</code> 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 | <code>{}</code> | 209| <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 <code>NAME=value</code>, and newlines may be included in a value by ending a line with a trailing back-slash (<code>\\</code>).<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 <code>stamp</code> attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. <code>NAME={WORKSPACE_STATUS_VARIABLE}</code>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 210| <a id="rust_binary-rustc_flags"></a>rustc_flags | List of compiler flags passed to <code>rustc</code>.<br><br>These strings are subject to Make variable expansion for predefined source/output path variables like <code>$location</code>, <code>$execpath</code>, and <code>$rootpath</code>. This expansion is useful if you wish to pass a generated file of arguments to rustc: <code>@$(location //package:target)</code>. | List of strings | optional | <code>[]</code> | 211| <a id="rust_binary-srcs"></a>srcs | List of Rust <code>.rs</code> source files used to build the library.<br><br>If <code>srcs</code> contains more than one file, then there must be a file either named <code>lib.rs</code>. Otherwise, <code>crate_root</code> 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 | <code>[]</code> | 212| <a id="rust_binary-stamp"></a>stamp | Whether to encode build information into the <code>Rustc</code> action. Possible values:<br><br>- <code>stamp = 1</code>: Always stamp the build information into the <code>Rustc</code> 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>- <code>stamp = 0</code>: Always replace build information by constant values. This gives good build result caching.<br><br>- <code>stamp = -1</code>: 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 <code>rust_library</code> is stamped, and a <code>rust_binary</code> depends on that library, the stamped library won't be rebuilt when we change sources of the <code>rust_binary</code>. This is different from how [<code>cc_library.linkstamps</code>](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | <code>-1</code> | 213| <a id="rust_binary-version"></a>version | A version to inject in the cargo environment variable. | String | optional | <code>"0.0.0"</code> | 214 215 216<a id="rust_library"></a> 217 218## rust_library 219 220<pre> 221rust_library(<a href="#rust_library-name">name</a>, <a href="#rust_library-aliases">aliases</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>, <a href="#rust_library-crate_root">crate_root</a>, <a href="#rust_library-data">data</a>, <a href="#rust_library-deps">deps</a>, 222 <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>, <a href="#rust_library-rustc_flags">rustc_flags</a>, 223 <a href="#rust_library-srcs">srcs</a>, <a href="#rust_library-stamp">stamp</a>, <a href="#rust_library-version">version</a>) 224</pre> 225 226Builds a Rust library crate. 227 228Example: 229 230Suppose you have the following directory structure for a simple Rust library crate: 231 232```output 233[workspace]/ 234 WORKSPACE 235 hello_lib/ 236 BUILD 237 src/ 238 greeter.rs 239 lib.rs 240``` 241 242`hello_lib/src/greeter.rs`: 243```rust 244pub struct Greeter { 245 greeting: String, 246} 247 248impl Greeter { 249 pub fn new(greeting: &str) -> Greeter { 250 Greeter { greeting: greeting.to_string(), } 251 } 252 253 pub fn greet(&self, thing: &str) { 254 println!("{} {}", &self.greeting, thing); 255 } 256} 257``` 258 259`hello_lib/src/lib.rs`: 260 261```rust 262pub mod greeter; 263``` 264 265`hello_lib/BUILD`: 266```python 267package(default_visibility = ["//visibility:public"]) 268 269load("@rules_rust//rust:defs.bzl", "rust_library") 270 271rust_library( 272 name = "hello_lib", 273 srcs = [ 274 "src/greeter.rs", 275 "src/lib.rs", 276 ], 277) 278``` 279 280Build the library: 281```output 282$ bazel build //hello_lib 283INFO: Found 1 target... 284Target //examples/rust/hello_lib:hello_lib up-to-date: 285bazel-bin/examples/rust/hello_lib/libhello_lib.rlib 286INFO: Elapsed time: 1.245s, Critical Path: 1.01s 287``` 288 289 290**ATTRIBUTES** 291 292 293| Name | Description | Type | Mandatory | Default | 294| :------------- | :------------- | :------------- | :------------- | :------------- | 295| <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 | | 296| <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 <code>rust_library</code> targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{}</code> | 297| <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 [<code>include_str!</code>](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 298| <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 <code>#[cfg(feature = "foo")]</code> configuration option. The features listed here will be passed to <code>rustc</code> with <code>--cfg feature="${feature_name}"</code> flags. | List of strings | optional | <code>[]</code> | 299| <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 | <code>""</code> | 300| <a id="rust_library-crate_root"></a>crate_root | The file that will be passed to <code>rustc</code> to be used for building this crate.<br><br>If <code>crate_root</code> is not set, then this rule will look for a <code>lib.rs</code> file (or <code>main.rs</code> for rust_binary) or the single file in <code>srcs</code> if <code>srcs</code> contains only one file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 301| <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 <code>compile_data</code> over <code>data</code>, to prevent the data also being included in the runfiles. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 302| <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 <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 303| <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 <code>.rmeta</code> file and all the dependent crates will instead use the <code>.rlib</code> file. | Boolean | optional | <code>False</code> | 304| <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 | <code>""</code> | 305| <a id="rust_library-proc_macro_deps"></a>proc_macro_deps | List of <code>rust_proc_macro</code> targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 306| <a id="rust_library-rustc_env"></a>rustc_env | Dictionary of additional <code>"key": "value"</code> 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 | <code>{}</code> | 307| <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 <code>NAME=value</code>, and newlines may be included in a value by ending a line with a trailing back-slash (<code>\\</code>).<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 <code>stamp</code> attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. <code>NAME={WORKSPACE_STATUS_VARIABLE}</code>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 308| <a id="rust_library-rustc_flags"></a>rustc_flags | List of compiler flags passed to <code>rustc</code>.<br><br>These strings are subject to Make variable expansion for predefined source/output path variables like <code>$location</code>, <code>$execpath</code>, and <code>$rootpath</code>. This expansion is useful if you wish to pass a generated file of arguments to rustc: <code>@$(location //package:target)</code>. | List of strings | optional | <code>[]</code> | 309| <a id="rust_library-srcs"></a>srcs | List of Rust <code>.rs</code> source files used to build the library.<br><br>If <code>srcs</code> contains more than one file, then there must be a file either named <code>lib.rs</code>. Otherwise, <code>crate_root</code> 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 | <code>[]</code> | 310| <a id="rust_library-stamp"></a>stamp | Whether to encode build information into the <code>Rustc</code> action. Possible values:<br><br>- <code>stamp = 1</code>: Always stamp the build information into the <code>Rustc</code> 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>- <code>stamp = 0</code>: Always replace build information by constant values. This gives good build result caching.<br><br>- <code>stamp = -1</code>: 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 <code>rust_library</code> is stamped, and a <code>rust_binary</code> depends on that library, the stamped library won't be rebuilt when we change sources of the <code>rust_binary</code>. This is different from how [<code>cc_library.linkstamps</code>](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | <code>0</code> | 311| <a id="rust_library-version"></a>version | A version to inject in the cargo environment variable. | String | optional | <code>"0.0.0"</code> | 312 313 314<a id="rust_library_group"></a> 315 316## rust_library_group 317 318<pre> 319rust_library_group(<a href="#rust_library_group-name">name</a>, <a href="#rust_library_group-deps">deps</a>) 320</pre> 321 322Functions as an alias for a set of dependencies. 323 324Specifically, the following are equivalent: 325 326```starlark 327rust_library_group( 328 name = "crate_group", 329 deps = [ 330 ":crate1", 331 ":crate2", 332 ], 333) 334 335rust_library( 336 name = "foobar", 337 deps = [":crate_group"], 338 ... 339) 340``` 341 342and 343 344```starlark 345rust_library( 346 name = "foobar", 347 deps = [ 348 ":crate1", 349 ":crate2", 350 ], 351 ... 352) 353``` 354 355 356**ATTRIBUTES** 357 358 359| Name | Description | Type | Mandatory | Default | 360| :------------- | :------------- | :------------- | :------------- | :------------- | 361| <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 | | 362| <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 | <code>[]</code> | 363 364 365<a id="rust_proc_macro"></a> 366 367## rust_proc_macro 368 369<pre> 370rust_proc_macro(<a href="#rust_proc_macro-name">name</a>, <a href="#rust_proc_macro-aliases">aliases</a>, <a href="#rust_proc_macro-compile_data">compile_data</a>, <a href="#rust_proc_macro-crate_features">crate_features</a>, <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-data">data</a>, <a href="#rust_proc_macro-deps">deps</a>, 371 <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>, <a href="#rust_proc_macro-rustc_flags">rustc_flags</a>, <a href="#rust_proc_macro-srcs">srcs</a>, <a href="#rust_proc_macro-stamp">stamp</a>, 372 <a href="#rust_proc_macro-version">version</a>) 373</pre> 374 375Builds a Rust proc-macro crate. 376 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-aliases"></a>aliases | Remap crates to a new name or moniker for linkage to this target<br><br>These are other <code>rust_library</code> targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{}</code> | 385| <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 [<code>include_str!</code>](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 386| <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 <code>#[cfg(feature = "foo")]</code> configuration option. The features listed here will be passed to <code>rustc</code> with <code>--cfg feature="${feature_name}"</code> flags. | List of strings | optional | <code>[]</code> | 387| <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 | <code>""</code> | 388| <a id="rust_proc_macro-crate_root"></a>crate_root | The file that will be passed to <code>rustc</code> to be used for building this crate.<br><br>If <code>crate_root</code> is not set, then this rule will look for a <code>lib.rs</code> file (or <code>main.rs</code> for rust_binary) or the single file in <code>srcs</code> if <code>srcs</code> contains only one file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 389| <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 <code>compile_data</code> over <code>data</code>, to prevent the data also being included in the runfiles. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 390| <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 <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 391| <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 | <code>""</code> | 392| <a id="rust_proc_macro-proc_macro_deps"></a>proc_macro_deps | List of <code>rust_proc_macro</code> targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 393| <a id="rust_proc_macro-rustc_env"></a>rustc_env | Dictionary of additional <code>"key": "value"</code> 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 | <code>{}</code> | 394| <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 <code>NAME=value</code>, and newlines may be included in a value by ending a line with a trailing back-slash (<code>\\</code>).<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 <code>stamp</code> attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. <code>NAME={WORKSPACE_STATUS_VARIABLE}</code>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 395| <a id="rust_proc_macro-rustc_flags"></a>rustc_flags | List of compiler flags passed to <code>rustc</code>.<br><br>These strings are subject to Make variable expansion for predefined source/output path variables like <code>$location</code>, <code>$execpath</code>, and <code>$rootpath</code>. This expansion is useful if you wish to pass a generated file of arguments to rustc: <code>@$(location //package:target)</code>. | List of strings | optional | <code>[]</code> | 396| <a id="rust_proc_macro-srcs"></a>srcs | List of Rust <code>.rs</code> source files used to build the library.<br><br>If <code>srcs</code> contains more than one file, then there must be a file either named <code>lib.rs</code>. Otherwise, <code>crate_root</code> 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 | <code>[]</code> | 397| <a id="rust_proc_macro-stamp"></a>stamp | Whether to encode build information into the <code>Rustc</code> action. Possible values:<br><br>- <code>stamp = 1</code>: Always stamp the build information into the <code>Rustc</code> 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>- <code>stamp = 0</code>: Always replace build information by constant values. This gives good build result caching.<br><br>- <code>stamp = -1</code>: 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 <code>rust_library</code> is stamped, and a <code>rust_binary</code> depends on that library, the stamped library won't be rebuilt when we change sources of the <code>rust_binary</code>. This is different from how [<code>cc_library.linkstamps</code>](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | <code>0</code> | 398| <a id="rust_proc_macro-version"></a>version | A version to inject in the cargo environment variable. | String | optional | <code>"0.0.0"</code> | 399 400 401<a id="rust_shared_library"></a> 402 403## rust_shared_library 404 405<pre> 406rust_shared_library(<a href="#rust_shared_library-name">name</a>, <a href="#rust_shared_library-aliases">aliases</a>, <a href="#rust_shared_library-compile_data">compile_data</a>, <a href="#rust_shared_library-crate_features">crate_features</a>, <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-data">data</a>, <a href="#rust_shared_library-deps">deps</a>, 407 <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>, <a href="#rust_shared_library-platform">platform</a>, <a href="#rust_shared_library-proc_macro_deps">proc_macro_deps</a>, 408 <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-srcs">srcs</a>, <a href="#rust_shared_library-stamp">stamp</a>, <a href="#rust_shared_library-version">version</a>) 409</pre> 410 411Builds a Rust shared library. 412 413This shared library will contain all transitively reachable crates and native objects. 414It is meant to be used when producing an artifact that is then consumed by some other build system 415(for example to produce a shared library that Python program links against). 416 417This rule provides CcInfo, so it can be used everywhere Bazel expects `rules_cc`. 418 419When building the whole binary in Bazel, use `rust_library` instead. 420 421 422**ATTRIBUTES** 423 424 425| Name | Description | Type | Mandatory | Default | 426| :------------- | :------------- | :------------- | :------------- | :------------- | 427| <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 | | 428| <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 <code>rust_library</code> targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{}</code> | 429| <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 [<code>include_str!</code>](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 430| <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 <code>#[cfg(feature = "foo")]</code> configuration option. The features listed here will be passed to <code>rustc</code> with <code>--cfg feature="${feature_name}"</code> flags. | List of strings | optional | <code>[]</code> | 431| <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 | <code>""</code> | 432| <a id="rust_shared_library-crate_root"></a>crate_root | The file that will be passed to <code>rustc</code> to be used for building this crate.<br><br>If <code>crate_root</code> is not set, then this rule will look for a <code>lib.rs</code> file (or <code>main.rs</code> for rust_binary) or the single file in <code>srcs</code> if <code>srcs</code> contains only one file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 433| <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 <code>compile_data</code> over <code>data</code>, to prevent the data also being included in the runfiles. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 434| <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 <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 435| <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 | <code>""</code> | 436| <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 | <code>-1</code> | 437| <a id="rust_shared_library-malloc"></a>malloc | Override the default dependency on <code>malloc</code>.<br><br>By default, Rust binaries linked with cc_common.link are linked against <code>@bazel_tools//tools/cpp:malloc"</code>, which is an empty library and the resulting binary will use libc's <code>malloc</code>. This label must refer to a <code>cc_library</code> rule. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>@bazel_tools//tools/cpp:malloc</code> | 438| <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 | <code>None</code> | 439| <a id="rust_shared_library-proc_macro_deps"></a>proc_macro_deps | List of <code>rust_proc_macro</code> targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 440| <a id="rust_shared_library-rustc_env"></a>rustc_env | Dictionary of additional <code>"key": "value"</code> 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 | <code>{}</code> | 441| <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 <code>NAME=value</code>, and newlines may be included in a value by ending a line with a trailing back-slash (<code>\\</code>).<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 <code>stamp</code> attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. <code>NAME={WORKSPACE_STATUS_VARIABLE}</code>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 442| <a id="rust_shared_library-rustc_flags"></a>rustc_flags | List of compiler flags passed to <code>rustc</code>.<br><br>These strings are subject to Make variable expansion for predefined source/output path variables like <code>$location</code>, <code>$execpath</code>, and <code>$rootpath</code>. This expansion is useful if you wish to pass a generated file of arguments to rustc: <code>@$(location //package:target)</code>. | List of strings | optional | <code>[]</code> | 443| <a id="rust_shared_library-srcs"></a>srcs | List of Rust <code>.rs</code> source files used to build the library.<br><br>If <code>srcs</code> contains more than one file, then there must be a file either named <code>lib.rs</code>. Otherwise, <code>crate_root</code> 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 | <code>[]</code> | 444| <a id="rust_shared_library-stamp"></a>stamp | Whether to encode build information into the <code>Rustc</code> action. Possible values:<br><br>- <code>stamp = 1</code>: Always stamp the build information into the <code>Rustc</code> 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>- <code>stamp = 0</code>: Always replace build information by constant values. This gives good build result caching.<br><br>- <code>stamp = -1</code>: 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 <code>rust_library</code> is stamped, and a <code>rust_binary</code> depends on that library, the stamped library won't be rebuilt when we change sources of the <code>rust_binary</code>. This is different from how [<code>cc_library.linkstamps</code>](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | <code>0</code> | 445| <a id="rust_shared_library-version"></a>version | A version to inject in the cargo environment variable. | String | optional | <code>"0.0.0"</code> | 446 447 448<a id="rust_static_library"></a> 449 450## rust_static_library 451 452<pre> 453rust_static_library(<a href="#rust_static_library-name">name</a>, <a href="#rust_static_library-aliases">aliases</a>, <a href="#rust_static_library-compile_data">compile_data</a>, <a href="#rust_static_library-crate_features">crate_features</a>, <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-data">data</a>, <a href="#rust_static_library-deps">deps</a>, 454 <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>, <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-srcs">srcs</a>, 455 <a href="#rust_static_library-stamp">stamp</a>, <a href="#rust_static_library-version">version</a>) 456</pre> 457 458Builds a Rust static library. 459 460This static library will contain all transitively reachable crates and native objects. 461It is meant to be used when producing an artifact that is then consumed by some other build system 462(for example to produce an archive that Python program links against). 463 464This rule provides CcInfo, so it can be used everywhere Bazel expects `rules_cc`. 465 466When building the whole binary in Bazel, use `rust_library` instead. 467 468 469**ATTRIBUTES** 470 471 472| Name | Description | Type | Mandatory | Default | 473| :------------- | :------------- | :------------- | :------------- | :------------- | 474| <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 | | 475| <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 <code>rust_library</code> targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{}</code> | 476| <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 [<code>include_str!</code>](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 477| <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 <code>#[cfg(feature = "foo")]</code> configuration option. The features listed here will be passed to <code>rustc</code> with <code>--cfg feature="${feature_name}"</code> flags. | List of strings | optional | <code>[]</code> | 478| <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 | <code>""</code> | 479| <a id="rust_static_library-crate_root"></a>crate_root | The file that will be passed to <code>rustc</code> to be used for building this crate.<br><br>If <code>crate_root</code> is not set, then this rule will look for a <code>lib.rs</code> file (or <code>main.rs</code> for rust_binary) or the single file in <code>srcs</code> if <code>srcs</code> contains only one file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 480| <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 <code>compile_data</code> over <code>data</code>, to prevent the data also being included in the runfiles. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 481| <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 <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 482| <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 | <code>""</code> | 483| <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 | <code>None</code> | 484| <a id="rust_static_library-proc_macro_deps"></a>proc_macro_deps | List of <code>rust_proc_macro</code> targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 485| <a id="rust_static_library-rustc_env"></a>rustc_env | Dictionary of additional <code>"key": "value"</code> 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 | <code>{}</code> | 486| <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 <code>NAME=value</code>, and newlines may be included in a value by ending a line with a trailing back-slash (<code>\\</code>).<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 <code>stamp</code> attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. <code>NAME={WORKSPACE_STATUS_VARIABLE}</code>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 487| <a id="rust_static_library-rustc_flags"></a>rustc_flags | List of compiler flags passed to <code>rustc</code>.<br><br>These strings are subject to Make variable expansion for predefined source/output path variables like <code>$location</code>, <code>$execpath</code>, and <code>$rootpath</code>. This expansion is useful if you wish to pass a generated file of arguments to rustc: <code>@$(location //package:target)</code>. | List of strings | optional | <code>[]</code> | 488| <a id="rust_static_library-srcs"></a>srcs | List of Rust <code>.rs</code> source files used to build the library.<br><br>If <code>srcs</code> contains more than one file, then there must be a file either named <code>lib.rs</code>. Otherwise, <code>crate_root</code> 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 | <code>[]</code> | 489| <a id="rust_static_library-stamp"></a>stamp | Whether to encode build information into the <code>Rustc</code> action. Possible values:<br><br>- <code>stamp = 1</code>: Always stamp the build information into the <code>Rustc</code> 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>- <code>stamp = 0</code>: Always replace build information by constant values. This gives good build result caching.<br><br>- <code>stamp = -1</code>: 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 <code>rust_library</code> is stamped, and a <code>rust_binary</code> depends on that library, the stamped library won't be rebuilt when we change sources of the <code>rust_binary</code>. This is different from how [<code>cc_library.linkstamps</code>](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | <code>0</code> | 490| <a id="rust_static_library-version"></a>version | A version to inject in the cargo environment variable. | String | optional | <code>"0.0.0"</code> | 491 492 493<a id="rust_test"></a> 494 495## rust_test 496 497<pre> 498rust_test(<a href="#rust_test-name">name</a>, <a href="#rust_test-aliases">aliases</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>, <a href="#rust_test-crate_name">crate_name</a>, <a href="#rust_test-crate_root">crate_root</a>, <a href="#rust_test-data">data</a>, <a href="#rust_test-deps">deps</a>, 499 <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>, <a href="#rust_test-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_test-rustc_env">rustc_env</a>, 500 <a href="#rust_test-rustc_env_files">rustc_env_files</a>, <a href="#rust_test-rustc_flags">rustc_flags</a>, <a href="#rust_test-srcs">srcs</a>, <a href="#rust_test-stamp">stamp</a>, <a href="#rust_test-use_libtest_harness">use_libtest_harness</a>, <a href="#rust_test-version">version</a>) 501</pre> 502 503Builds a Rust test crate. 504 505Examples: 506 507Suppose you have the following directory structure for a Rust library crate with unit test code in the library sources: 508 509```output 510[workspace]/ 511 WORKSPACE 512 hello_lib/ 513 BUILD 514 src/ 515 lib.rs 516``` 517 518`hello_lib/src/lib.rs`: 519```rust 520pub struct Greeter { 521 greeting: String, 522} 523 524impl Greeter { 525 pub fn new(greeting: &str) -> Greeter { 526 Greeter { greeting: greeting.to_string(), } 527 } 528 529 pub fn greet(&self, thing: &str) -> String { 530 format!("{} {}", &self.greeting, thing) 531 } 532} 533 534#[cfg(test)] 535mod test { 536 use super::Greeter; 537 538 #[test] 539 fn test_greeting() { 540 let hello = Greeter::new("Hi"); 541 assert_eq!("Hi Rust", hello.greet("Rust")); 542 } 543} 544``` 545 546To build and run the tests, simply add a `rust_test` rule with no `srcs` 547and only depends on the `hello_lib` `rust_library` target via the 548`crate` attribute: 549 550`hello_lib/BUILD`: 551```python 552load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") 553 554rust_library( 555 name = "hello_lib", 556 srcs = ["src/lib.rs"], 557) 558 559rust_test( 560 name = "hello_lib_test", 561 crate = ":hello_lib", 562 # You may add other deps that are specific to the test configuration 563 deps = ["//some/dev/dep"], 564) 565``` 566 567Run the test with `bazel test //hello_lib:hello_lib_test`. The crate 568will be built using the same crate name as the underlying ":hello_lib" 569crate. 570 571### Example: `test` directory 572 573Integration 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: 574 575[int-tests]: http://doc.rust-lang.org/book/testing.html#the-tests-directory 576 577```output 578[workspace]/ 579 WORKSPACE 580 hello_lib/ 581 BUILD 582 src/ 583 lib.rs 584 tests/ 585 greeting.rs 586``` 587 588`hello_lib/tests/greeting.rs`: 589```rust 590extern crate hello_lib; 591 592use hello_lib; 593 594#[test] 595fn test_greeting() { 596 let hello = greeter::Greeter::new("Hello"); 597 assert_eq!("Hello world", hello.greeting("world")); 598} 599``` 600 601To build the `greeting.rs` integration test, simply add a `rust_test` target 602with `greeting.rs` in `srcs` and a dependency on the `hello_lib` target: 603 604`hello_lib/BUILD`: 605```python 606load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") 607 608rust_library( 609 name = "hello_lib", 610 srcs = ["src/lib.rs"], 611) 612 613rust_test( 614 name = "greeting_test", 615 srcs = ["tests/greeting.rs"], 616 deps = [":hello_lib"], 617) 618``` 619 620Run the test with `bazel test //hello_lib:greeting_test`. 621 622**ATTRIBUTES** 623 624 625| Name | Description | Type | Mandatory | Default | 626| :------------- | :------------- | :------------- | :------------- | :------------- | 627| <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 | | 628| <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 <code>rust_library</code> targets and will be presented as the new name given. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{}</code> | 629| <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 [<code>include_str!</code>](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 630| <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 <code>#[cfg(test)]</code> declarations. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 631| <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 <code>#[cfg(feature = "foo")]</code> configuration option. The features listed here will be passed to <code>rustc</code> with <code>--cfg feature="${feature_name}"</code> flags. | List of strings | optional | <code>[]</code> | 632| <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 | <code>""</code> | 633| <a id="rust_test-crate_root"></a>crate_root | The file that will be passed to <code>rustc</code> to be used for building this crate.<br><br>If <code>crate_root</code> is not set, then this rule will look for a <code>lib.rs</code> file (or <code>main.rs</code> for rust_binary) or the single file in <code>srcs</code> if <code>srcs</code> contains only one file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 634| <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 <code>compile_data</code> over <code>data</code>, to prevent the data also being included in the runfiles. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 635| <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 <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 636| <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 | <code>""</code> | 637| <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 <code>$(rootpath)</code>, <code>$(execpath)</code>, 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 | <code>{}</code> | 638| <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 | <code>-1</code> | 639| <a id="rust_test-malloc"></a>malloc | Override the default dependency on <code>malloc</code>.<br><br>By default, Rust binaries linked with cc_common.link are linked against <code>@bazel_tools//tools/cpp:malloc"</code>, which is an empty library and the resulting binary will use libc's <code>malloc</code>. This label must refer to a <code>cc_library</code> rule. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>@bazel_tools//tools/cpp:malloc</code> | 640| <a id="rust_test-platform"></a>platform | Optional platform to transition the test to. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 641| <a id="rust_test-proc_macro_deps"></a>proc_macro_deps | List of <code>rust_proc_macro</code> targets used to help build this library target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 642| <a id="rust_test-rustc_env"></a>rustc_env | Dictionary of additional <code>"key": "value"</code> 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 | <code>{}</code> | 643| <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 <code>NAME=value</code>, and newlines may be included in a value by ending a line with a trailing back-slash (<code>\\</code>).<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 <code>stamp</code> attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. <code>NAME={WORKSPACE_STATUS_VARIABLE}</code>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 644| <a id="rust_test-rustc_flags"></a>rustc_flags | List of compiler flags passed to <code>rustc</code>.<br><br>These strings are subject to Make variable expansion for predefined source/output path variables like <code>$location</code>, <code>$execpath</code>, and <code>$rootpath</code>. This expansion is useful if you wish to pass a generated file of arguments to rustc: <code>@$(location //package:target)</code>. | List of strings | optional | <code>[]</code> | 645| <a id="rust_test-srcs"></a>srcs | List of Rust <code>.rs</code> source files used to build the library.<br><br>If <code>srcs</code> contains more than one file, then there must be a file either named <code>lib.rs</code>. Otherwise, <code>crate_root</code> 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 | <code>[]</code> | 646| <a id="rust_test-stamp"></a>stamp | Whether to encode build information into the <code>Rustc</code> action. Possible values:<br><br>- <code>stamp = 1</code>: Always stamp the build information into the <code>Rustc</code> 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>- <code>stamp = 0</code>: Always replace build information by constant values. This gives good build result caching.<br><br>- <code>stamp = -1</code>: 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 <code>rust_library</code> is stamped, and a <code>rust_binary</code> depends on that library, the stamped library won't be rebuilt when we change sources of the <code>rust_binary</code>. This is different from how [<code>cc_library.linkstamps</code>](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp) behaves. | Integer | optional | <code>0</code> | 647| <a id="rust_test-use_libtest_harness"></a>use_libtest_harness | Whether to use <code>libtest</code>. 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. <code>bazel test //src:rust_test --test_arg=foo::test::test_fn</code>. | Boolean | optional | <code>True</code> | 648| <a id="rust_test-version"></a>version | A version to inject in the cargo environment variable. | String | optional | <code>"0.0.0"</code> | 649 650 651<a id="rust_test_suite"></a> 652 653## rust_test_suite 654 655<pre> 656rust_test_suite(<a href="#rust_test_suite-name">name</a>, <a href="#rust_test_suite-srcs">srcs</a>, <a href="#rust_test_suite-kwargs">kwargs</a>) 657</pre> 658 659A rule for creating a test suite for a set of `rust_test` targets. 660 661This rule can be used for setting up typical rust [integration tests][it]. Given the following 662directory structure: 663 664```text 665[crate]/ 666 BUILD.bazel 667 src/ 668 lib.rs 669 main.rs 670 tests/ 671 integrated_test_a.rs 672 integrated_test_b.rs 673 integrated_test_c.rs 674 patterns/ 675 fibonacci_test.rs 676``` 677 678The rule can be used to generate [rust_test](#rust_test) targets for each source file under `tests` 679and a [test_suite][ts] which encapsulates all tests. 680 681```python 682load("//rust:defs.bzl", "rust_binary", "rust_library", "rust_test_suite") 683 684rust_library( 685 name = "math_lib", 686 srcs = ["src/lib.rs"], 687) 688 689rust_binary( 690 name = "math_bin", 691 srcs = ["src/main.rs"], 692) 693 694rust_test_suite( 695 name = "integrated_tests_suite", 696 srcs = glob(["tests/**"]), 697 deps = [":math_lib"], 698) 699``` 700 701[it]: https://doc.rust-lang.org/rust-by-example/testing/integration_testing.html 702[ts]: https://docs.bazel.build/versions/master/be/general.html#test_suite 703 704 705**PARAMETERS** 706 707 708| Name | Description | Default Value | 709| :------------- | :------------- | :------------- | 710| <a id="rust_test_suite-name"></a>name | The name of the <code>test_suite</code>. | none | 711| <a id="rust_test_suite-srcs"></a>srcs | All test sources, typically <code>glob(["tests/**/*.rs"])</code>. | none | 712| <a id="rust_test_suite-kwargs"></a>kwargs | Additional keyword arguments for the underyling [rust_test](#rust_test) targets. The <code>tags</code> argument is also passed to the generated <code>test_suite</code> target. | none | 713 714 715