From 00208ea6e522551d32ce03215df76a5c812265ca Mon Sep 17 00:00:00 2001 From: David Freese Date: Sat, 17 Apr 2021 22:37:17 -0700 Subject: [PATCH 1/3] Add github action to generate and push docs to docs branch Instead of requiring that users regenerate auto-generated documentation each time it changes, this adds a github action to force push any changes on the main branch to the docs branch. Github pages allows docs to be on any branch, in the docs folder. There may be some permissions issues with the docs branch. In that case, I'm fine reverting this immediately afterwards. I've tested this to the extent I could on my forked repository. --- .bazelci/presubmit.yml | 8 - .github/workflows/gen_docs.yaml | 18 + .github/workflows/scripts/install_bazelisk.sh | 7 + .github/workflows/scripts/publish_docs.sh | 24 + docs/cargo_build_script.md | 86 - docs/defs.md | 686 -------- docs/flatten.md | 1531 ----------------- docs/rust_analyzer.md | 23 - docs/rust_bindgen.md | 89 - docs/rust_clippy.md | 58 - docs/rust_doc.md | 117 -- docs/rust_proto.md | 167 -- 12 files changed, 49 insertions(+), 2765 deletions(-) create mode 100644 .github/workflows/gen_docs.yaml create mode 100755 .github/workflows/scripts/install_bazelisk.sh create mode 100755 .github/workflows/scripts/publish_docs.sh delete mode 100644 docs/cargo_build_script.md delete mode 100644 docs/defs.md delete mode 100644 docs/flatten.md delete mode 100644 docs/rust_analyzer.md delete mode 100644 docs/rust_bindgen.md delete mode 100644 docs/rust_clippy.md delete mode 100644 docs/rust_doc.md delete mode 100644 docs/rust_proto.md diff --git a/.bazelci/presubmit.yml b/.bazelci/presubmit.yml index 4b22c882c8..402801377f 100644 --- a/.bazelci/presubmit.yml +++ b/.bazelci/presubmit.yml @@ -78,14 +78,6 @@ tasks: working_directory: examples test_targets: - //... - docs_linux: - name: Docs - platform: ubuntu1804 - working_directory: docs - build_targets: - - //... - run_targets: - - "//:test_docs" clippy_examples: name: Clippy on Examples platform: ubuntu1804 diff --git a/.github/workflows/gen_docs.yaml b/.github/workflows/gen_docs.yaml new file mode 100644 index 0000000000..1d769c3c90 --- /dev/null +++ b/.github/workflows/gen_docs.yaml @@ -0,0 +1,18 @@ +name: Generate Documenation Pages +on: + push: + branches: + - main +jobs: + generate: + if: ${{ github.repository_owner == 'bazelbuild' }} + name: Generate Docs + runs-on: ubuntu-20.04 + steps: + - uses: actions/checkout@v2 + - name: Install bazelisk + run: .github/workflows/scripts/install_bazelisk.sh + env: + USE_BAZEL_VERSION: 4.0.0 + - name: Generate and Push + run: .github/workflows/scripts/publish_docs.sh diff --git a/.github/workflows/scripts/install_bazelisk.sh b/.github/workflows/scripts/install_bazelisk.sh new file mode 100755 index 0000000000..a38b147659 --- /dev/null +++ b/.github/workflows/scripts/install_bazelisk.sh @@ -0,0 +1,7 @@ +#!/bin/bash +set -euo pipefail + +curl -LO "https://github.com/bazelbuild/bazelisk/releases/download/v1.1.0/bazelisk-linux-amd64" +mkdir -p "${GITHUB_WORKSPACE}/bin/" +mv bazelisk-linux-amd64 "${GITHUB_WORKSPACE}/bin/bazel" +chmod +x "${GITHUB_WORKSPACE}/bin/bazel" diff --git a/.github/workflows/scripts/publish_docs.sh b/.github/workflows/scripts/publish_docs.sh new file mode 100755 index 0000000000..893a06b066 --- /dev/null +++ b/.github/workflows/scripts/publish_docs.sh @@ -0,0 +1,24 @@ +#!/bin/bash +set -exuo pipefail + +# run within the docs workspace +pushd docs &> /dev/null + +# We use a bazelisk-installed bazel +"${GITHUB_WORKSPACE}/bin/bazel" clean +"${GITHUB_WORKSPACE}/bin/bazel" build //... + +# Pull out the relevant docs +cp bazel-bin/*.md . +chmod 0644 *.md + +# And generate a new commit, that we push to the "docs" branch. +git config user.name github-actions +git config user.email github-actions@github.com +git add *.md +git commit -m "Regenerate documentation" +git remote -v +git push -f origin HEAD:docs + +popd &> /dev/null + diff --git a/docs/cargo_build_script.md b/docs/cargo_build_script.md deleted file mode 100644 index 6df78c3e9a..0000000000 --- a/docs/cargo_build_script.md +++ /dev/null @@ -1,86 +0,0 @@ -# Rust rules -* [cargo_build_script](#cargo_build_script) - - - -## cargo_build_script - -
-cargo_build_script(name, crate_features, version, deps, build_script_env, data, links, rustc_env,
-                   kwargs)
-
- -Compile and execute a rust build script to generate build attributes - -This rules take the same arguments as rust_binary. - -Example: - -Suppose you have a crate with a cargo build script `build.rs`: - -```output -[workspace]/ - hello_lib/ - BUILD - build.rs - src/ - lib.rs -``` - -Then you want to use the build script in the following: - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_binary", "rust_library") -load("@rules_rust//cargo:cargo_build_script.bzl", "cargo_build_script") - -# This will run the build script from the root of the workspace, and -# collect the outputs. -cargo_build_script( - name = "build_script", - srcs = ["build.rs"], - # Optional environment variables passed during build.rs compilation - rustc_env = { - "CARGO_PKG_VERSION": "0.1.2", - }, - # Optional environment variables passed during build.rs execution. - # Note that as the build script's working directory is not execroot, - # execpath/location will return an absolute path, instead of a relative - # one. - build_script_env = { - "SOME_TOOL_OR_FILE": "$(execpath @tool//:binary)" - } - # Optional data/tool dependencies - data = ["@tool//:binary"], -) - -rust_library( - name = "hello_lib", - srcs = [ - "src/lib.rs", - ], - deps = [":build_script"], -) -``` - -The `hello_lib` target will be build with the flags and the environment variables declared by the build script in addition to the file generated by it. - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name | The name for the underlying rule. This should be the name of the package being compiled, optionally with a suffix of _build_script. | none | -| crate_features | A list of features to enable for the build script. | [] | -| version | The semantic version (semver) of the crate. | None | -| deps | The dependencies of the crate. | [] | -| build_script_env | Environment variables for build scripts. | {} | -| data | Files or tools needed by the build script. | [] | -| links | Name of the native library this crate links against. | None | -| rustc_env | Environment variables to set in rustc when compiling the build script. | {} | -| kwargs | Forwards to the underlying rust_binary rule. | none | - - diff --git a/docs/defs.md b/docs/defs.md deleted file mode 100644 index e8ca9e6753..0000000000 --- a/docs/defs.md +++ /dev/null @@ -1,686 +0,0 @@ -# Rust rules -* [rust_binary](#rust_binary) -* [rust_library](#rust_library) -* [rust_static_library](#rust_static_library) -* [rust_shared_library](#rust_shared_library) -* [rust_proc_macro](#rust_proc_macro) -* [rust_benchmark](#rust_benchmark) -* [rust_test](#rust_test) -* [rust_test_suite](#rust_test_suite) - - - -## rust_benchmark - -
-rust_benchmark(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-               edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-               version)
-
- -Builds a Rust benchmark test. - -**Warning**: This rule is currently experimental. [Rust Benchmark tests][rust-bench] require the `Bencher` interface in the unstable `libtest` crate, which is behind the `test` unstable feature gate. As a result, using this rule would require using a nightly binary release of Rust. - -[rust-bench]: https://doc.rust-lang.org/book/benchmark-tests.html - -Example: - -Suppose you have the following directory structure for a Rust project with a library crate, `fibonacci` with benchmarks under the `benches/` directory: - -```output -[workspace]/ -WORKSPACE -fibonacci/ - BUILD - src/ - lib.rs - benches/ - fibonacci_bench.rs -``` - -`fibonacci/src/lib.rs`: -```rust -pub fn fibonacci(n: u64) -> u64 { - if n < 2 { - return n; - } - let mut n1: u64 = 0; - let mut n2: u64 = 1; - for _ in 1..n { - let sum = n1 + n2; - n1 = n2; - n2 = sum; - } - n2 -} -``` - -`fibonacci/benches/fibonacci_bench.rs`: -```rust -#![feature(test)] - -extern crate test; -extern crate fibonacci; - -use test::Bencher; - -#[bench] -fn bench_fibonacci(b: &mut Bencher) { - b.iter(|| fibonacci::fibonacci(40)); -} -``` - -To build the benchmark test, add a `rust_benchmark` target: - -`fibonacci/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:defs.bzl", "rust_library", "rust_benchmark") - -rust_library( -name = "fibonacci", -srcs = ["src/lib.rs"], -) - -rust_benchmark( -name = "fibonacci_bench", -srcs = ["benches/fibonacci_bench.rs"], -deps = [":fibonacci"], -) -``` - -Run the benchmark test using: `bazel run //fibonacci:fibonacci_bench`. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_binary - -
-rust_binary(name, aliases, compile_data, crate_features, crate_name, crate_root, crate_type, data,
-            deps, edition, linker_script, out_binary, out_dir_tar, proc_macro_deps, rustc_env,
-            rustc_env_files, rustc_flags, srcs, version)
-
- -Builds a Rust binary crate. - -Example: - -Suppose you have the following directory structure for a Rust project with a -library crate, `hello_lib`, and a binary crate, `hello_world` that uses the -`hello_lib` library: - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs - hello_world/ - BUILD - src/ - main.rs -``` - -`hello_lib/src/lib.rs`: -```rust -pub struct Greeter { - greeting: String, -} - -impl Greeter { - pub fn new(greeting: &str) -> Greeter { - Greeter { greeting: greeting.to_string(), } - } - - pub fn greet(&self, thing: &str) { - println!("{} {}", &self.greeting, thing); - } -} -``` - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_library") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) -``` - -`hello_world/src/main.rs`: -```rust -extern crate hello_lib; - -fn main() { - let hello = hello_lib::Greeter::new("Hello"); - hello.greet("world"); -} -``` - -`hello_world/BUILD`: -```python -load("@rules_rust//rust:rust.bzl", "rust_binary") - -rust_binary( - name = "hello_world", - srcs = ["src/main.rs"], - deps = ["//hello_lib"], -) -``` - -Build and run `hello_world`: -``` -$ bazel run //hello_world -INFO: Found 1 target... -Target //examples/rust/hello_world:hello_world up-to-date: -bazel-bin/examples/rust/hello_world/hello_world -INFO: Elapsed time: 1.308s, Critical Path: 1.22s - -INFO: Running command line: bazel-bin/examples/rust/hello_world/hello_world -Hello world -``` - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

These can be either other rust_library targets or cc_library targets if linking a native library. | List of labels | optional | [] | -| edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | "" | -| linker_script | Link script to forward into linker via rustc options. | Label | optional | None | -| out_binary | - | Boolean | optional | False | -| out_dir_tar | __Deprecated__, do not use, see [#cargo_build_script] instead. | Label | optional | None | -| proc_macro_deps | List of rust_library targets with kind proc-macro used to help build this library target. | List of labels | optional | [] | -| rustc_env | Dictionary of additional "key": "value" environment variables to set for rustc.

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_library - -
-rust_library(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-             edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-             version)
-
- -Builds a Rust library crate. - -Example: - -Suppose you have the following directory structure for a simple Rust library crate: - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - greeter.rs - lib.rs -``` - -`hello_lib/src/greeter.rs`: -```rust -pub struct Greeter { - greeting: String, -} - -impl Greeter { - pub fn new(greeting: &str) -> Greeter { - Greeter { greeting: greeting.to_string(), } - } - - pub fn greet(&self, thing: &str) { - println!("{} {}", &self.greeting, thing); - } -} -``` - -`hello_lib/src/lib.rs`: - -```rust -pub mod greeter; -``` - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_library") - -rust_library( - name = "hello_lib", - srcs = [ - "src/greeter.rs", - "src/lib.rs", - ], -) -``` - -Build the library: -```output -$ bazel build //hello_lib -INFO: Found 1 target... -Target //examples/rust/hello_lib:hello_lib up-to-date: -bazel-bin/examples/rust/hello_lib/libhello_lib.rlib -INFO: Elapsed time: 1.245s, Critical Path: 1.01s -``` - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_proc_macro - -
-rust_proc_macro(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-                edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-                version)
-
- -Builds a Rust proc-macro crate. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_shared_library - -
-rust_shared_library(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-                    edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags,
-                    srcs, version)
-
- -Builds a Rust shared library. - -This shared library will contain all transitively reachable crates and native objects. -It is meant to be used when producing an artifact that is then consumed by some other build system -(for example to produce a shared library that Python program links against). - -This rule provides CcInfo, so it can be used everywhere Bazel expects `rules_cc`. - -When building the whole binary in Bazel, use `rust_library` instead. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_static_library - -
-rust_static_library(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-                    edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags,
-                    srcs, version)
-
- -Builds a Rust static library. - -This static library will contain all transitively reachable crates and native objects. -It is meant to be used when producing an artifact that is then consumed by some other build system -(for example to produce an archive that Python program links against). - -This rule provides CcInfo, so it can be used everywhere Bazel expects `rules_cc`. - -When building the whole binary in Bazel, use `rust_library` instead. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_test - -
-rust_test(name, aliases, compile_data, crate, crate_features, crate_name, crate_root, data, deps,
-          edition, env, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-          version)
-
- -Builds a Rust test crate. - -Examples: - -Suppose you have the following directory structure for a Rust library crate with unit test code in the library sources: - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs -``` - -`hello_lib/src/lib.rs`: -```rust -pub struct Greeter { - greeting: String, -} - -impl Greeter { - pub fn new(greeting: &str) -> Greeter { - Greeter { greeting: greeting.to_string(), } - } - - pub fn greet(&self, thing: &str) { - println!("{} {}", &self.greeting, thing); - } -} - -#[cfg(test)] -mod test { - use super::Greeter; - - #[test] - fn test_greeting() { - let hello = Greeter::new("Hi"); - assert_eq!("Hi Rust", hello.greet("Rust")); - } -} -``` - -To build and run the tests, simply add a `rust_test` rule with no `srcs` and only depends on the `hello_lib` `rust_library` target: - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) - -rust_test( - name = "hello_lib_test", - deps = [":hello_lib"], -) -``` - -Run the test with `bazel build //hello_lib:hello_lib_test`. - -To run a crate or lib with the `#[cfg(test)]` configuration, handling inline tests, you should specify the crate directly like so. - -```python -rust_test( - name = "hello_lib_test", - crate = ":hello_lib", - # You may add other deps that are specific to the test configuration - deps = ["//some/dev/dep"], -) -``` - -### Example: `test` directory - -Integration tests that live in the [`tests` directory][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: - -[int-tests]: http://doc.rust-lang.org/book/testing.html#the-tests-directory - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs - tests/ - greeting.rs -``` - -`hello_lib/tests/greeting.rs`: -```rust -extern crate hello_lib; - -use hello_lib; - -#[test] -fn test_greeting() { - let hello = greeter::Greeter::new("Hello"); - assert_eq!("Hello world", hello.greeting("world")); -} -``` - -To build the `greeting.rs` integration test, simply add a `rust_test` target -with `greeting.rs` in `srcs` and a dependency on the `hello_lib` target: - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) - -rust_test( - name = "greeting_test", - srcs = ["tests/greeting.rs"], - deps = [":hello_lib"], -) -``` - -Run the test with `bazel build //hello_lib:hello_lib_test`. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate | Target inline tests declared in the given crate

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

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

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

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

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

These can be either other rust_library targets or cc_library targets if linking a native library. | List of labels | optional | [] | -| edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | "" | -| env | Specifies additional environment variables to set when the test is executed by bazel test. Values are subject to $(execpath) and ["Make variable"](https://docs.bazel.build/versions/master/be/make-variables.html) substitution. | Dictionary: String -> String | optional | {} | -| out_dir_tar | __Deprecated__, do not use, see [#cargo_build_script] instead. | Label | optional | None | -| proc_macro_deps | List of rust_library targets with kind proc-macro used to help build this library target. | List of labels | optional | [] | -| rustc_env | Dictionary of additional "key": "value" environment variables to set for rustc.

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_test_suite - -
-rust_test_suite(name, srcs, kwargs)
-
- -A rule for creating a test suite for a set of `rust_test` targets. - -This rule can be used for setting up typical rust [integration tests][it]. Given the following -directory structure: - -```text -[crate]/ - BUILD.bazel - src/ - lib.rs - main.rs - tests/ - integrated_test_a.rs - integrated_test_b.rs - integrated_test_c.rs - patterns/ - fibonacci_test.rs -``` - -The rule can be used to generate [rust_test](#rust_test) targets for each source file under `tests` -and a [test_suite][ts] which encapsulates all tests. - -```python -load("//rust:defs.bzl", "rust_binary", "rust_library", "rust_test_suite") - -rust_library( - name = "math_lib", - srcs = ["src/lib.rs"], -) - -rust_binary( - name = "math_bin", - srcs = ["src/main.rs"], -) - -rust_test_suite( - name = "integrated_tests_suite", - srcs = glob(["tests/**"]), - deps = [":math_lib"], -) -``` - -[it]: https://doc.rust-lang.org/rust-by-example/testing/integration_testing.html -[ts]: https://docs.bazel.build/versions/master/be/general.html#test_suite - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name | The name of the test_suite. | none | -| srcs | All test sources, typically glob(["tests/**/*.rs"]). | none | -| kwargs | Additional keyword arguments for the underyling [rust_test](#rust_test) targets. The tags argument is also passed to the generated test_suite target. | none | - - diff --git a/docs/flatten.md b/docs/flatten.md deleted file mode 100644 index 6aaab4a1e3..0000000000 --- a/docs/flatten.md +++ /dev/null @@ -1,1531 +0,0 @@ -# Rust rules - -* [cargo_build_script](#cargo_build_script) -* [rust_analyzer](#rust_analyzer) -* [rust_analyzer_aspect](#rust_analyzer_aspect) -* [rust_benchmark](#rust_benchmark) -* [rust_binary](#rust_binary) -* [rust_bindgen](#rust_bindgen) -* [rust_bindgen_library](#rust_bindgen_library) -* [rust_bindgen_repositories](#rust_bindgen_repositories) -* [rust_bindgen_toolchain](#rust_bindgen_toolchain) -* [rust_clippy](#rust_clippy) -* [rust_clippy_aspect](#rust_clippy_aspect) -* [rust_doc](#rust_doc) -* [rust_doc_test](#rust_doc_test) -* [rust_grpc_library](#rust_grpc_library) -* [rust_library](#rust_library) -* [rust_proc_macro](#rust_proc_macro) -* [rust_proto_library](#rust_proto_library) -* [rust_proto_repositories](#rust_proto_repositories) -* [rust_proto_toolchain](#rust_proto_toolchain) -* [rust_repositories](#rust_repositories) -* [rust_repository_set](#rust_repository_set) -* [rust_shared_library](#rust_shared_library) -* [rust_static_library](#rust_static_library) -* [rust_test](#rust_test) -* [rust_test_suite](#rust_test_suite) -* [rust_toolchain](#rust_toolchain) -* [rust_toolchain_repository](#rust_toolchain_repository) -* [rust_toolchain_repository_proxy](#rust_toolchain_repository_proxy) -* [rust_wasm_bindgen](#rust_wasm_bindgen) -* [rust_wasm_bindgen_repositories](#rust_wasm_bindgen_repositories) -* [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain) - - - - -## rust_analyzer - -
-rust_analyzer(name, targets)
-
- -Produces a rust-project.json for the given targets. Configure rust-analyzer to load the generated file via the linked projects mechanism. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| targets | List of all targets to be included in the index | List of labels | optional | [] | - - - - -## rust_benchmark - -
-rust_benchmark(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-               edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-               version)
-
- -Builds a Rust benchmark test. - -**Warning**: This rule is currently experimental. [Rust Benchmark tests][rust-bench] require the `Bencher` interface in the unstable `libtest` crate, which is behind the `test` unstable feature gate. As a result, using this rule would require using a nightly binary release of Rust. - -[rust-bench]: https://doc.rust-lang.org/book/benchmark-tests.html - -Example: - -Suppose you have the following directory structure for a Rust project with a library crate, `fibonacci` with benchmarks under the `benches/` directory: - -```output -[workspace]/ -WORKSPACE -fibonacci/ - BUILD - src/ - lib.rs - benches/ - fibonacci_bench.rs -``` - -`fibonacci/src/lib.rs`: -```rust -pub fn fibonacci(n: u64) -> u64 { - if n < 2 { - return n; - } - let mut n1: u64 = 0; - let mut n2: u64 = 1; - for _ in 1..n { - let sum = n1 + n2; - n1 = n2; - n2 = sum; - } - n2 -} -``` - -`fibonacci/benches/fibonacci_bench.rs`: -```rust -#![feature(test)] - -extern crate test; -extern crate fibonacci; - -use test::Bencher; - -#[bench] -fn bench_fibonacci(b: &mut Bencher) { - b.iter(|| fibonacci::fibonacci(40)); -} -``` - -To build the benchmark test, add a `rust_benchmark` target: - -`fibonacci/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:defs.bzl", "rust_library", "rust_benchmark") - -rust_library( -name = "fibonacci", -srcs = ["src/lib.rs"], -) - -rust_benchmark( -name = "fibonacci_bench", -srcs = ["benches/fibonacci_bench.rs"], -deps = [":fibonacci"], -) -``` - -Run the benchmark test using: `bazel run //fibonacci:fibonacci_bench`. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_binary - -
-rust_binary(name, aliases, compile_data, crate_features, crate_name, crate_root, crate_type, data,
-            deps, edition, linker_script, out_binary, out_dir_tar, proc_macro_deps, rustc_env,
-            rustc_env_files, rustc_flags, srcs, version)
-
- -Builds a Rust binary crate. - -Example: - -Suppose you have the following directory structure for a Rust project with a -library crate, `hello_lib`, and a binary crate, `hello_world` that uses the -`hello_lib` library: - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs - hello_world/ - BUILD - src/ - main.rs -``` - -`hello_lib/src/lib.rs`: -```rust -pub struct Greeter { - greeting: String, -} - -impl Greeter { - pub fn new(greeting: &str) -> Greeter { - Greeter { greeting: greeting.to_string(), } - } - - pub fn greet(&self, thing: &str) { - println!("{} {}", &self.greeting, thing); - } -} -``` - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_library") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) -``` - -`hello_world/src/main.rs`: -```rust -extern crate hello_lib; - -fn main() { - let hello = hello_lib::Greeter::new("Hello"); - hello.greet("world"); -} -``` - -`hello_world/BUILD`: -```python -load("@rules_rust//rust:rust.bzl", "rust_binary") - -rust_binary( - name = "hello_world", - srcs = ["src/main.rs"], - deps = ["//hello_lib"], -) -``` - -Build and run `hello_world`: -``` -$ bazel run //hello_world -INFO: Found 1 target... -Target //examples/rust/hello_world:hello_world up-to-date: -bazel-bin/examples/rust/hello_world/hello_world -INFO: Elapsed time: 1.308s, Critical Path: 1.22s - -INFO: Running command line: bazel-bin/examples/rust/hello_world/hello_world -Hello world -``` - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

These can be either other rust_library targets or cc_library targets if linking a native library. | List of labels | optional | [] | -| edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | "" | -| linker_script | Link script to forward into linker via rustc options. | Label | optional | None | -| out_binary | - | Boolean | optional | False | -| out_dir_tar | __Deprecated__, do not use, see [#cargo_build_script] instead. | Label | optional | None | -| proc_macro_deps | List of rust_library targets with kind proc-macro used to help build this library target. | List of labels | optional | [] | -| rustc_env | Dictionary of additional "key": "value" environment variables to set for rustc.

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_bindgen - -
-rust_bindgen(name, bindgen_flags, cc_lib, clang_flags, header)
-
- -Generates a rust source file from a cc_library and a header. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| bindgen_flags | Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. | List of strings | optional | [] | -| cc_lib | The cc_library that contains the .h file. This is used to find the transitive includes. | Label | optional | None | -| clang_flags | Flags to pass directly to the clang executable. | List of strings | optional | [] | -| header | The .h file to generate bindings for. | Label | optional | None | - - - - -## rust_bindgen_toolchain - -
-rust_bindgen_toolchain(name, bindgen, clang, libclang, libstdcxx, rustfmt)
-
- -The tools required for the `rust_bindgen` rule. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| bindgen | The label of a bindgen executable. | Label | optional | None | -| clang | The label of a clang executable. | Label | optional | None | -| libclang | A cc_library that provides bindgen's runtime dependency on libclang. | Label | optional | None | -| libstdcxx | A cc_library that satisfies libclang's libstdc++ dependency. | Label | optional | None | -| rustfmt | The label of a rustfmt executable. If this is provided, generated sources will be formatted. | Label | optional | None | - - - - -## rust_clippy - -
-rust_clippy(name, deps)
-
- -Executes the clippy checker on a specific target. - -Similar to `rust_clippy_aspect`, but allows specifying a list of dependencies within the build system. - -For example, given the following example targets: - -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_library", "rust_test") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) - -rust_test( - name = "greeting_test", - srcs = ["tests/greeting.rs"], - deps = [":hello_lib"], -) -``` - -Rust clippy can be set as a build target with the following: - -```python -rust_clippy( - name = "hello_library_clippy", - testonly = True, - deps = [ - ":hello_lib", - ":greeting_test", - ], -) -``` - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| deps | - | List of labels | optional | [] | - - - - -## rust_doc - -
-rust_doc(name, dep, html_after_content, html_before_content, html_in_header, markdown_css)
-
- -Generates code documentation. - -Example: - Suppose you have the following directory structure for a Rust library crate: - - ``` - [workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs - ``` - - To build [`rustdoc`][rustdoc] documentation for the `hello_lib` crate, define a `rust_doc` rule that depends on the the `hello_lib` `rust_library` target: - - [rustdoc]: https://doc.rust-lang.org/book/documentation.html - - ```python - package(default_visibility = ["//visibility:public"]) - - load("@rules_rust//rust:rust.bzl", "rust_library", "rust_doc") - - rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], - ) - - rust_doc( - name = "hello_lib_doc", - dep = ":hello_lib", - ) - ``` - - Running `bazel build //hello_lib:hello_lib_doc` will build a zip file containing the documentation for the `hello_lib` library crate generated by `rustdoc`. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| dep | The label of the target to generate code documentation for.

rust_doc can generate HTML code documentation for the source files of rust_library or rust_binary targets. | Label | required | | -| html_after_content | File to add in <body>, after content. | Label | optional | None | -| html_before_content | File to add in <body>, before content. | Label | optional | None | -| html_in_header | File to add to <head>. | Label | optional | None | -| markdown_css | CSS files to include via <link> in a rendered Markdown file. | List of labels | optional | [] | - - - - -## rust_doc_test - -
-rust_doc_test(name, dep)
-
- -Runs Rust documentation tests. - -Example: - -Suppose you have the following directory structure for a Rust library crate: - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs -``` - -To run [documentation tests][doc-test] for the `hello_lib` crate, define a `rust_doc_test` target that depends on the `hello_lib` `rust_library` target: - -[doc-test]: https://doc.rust-lang.org/book/documentation.html#documentation-as-tests - -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_library", "rust_doc_test") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) - -rust_doc_test( - name = "hello_lib_doc_test", - dep = ":hello_lib", -) -``` - -Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation tests for the `hello_lib` library crate. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| dep | The label of the target to run documentation tests for.

rust_doc_test can run documentation tests for the source files of rust_library or rust_binary targets. | Label | required | | - - - - -## rust_grpc_library - -
-rust_grpc_library(name, deps, rust_deps)
-
- -Builds a Rust library crate from a set of `proto_library`s suitable for gRPC. - -Example: - -```python -load("//proto:proto.bzl", "rust_grpc_library") - -proto_library( - name = "my_proto", - srcs = ["my.proto"] -) - -rust_grpc_library( - name = "rust", - deps = [":my_proto"], -) - -rust_binary( - name = "my_service", - srcs = ["my_service.rs"], - deps = [":rust"], -) -``` - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| deps | List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding gRPC stubs. | List of labels | required | | -| rust_deps | The crates the generated library depends on. | List of labels | optional | [] | - - - - -## rust_library - -
-rust_library(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-             edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-             version)
-
- -Builds a Rust library crate. - -Example: - -Suppose you have the following directory structure for a simple Rust library crate: - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - greeter.rs - lib.rs -``` - -`hello_lib/src/greeter.rs`: -```rust -pub struct Greeter { - greeting: String, -} - -impl Greeter { - pub fn new(greeting: &str) -> Greeter { - Greeter { greeting: greeting.to_string(), } - } - - pub fn greet(&self, thing: &str) { - println!("{} {}", &self.greeting, thing); - } -} -``` - -`hello_lib/src/lib.rs`: - -```rust -pub mod greeter; -``` - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_library") - -rust_library( - name = "hello_lib", - srcs = [ - "src/greeter.rs", - "src/lib.rs", - ], -) -``` - -Build the library: -```output -$ bazel build //hello_lib -INFO: Found 1 target... -Target //examples/rust/hello_lib:hello_lib up-to-date: -bazel-bin/examples/rust/hello_lib/libhello_lib.rlib -INFO: Elapsed time: 1.245s, Critical Path: 1.01s -``` - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_proc_macro - -
-rust_proc_macro(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-                edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-                version)
-
- -Builds a Rust proc-macro crate. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_proto_library - -
-rust_proto_library(name, deps, rust_deps)
-
- -Builds a Rust library crate from a set of `proto_library`s. - -Example: - -```python -load("@rules_rust//proto:proto.bzl", "rust_proto_library") - -proto_library( - name = "my_proto", - srcs = ["my.proto"] -) - -proto_rust_library( - name = "rust", - deps = [":my_proto"], -) - -rust_binary( - name = "my_proto_binary", - srcs = ["my_proto_binary.rs"], - deps = [":rust"], -) -``` - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| deps | List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding stubs. | List of labels | required | | -| rust_deps | The crates the generated library depends on. | List of labels | optional | [] | - - - - -## rust_proto_toolchain - -
-rust_proto_toolchain(name, edition, grpc_compile_deps, grpc_plugin, proto_compile_deps,
-                     proto_plugin, protoc)
-
- -Declares a Rust Proto toolchain for use. - -This is used to configure proto compilation and can be used to set different protobuf compiler plugin. - -Example: - -Suppose a new nicer gRPC plugin has came out. The new plugin can be used in Bazel by defining a new toolchain definition and declaration: - -```python -load('@rules_rust//proto:toolchain.bzl', 'rust_proto_toolchain') - -rust_proto_toolchain( - name="rust_proto_impl", - grpc_plugin="@rust_grpc//:grpc_plugin", - grpc_compile_deps=["@rust_grpc//:grpc_deps"], -) - -toolchain( - name="rust_proto", - exec_compatible_with = [ - "@platforms//cpu:cpuX", - ], - target_compatible_with = [ - "@platforms//cpu:cpuX", - ], - toolchain = ":rust_proto_impl", -) -``` - -Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the `--extra_toolchains` flag for Bazel, and it will be used. - -See @rules_rust//proto:BUILD for examples of defining the toolchain. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| edition | The edition used by the generated rust source. | String | optional | "2015" | -| grpc_compile_deps | The crates the generated grpc libraries depends on. | List of labels | optional | [Label("//proto/raze:protobuf"), Label("//proto/raze:grpc"), Label("//proto/raze:tls_api"), Label("//proto/raze:tls_api_stub")] | -| grpc_plugin | The location of the Rust protobuf compiler plugin to generate rust gRPC stubs. | Label | optional | //proto:protoc_gen_rust_grpc | -| proto_compile_deps | The crates the generated protobuf libraries depends on. | List of labels | optional | [Label("//proto/raze:protobuf")] | -| proto_plugin | The location of the Rust protobuf compiler plugin used to generate rust sources. | Label | optional | //proto:protoc_gen_rust | -| protoc | The location of the protoc binary. It should be an executable target. | Label | optional | @com_google_protobuf//:protoc | - - - - -## rust_shared_library - -
-rust_shared_library(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-                    edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags,
-                    srcs, version)
-
- -Builds a Rust shared library. - -This shared library will contain all transitively reachable crates and native objects. -It is meant to be used when producing an artifact that is then consumed by some other build system -(for example to produce a shared library that Python program links against). - -This rule provides CcInfo, so it can be used everywhere Bazel expects `rules_cc`. - -When building the whole binary in Bazel, use `rust_library` instead. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_static_library - -
-rust_static_library(name, aliases, compile_data, crate_features, crate_name, crate_root, data, deps,
-                    edition, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags,
-                    srcs, version)
-
- -Builds a Rust static library. - -This static library will contain all transitively reachable crates and native objects. -It is meant to be used when producing an artifact that is then consumed by some other build system -(for example to produce an archive that Python program links against). - -This rule provides CcInfo, so it can be used everywhere Bazel expects `rules_cc`. - -When building the whole binary in Bazel, use `rust_library` instead. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate_features | List of features to enable for this crate.

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

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

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

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

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

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_test - -
-rust_test(name, aliases, compile_data, crate, crate_features, crate_name, crate_root, data, deps,
-          edition, env, out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-          version)
-
- -Builds a Rust test crate. - -Examples: - -Suppose you have the following directory structure for a Rust library crate with unit test code in the library sources: - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs -``` - -`hello_lib/src/lib.rs`: -```rust -pub struct Greeter { - greeting: String, -} - -impl Greeter { - pub fn new(greeting: &str) -> Greeter { - Greeter { greeting: greeting.to_string(), } - } - - pub fn greet(&self, thing: &str) { - println!("{} {}", &self.greeting, thing); - } -} - -#[cfg(test)] -mod test { - use super::Greeter; - - #[test] - fn test_greeting() { - let hello = Greeter::new("Hi"); - assert_eq!("Hi Rust", hello.greet("Rust")); - } -} -``` - -To build and run the tests, simply add a `rust_test` rule with no `srcs` and only depends on the `hello_lib` `rust_library` target: - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) - -rust_test( - name = "hello_lib_test", - deps = [":hello_lib"], -) -``` - -Run the test with `bazel build //hello_lib:hello_lib_test`. - -To run a crate or lib with the `#[cfg(test)]` configuration, handling inline tests, you should specify the crate directly like so. - -```python -rust_test( - name = "hello_lib_test", - crate = ":hello_lib", - # You may add other deps that are specific to the test configuration - deps = ["//some/dev/dep"], -) -``` - -### Example: `test` directory - -Integration tests that live in the [`tests` directory][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: - -[int-tests]: http://doc.rust-lang.org/book/testing.html#the-tests-directory - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs - tests/ - greeting.rs -``` - -`hello_lib/tests/greeting.rs`: -```rust -extern crate hello_lib; - -use hello_lib; - -#[test] -fn test_greeting() { - let hello = greeter::Greeter::new("Hello"); - assert_eq!("Hello world", hello.greeting("world")); -} -``` - -To build the `greeting.rs` integration test, simply add a `rust_test` target -with `greeting.rs` in `srcs` and a dependency on the `hello_lib` target: - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) - -rust_test( - name = "greeting_test", - srcs = ["tests/greeting.rs"], - deps = [":hello_lib"], -) -``` - -Run the test with `bazel build //hello_lib:hello_lib_test`. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| aliases | Remap crates to a new name or moniker for linkage to this target

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

This attribute can be used to specify any data files that are embedded into the library, such as via the [include_str!](https://doc.rust-lang.org/std/macro.include_str!.html) macro. | List of labels | optional | [] | -| crate | Target inline tests declared in the given crate

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

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

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

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

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

These can be either other rust_library targets or cc_library targets if linking a native library. | List of labels | optional | [] | -| edition | The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. | String | optional | "" | -| env | Specifies additional environment variables to set when the test is executed by bazel test. Values are subject to $(execpath) and ["Make variable"](https://docs.bazel.build/versions/master/be/make-variables.html) substitution. | Dictionary: String -> String | optional | {} | -| out_dir_tar | __Deprecated__, do not use, see [#cargo_build_script] instead. | Label | optional | None | -| proc_macro_deps | List of rust_library targets with kind proc-macro used to help build this library target. | List of labels | optional | [] | -| rustc_env | Dictionary of additional "key": "value" environment variables to set for rustc.

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

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

The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. | List of labels | optional | [] | -| rustc_flags | List of compiler flags passed to rustc. | List of strings | optional | [] | -| srcs | List of Rust .rs source files used to build the library.

If srcs contains more than one file, then there must be a file either named lib.rs. Otherwise, crate_root must be set to the source file that is the root of the crate to be passed to rustc to build this crate. | List of labels | optional | [] | -| version | A version to inject in the cargo environment variable. | String | optional | "0.0.0" | - - - - -## rust_toolchain - -
-rust_toolchain(name, allocator_library, binary_ext, cargo, clippy_driver, debug_info,
-               default_edition, dylib_ext, exec_triple, opt_level, os, rust_doc, rust_lib, rustc,
-               rustc_lib, rustc_src, rustfmt, staticlib_ext, stdlib_linkflags, target_triple)
-
- -Declares a Rust toolchain for use. - -This is for declaring a custom toolchain, eg. for configuring a particular version of rust or supporting a new platform. - -Example: - -Suppose the core rust team has ported the compiler to a new target CPU, called `cpuX`. This support can be used in Bazel by defining a new toolchain definition and declaration: - -```python -load('@rules_rust//rust:toolchain.bzl', 'rust_toolchain') - -rust_toolchain( - name = "rust_cpuX_impl", - rustc = "@rust_cpuX//:rustc", - rustc_lib = "@rust_cpuX//:rustc_lib", - rust_lib = "@rust_cpuX//:rust_lib", - rust_doc = "@rust_cpuX//:rustdoc", - binary_ext = "", - staticlib_ext = ".a", - dylib_ext = ".so", - stdlib_linkflags = ["-lpthread", "-ldl"], - os = "linux", -) - -toolchain( - name = "rust_cpuX", - exec_compatible_with = [ - "@platforms//cpu:cpuX", - ], - target_compatible_with = [ - "@platforms//cpu:cpuX", - ], - toolchain = ":rust_cpuX_impl", -) -``` - -Then, either add the label of the toolchain rule to `register_toolchains` in the WORKSPACE, or pass it to the `"--extra_toolchains"` flag for Bazel, and it will be used. - -See @rules_rust//rust:repositories.bzl for examples of defining the @rust_cpuX repository with the actual binaries and libraries. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| allocator_library | Target that provides allocator functions when rust_library targets are embedded in a cc_binary. | Label | optional | None | -| binary_ext | The extension for binaries created from rustc. | String | required | | -| cargo | The location of the cargo binary. Can be a direct source or a filegroup containing one item. | Label | optional | None | -| clippy_driver | The location of the clippy-driver binary. Can be a direct source or a filegroup containing one item. | Label | optional | None | -| debug_info | Rustc debug info levels per opt level | Dictionary: String -> String | optional | {"dbg": "2", "fastbuild": "0", "opt": "0"} | -| default_edition | The edition to use for rust_* rules that don't specify an edition. | String | optional | "2015" | -| dylib_ext | The extension for dynamic libraries created from rustc. | String | required | | -| exec_triple | The platform triple for the toolchains execution environment. For more details see: https://docs.bazel.build/versions/master/skylark/rules.html#configurations | String | optional | "" | -| opt_level | Rustc optimization levels. | Dictionary: String -> String | optional | {"dbg": "0", "fastbuild": "0", "opt": "3"} | -| os | The operating system for the current toolchain | String | required | | -| rust_doc | The location of the rustdoc binary. Can be a direct source or a filegroup containing one item. | Label | optional | None | -| rust_lib | The rust standard library. | Label | optional | None | -| rustc | The location of the rustc binary. Can be a direct source or a filegroup containing one item. | Label | optional | None | -| rustc_lib | The libraries used by rustc during compilation. | Label | optional | None | -| rustc_src | The source code of rustc. | Label | optional | None | -| rustfmt | The location of the rustfmt binary. Can be a direct source or a filegroup containing one item. | Label | optional | None | -| staticlib_ext | The extension for static libraries created from rustc. | String | required | | -| stdlib_linkflags | Additional linker libs used when std lib is linked, see https://github.com/rust-lang/rust/blob/master/src/libstd/build.rs | List of strings | required | | -| target_triple | The platform triple for the toolchains target environment. For more details see: https://docs.bazel.build/versions/master/skylark/rules.html#configurations | String | optional | "" | - - - - -## rust_toolchain_repository - -
-rust_toolchain_repository(name, dev_components, edition, exec_triple, extra_target_triples,
-                          iso_date, repo_mapping, rustfmt_version, sha256s, toolchain_name_prefix,
-                          urls, version)
-
- -Composes a single workspace containing the toolchain components for compiling on a given platform to a series of target platforms. - -A given instance of this rule should be accompanied by a rust_toolchain_repository_proxy invocation to declare its toolchains to Bazel; the indirection allows separating toolchain selection from toolchain fetching. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this repository. | Name | required | | -| dev_components | Whether to download the rustc-dev components (defaults to False). Requires version to be "nightly". | Boolean | optional | False | -| edition | The rust edition to be used by default. | String | optional | "2015" | -| exec_triple | The Rust-style target that this compiler runs on | String | required | | -| extra_target_triples | Additional rust-style targets that this set of toolchains should support. | List of strings | optional | [] | -| iso_date | The date of the tool (or None, if the version is a specific version). | String | optional | "" | -| repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). | Dictionary: String -> String | required | | -| rustfmt_version | The version of the tool among "nightly", "beta", or an exact version. | String | optional | "" | -| sha256s | A dict associating tool subdirectories to sha256 hashes. See [rust_repositories](#rust_repositories) for more details. | Dictionary: String -> String | optional | {} | -| toolchain_name_prefix | The per-target prefix expected for the rust_toolchain declarations in the parent workspace. | String | optional | "" | -| urls | A list of mirror urls containing the tools from the Rust-lang static file server. These must contain the '{}' used to substitute the tool being fetched (using .format). | List of strings | optional | ["https://static.rust-lang.org/dist/{}.tar.gz"] | -| version | The version of the tool among "nightly", "beta", or an exact version. | String | required | | - - - - -## rust_toolchain_repository_proxy - -
-rust_toolchain_repository_proxy(name, exec_triple, extra_target_triples, parent_workspace_name,
-                                repo_mapping, toolchain_name_prefix)
-
- -Generates a toolchain-bearing repository that declares the toolchains from some other rust_toolchain_repository. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this repository. | Name | required | | -| exec_triple | The Rust-style target triple for the compilation platform | String | required | | -| extra_target_triples | The Rust-style triples for extra compilation targets | List of strings | optional | [] | -| parent_workspace_name | The name of the other rust_toolchain_repository | String | required | | -| repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). | Dictionary: String -> String | required | | -| toolchain_name_prefix | The per-target prefix expected for the rust_toolchain declarations in the parent workspace. | String | optional | "" | - - - - -## rust_wasm_bindgen - -
-rust_wasm_bindgen(name, bindgen_flags, wasm_file)
-
- -Generates javascript and typescript bindings for a webassembly module using [wasm-bindgen][ws]. - -[ws]: https://rustwasm.github.io/docs/wasm-bindgen/ - -To use the Rust WebAssembly bindgen rules, add the following to your `WORKSPACE` file to add the -external repositories for the Rust bindgen toolchain (in addition to the Rust rules setup): - -```python -load("@rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositories") - -rust_wasm_bindgen_repositories() -``` - -For more details on `rust_wasm_bindgen_repositories`, see [here](#rust_wasm_bindgen_repositories). - -An example of this rule in use can be seen at [@rules_rust//examples/wasm](../examples/wasm) - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| bindgen_flags | Flags to pass directly to the bindgen executable. See https://github.com/rustwasm/wasm-bindgen/ for details. | List of strings | optional | [] | -| wasm_file | The .wasm file to generate bindings for. | Label | optional | None | - - - - -## rust_wasm_bindgen_toolchain - -
-rust_wasm_bindgen_toolchain(name, bindgen)
-
- -The tools required for the `rust_wasm_bindgen` rule. - -In cases where users want to control or change the version of `wasm-bindgen` used by [rust_wasm_bindgen](#rust_wasm_bindgen), -a unique toolchain can be created as in the example below: - -```python -load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain") - -rust_bindgen_toolchain( - bindgen = "//my/cargo_raze:cargo_bin_wasm_bindgen", -) - -toolchain( - name = "wasm_bindgen_toolchain", - toolchain = "wasm_bindgen_toolchain_impl", - toolchain_type = "@rules_rust//wasm_bindgen:wasm_bindgen_toolchain", -) -``` - -Now that you have your own toolchain, you need to register it by -inserting the following statement in your `WORKSPACE` file: - -```python -register_toolchains("//my/toolchains:wasm_bindgen_toolchain") -``` - -For additional information, see the [Bazel toolchains documentation][toolchains]. - -[toolchains]: https://docs.bazel.build/versions/master/toolchains.html - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| bindgen | The label of a wasm-bindgen-cli executable. | Label | optional | None | - - - - -## cargo_build_script - -
-cargo_build_script(name, crate_features, version, deps, build_script_env, data, links, rustc_env,
-                   kwargs)
-
- -Compile and execute a rust build script to generate build attributes - -This rules take the same arguments as rust_binary. - -Example: - -Suppose you have a crate with a cargo build script `build.rs`: - -```output -[workspace]/ - hello_lib/ - BUILD - build.rs - src/ - lib.rs -``` - -Then you want to use the build script in the following: - -`hello_lib/BUILD`: -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_binary", "rust_library") -load("@rules_rust//cargo:cargo_build_script.bzl", "cargo_build_script") - -# This will run the build script from the root of the workspace, and -# collect the outputs. -cargo_build_script( - name = "build_script", - srcs = ["build.rs"], - # Optional environment variables passed during build.rs compilation - rustc_env = { - "CARGO_PKG_VERSION": "0.1.2", - }, - # Optional environment variables passed during build.rs execution. - # Note that as the build script's working directory is not execroot, - # execpath/location will return an absolute path, instead of a relative - # one. - build_script_env = { - "SOME_TOOL_OR_FILE": "$(execpath @tool//:binary)" - } - # Optional data/tool dependencies - data = ["@tool//:binary"], -) - -rust_library( - name = "hello_lib", - srcs = [ - "src/lib.rs", - ], - deps = [":build_script"], -) -``` - -The `hello_lib` target will be build with the flags and the environment variables declared by the build script in addition to the file generated by it. - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name | The name for the underlying rule. This should be the name of the package being compiled, optionally with a suffix of _build_script. | none | -| crate_features | A list of features to enable for the build script. | [] | -| version | The semantic version (semver) of the crate. | None | -| deps | The dependencies of the crate. | [] | -| build_script_env | Environment variables for build scripts. | {} | -| data | Files or tools needed by the build script. | [] | -| links | Name of the native library this crate links against. | None | -| rustc_env | Environment variables to set in rustc when compiling the build script. | {} | -| kwargs | Forwards to the underlying rust_binary rule. | none | - - - - -## rust_bindgen_library - -
-rust_bindgen_library(name, header, cc_lib, bindgen_flags, clang_flags, kwargs)
-
- -Generates a rust source file for `header`, and builds a rust_library. - -Arguments are the same as `rust_bindgen`, and `kwargs` are passed directly to rust_library. - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name | A unique name for this target. | none | -| header | The label of the .h file to generate bindings for. | none | -| cc_lib | The label of the cc_library that contains the .h file. This is used to find the transitive includes. | none | -| bindgen_flags | Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. | None | -| clang_flags | Flags to pass directly to the clang executable. | None | -| kwargs | Arguments to forward to the underlying rust_library rule. | none | - - - - -## rust_bindgen_repositories - -
-rust_bindgen_repositories()
-
- -Declare dependencies needed for bindgen. - - - - - -## rust_proto_repositories - -
-rust_proto_repositories(register_default_toolchain)
-
- -Declare dependencies needed for proto compilation. - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| register_default_toolchain | If True, the default [rust_proto_toolchain](#rust_proto_toolchain) (@rules_rust//proto:default-proto-toolchain) is registered. This toolchain requires a set of dependencies that were generated using [cargo raze](https://github.com/google/cargo-raze). These will also be loaded. | True | - - - - -## rust_repositories - -
-rust_repositories(version, iso_date, rustfmt_version, edition, dev_components, sha256s, urls)
-
- -Emits a default set of toolchains for Linux, MacOS, and Freebsd - -Skip this macro and call the `rust_repository_set` macros directly if you need a compiler for other hosts or for additional target triples. - -The `sha256` attribute represents a dict associating tool subdirectories to sha256 hashes. As an example: -```python -{ - "rust-1.46.0-x86_64-unknown-linux-gnu": "e3b98bc3440fe92817881933f9564389eccb396f5f431f33d48b979fa2fbdcf5", - "rustfmt-1.4.12-x86_64-unknown-linux-gnu": "1894e76913303d66bf40885a601462844eec15fca9e76a6d13c390d7000d64b0", - "rust-std-1.46.0-x86_64-unknown-linux-gnu": "ac04aef80423f612c0079829b504902de27a6997214eb58ab0765d02f7ec1dbc", -} -``` -This would match for `exec_triple = "x86_64-unknown-linux-gnu"`. If not specified, rules_rust pulls from a non-exhaustive list of known checksums.. - -See `load_arbitrary_tool` in `@rules_rust//rust:repositories.bzl` for more details. - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| version | The version of Rust. Either "nightly", "beta", or an exact version. Defaults to a modern version. | "1.51.0" | -| iso_date | The date of the nightly or beta release (or None, if the version is a specific version). | None | -| rustfmt_version | The version of rustfmt. Either "nightly", "beta", or an exact version. Defaults to version if not specified. | None | -| edition | The rust edition to be used by default (2015 (default) or 2018) | None | -| dev_components | Whether to download the rustc-dev components (defaults to False). Requires version to be "nightly". | False | -| sha256s | A dict associating tool subdirectories to sha256 hashes. Defaults to None. | None | -| urls | A list of mirror urls containing the tools from the Rust-lang static file server. These must contain the '{}' used to substitute the tool being fetched (using .format). Defaults to ['https://static.rust-lang.org/dist/{}.tar.gz'] | ["https://static.rust-lang.org/dist/{}.tar.gz"] | - - - - -## rust_repository_set - -
-rust_repository_set(name, version, exec_triple, extra_target_triples, iso_date, rustfmt_version,
-                    edition, dev_components, sha256s, urls)
-
- -Assembles a remote repository for the given toolchain params, produces a proxy repository to contain the toolchain declaration, and registers the toolchains. - -N.B. A "proxy repository" is needed to allow for registering the toolchain (with constraints) without actually downloading the toolchain. - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name | The name of the generated repository | none | -| version | The version of the tool among "nightly", "beta', or an exact version. | none | -| exec_triple | The Rust-style target that this compiler runs on | none | -| extra_target_triples | Additional rust-style targets that this set of toolchains should support. Defaults to []. | [] | -| iso_date | The date of the tool. Defaults to None. | None | -| rustfmt_version | The version of rustfmt to be associated with the toolchain. Defaults to None. | None | -| edition | The rust edition to be used by default (2015 (if None) or 2018). | None | -| dev_components | Whether to download the rustc-dev components. Requires version to be "nightly". Defaults to False. | False | -| sha256s | A dict associating tool subdirectories to sha256 hashes. See [rust_repositories](#rust_repositories) for more details. | None | -| urls | A list of mirror urls containing the tools from the Rust-lang static file server. These must contain the '{}' used to substitute the tool being fetched (using .format). Defaults to ['https://static.rust-lang.org/dist/{}.tar.gz'] | ["https://static.rust-lang.org/dist/{}.tar.gz"] | - - - - -## rust_test_suite - -
-rust_test_suite(name, srcs, kwargs)
-
- -A rule for creating a test suite for a set of `rust_test` targets. - -This rule can be used for setting up typical rust [integration tests][it]. Given the following -directory structure: - -```text -[crate]/ - BUILD.bazel - src/ - lib.rs - main.rs - tests/ - integrated_test_a.rs - integrated_test_b.rs - integrated_test_c.rs - patterns/ - fibonacci_test.rs -``` - -The rule can be used to generate [rust_test](#rust_test) targets for each source file under `tests` -and a [test_suite][ts] which encapsulates all tests. - -```python -load("//rust:defs.bzl", "rust_binary", "rust_library", "rust_test_suite") - -rust_library( - name = "math_lib", - srcs = ["src/lib.rs"], -) - -rust_binary( - name = "math_bin", - srcs = ["src/main.rs"], -) - -rust_test_suite( - name = "integrated_tests_suite", - srcs = glob(["tests/**"]), - deps = [":math_lib"], -) -``` - -[it]: https://doc.rust-lang.org/rust-by-example/testing/integration_testing.html -[ts]: https://docs.bazel.build/versions/master/be/general.html#test_suite - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name | The name of the test_suite. | none | -| srcs | All test sources, typically glob(["tests/**/*.rs"]). | none | -| kwargs | Additional keyword arguments for the underyling [rust_test](#rust_test) targets. The tags argument is also passed to the generated test_suite target. | none | - - - - -## rust_wasm_bindgen_repositories - -
-rust_wasm_bindgen_repositories(register_default_toolchain)
-
- -Declare dependencies needed for [rust_wasm_bindgen](#rust_wasm_bindgen). - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| register_default_toolchain | If True, the default [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain) (@rules_rust//wasm_bindgen:default_wasm_bindgen_toolchain) is registered. This toolchain requires a set of dependencies that were generated using [cargo raze](https://github.com/google/cargo-raze). These will also be loaded. | True | - - diff --git a/docs/rust_analyzer.md b/docs/rust_analyzer.md deleted file mode 100644 index c632956bdb..0000000000 --- a/docs/rust_analyzer.md +++ /dev/null @@ -1,23 +0,0 @@ -# Rust rules -* [rust_analyzer](#rust_analyzer) -* [rust_analyzer_aspect](#rust_analyzer_aspect) - - - -## rust_analyzer - -
-rust_analyzer(name, targets)
-
- -Produces a rust-project.json for the given targets. Configure rust-analyzer to load the generated file via the linked projects mechanism. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| targets | List of all targets to be included in the index | List of labels | optional | [] | - - diff --git a/docs/rust_bindgen.md b/docs/rust_bindgen.md deleted file mode 100644 index c3a4543ed0..0000000000 --- a/docs/rust_bindgen.md +++ /dev/null @@ -1,89 +0,0 @@ -# Rust rules -* [rust_bindgen_library](#rust_bindgen_library) -* [rust_bindgen_repositories](#rust_bindgen_repositories) -* [rust_bindgen_toolchain](#rust_bindgen_toolchain) -* [rust_bindgen](#rust_bindgen) - - - -## rust_bindgen - -
-rust_bindgen(name, bindgen_flags, cc_lib, clang_flags, header)
-
- -Generates a rust source file from a cc_library and a header. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| bindgen_flags | Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. | List of strings | optional | [] | -| cc_lib | The cc_library that contains the .h file. This is used to find the transitive includes. | Label | optional | None | -| clang_flags | Flags to pass directly to the clang executable. | List of strings | optional | [] | -| header | The .h file to generate bindings for. | Label | optional | None | - - - - -## rust_bindgen_toolchain - -
-rust_bindgen_toolchain(name, bindgen, clang, libclang, libstdcxx, rustfmt)
-
- -The tools required for the `rust_bindgen` rule. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| bindgen | The label of a bindgen executable. | Label | optional | None | -| clang | The label of a clang executable. | Label | optional | None | -| libclang | A cc_library that provides bindgen's runtime dependency on libclang. | Label | optional | None | -| libstdcxx | A cc_library that satisfies libclang's libstdc++ dependency. | Label | optional | None | -| rustfmt | The label of a rustfmt executable. If this is provided, generated sources will be formatted. | Label | optional | None | - - - - -## rust_bindgen_library - -
-rust_bindgen_library(name, header, cc_lib, bindgen_flags, clang_flags, kwargs)
-
- -Generates a rust source file for `header`, and builds a rust_library. - -Arguments are the same as `rust_bindgen`, and `kwargs` are passed directly to rust_library. - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name | A unique name for this target. | none | -| header | The label of the .h file to generate bindings for. | none | -| cc_lib | The label of the cc_library that contains the .h file. This is used to find the transitive includes. | none | -| bindgen_flags | Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. | None | -| clang_flags | Flags to pass directly to the clang executable. | None | -| kwargs | Arguments to forward to the underlying rust_library rule. | none | - - - - -## rust_bindgen_repositories - -
-rust_bindgen_repositories()
-
- -Declare dependencies needed for bindgen. - - - diff --git a/docs/rust_clippy.md b/docs/rust_clippy.md deleted file mode 100644 index 8841f0c799..0000000000 --- a/docs/rust_clippy.md +++ /dev/null @@ -1,58 +0,0 @@ -# Rust rules -* [rust_clippy](#rust_clippy) -* [rust_clippy_aspect](#rust_clippy_aspect) - - - -## rust_clippy - -
-rust_clippy(name, deps)
-
- -Executes the clippy checker on a specific target. - -Similar to `rust_clippy_aspect`, but allows specifying a list of dependencies within the build system. - -For example, given the following example targets: - -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_library", "rust_test") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) - -rust_test( - name = "greeting_test", - srcs = ["tests/greeting.rs"], - deps = [":hello_lib"], -) -``` - -Rust clippy can be set as a build target with the following: - -```python -rust_clippy( - name = "hello_library_clippy", - testonly = True, - deps = [ - ":hello_lib", - ":greeting_test", - ], -) -``` - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| deps | - | List of labels | optional | [] | - - diff --git a/docs/rust_doc.md b/docs/rust_doc.md deleted file mode 100644 index 26ac5557fd..0000000000 --- a/docs/rust_doc.md +++ /dev/null @@ -1,117 +0,0 @@ -# Rust rules -* [rust_doc](#rust_doc) -* [rust_doc_test](#rust_doc_test) - - - -## rust_doc - -
-rust_doc(name, dep, html_after_content, html_before_content, html_in_header, markdown_css)
-
- -Generates code documentation. - -Example: - Suppose you have the following directory structure for a Rust library crate: - - ``` - [workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs - ``` - - To build [`rustdoc`][rustdoc] documentation for the `hello_lib` crate, define a `rust_doc` rule that depends on the the `hello_lib` `rust_library` target: - - [rustdoc]: https://doc.rust-lang.org/book/documentation.html - - ```python - package(default_visibility = ["//visibility:public"]) - - load("@rules_rust//rust:rust.bzl", "rust_library", "rust_doc") - - rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], - ) - - rust_doc( - name = "hello_lib_doc", - dep = ":hello_lib", - ) - ``` - - Running `bazel build //hello_lib:hello_lib_doc` will build a zip file containing the documentation for the `hello_lib` library crate generated by `rustdoc`. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| dep | The label of the target to generate code documentation for.

rust_doc can generate HTML code documentation for the source files of rust_library or rust_binary targets. | Label | required | | -| html_after_content | File to add in <body>, after content. | Label | optional | None | -| html_before_content | File to add in <body>, before content. | Label | optional | None | -| html_in_header | File to add to <head>. | Label | optional | None | -| markdown_css | CSS files to include via <link> in a rendered Markdown file. | List of labels | optional | [] | - - - - -## rust_doc_test - -
-rust_doc_test(name, dep)
-
- -Runs Rust documentation tests. - -Example: - -Suppose you have the following directory structure for a Rust library crate: - -```output -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - src/ - lib.rs -``` - -To run [documentation tests][doc-test] for the `hello_lib` crate, define a `rust_doc_test` target that depends on the `hello_lib` `rust_library` target: - -[doc-test]: https://doc.rust-lang.org/book/documentation.html#documentation-as-tests - -```python -package(default_visibility = ["//visibility:public"]) - -load("@rules_rust//rust:rust.bzl", "rust_library", "rust_doc_test") - -rust_library( - name = "hello_lib", - srcs = ["src/lib.rs"], -) - -rust_doc_test( - name = "hello_lib_doc_test", - dep = ":hello_lib", -) -``` - -Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation tests for the `hello_lib` library crate. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| dep | The label of the target to run documentation tests for.

rust_doc_test can run documentation tests for the source files of rust_library or rust_binary targets. | Label | required | | - - diff --git a/docs/rust_proto.md b/docs/rust_proto.md deleted file mode 100644 index 1a068fc9fd..0000000000 --- a/docs/rust_proto.md +++ /dev/null @@ -1,167 +0,0 @@ -# Rust rules -* [rust_grpc_library](#rust_grpc_library) -* [rust_proto_library](#rust_proto_library) -* [rust_proto_repositories](#rust_proto_repositories) -* [rust_proto_toolchain](#rust_proto_toolchain) - - - -## rust_grpc_library - -
-rust_grpc_library(name, deps, rust_deps)
-
- -Builds a Rust library crate from a set of `proto_library`s suitable for gRPC. - -Example: - -```python -load("//proto:proto.bzl", "rust_grpc_library") - -proto_library( - name = "my_proto", - srcs = ["my.proto"] -) - -rust_grpc_library( - name = "rust", - deps = [":my_proto"], -) - -rust_binary( - name = "my_service", - srcs = ["my_service.rs"], - deps = [":rust"], -) -``` - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| deps | List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding gRPC stubs. | List of labels | required | | -| rust_deps | The crates the generated library depends on. | List of labels | optional | [] | - - - - -## rust_proto_library - -
-rust_proto_library(name, deps, rust_deps)
-
- -Builds a Rust library crate from a set of `proto_library`s. - -Example: - -```python -load("@rules_rust//proto:proto.bzl", "rust_proto_library") - -proto_library( - name = "my_proto", - srcs = ["my.proto"] -) - -proto_rust_library( - name = "rust", - deps = [":my_proto"], -) - -rust_binary( - name = "my_proto_binary", - srcs = ["my_proto_binary.rs"], - deps = [":rust"], -) -``` - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| deps | List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding stubs. | List of labels | required | | -| rust_deps | The crates the generated library depends on. | List of labels | optional | [] | - - - - -## rust_proto_toolchain - -
-rust_proto_toolchain(name, edition, grpc_compile_deps, grpc_plugin, proto_compile_deps,
-                     proto_plugin, protoc)
-
- -Declares a Rust Proto toolchain for use. - -This is used to configure proto compilation and can be used to set different protobuf compiler plugin. - -Example: - -Suppose a new nicer gRPC plugin has came out. The new plugin can be used in Bazel by defining a new toolchain definition and declaration: - -```python -load('@rules_rust//proto:toolchain.bzl', 'rust_proto_toolchain') - -rust_proto_toolchain( - name="rust_proto_impl", - grpc_plugin="@rust_grpc//:grpc_plugin", - grpc_compile_deps=["@rust_grpc//:grpc_deps"], -) - -toolchain( - name="rust_proto", - exec_compatible_with = [ - "@platforms//cpu:cpuX", - ], - target_compatible_with = [ - "@platforms//cpu:cpuX", - ], - toolchain = ":rust_proto_impl", -) -``` - -Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the `--extra_toolchains` flag for Bazel, and it will be used. - -See @rules_rust//proto:BUILD for examples of defining the toolchain. - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| edition | The edition used by the generated rust source. | String | optional | "2015" | -| grpc_compile_deps | The crates the generated grpc libraries depends on. | List of labels | optional | [Label("//proto/raze:protobuf"), Label("//proto/raze:grpc"), Label("//proto/raze:tls_api"), Label("//proto/raze:tls_api_stub")] | -| grpc_plugin | The location of the Rust protobuf compiler plugin to generate rust gRPC stubs. | Label | optional | //proto:protoc_gen_rust_grpc | -| proto_compile_deps | The crates the generated protobuf libraries depends on. | List of labels | optional | [Label("//proto/raze:protobuf")] | -| proto_plugin | The location of the Rust protobuf compiler plugin used to generate rust sources. | Label | optional | //proto:protoc_gen_rust | -| protoc | The location of the protoc binary. It should be an executable target. | Label | optional | @com_google_protobuf//:protoc | - - - - -## rust_proto_repositories - -
-rust_proto_repositories(register_default_toolchain)
-
- -Declare dependencies needed for proto compilation. - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| register_default_toolchain | If True, the default [rust_proto_toolchain](#rust_proto_toolchain) (@rules_rust//proto:default-proto-toolchain) is registered. This toolchain requires a set of dependencies that were generated using [cargo raze](https://github.com/google/cargo-raze). These will also be loaded. | True | - - From 59c3dddbd255b7f5290e9d3dc4c0850f0682073a Mon Sep 17 00:00:00 2001 From: David Freese Date: Tue, 20 Apr 2021 14:13:06 -0700 Subject: [PATCH 2/3] spaces, not tabs Co-authored-by: Daniel Wagner-Hall --- .github/workflows/gen_docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/gen_docs.yaml b/.github/workflows/gen_docs.yaml index 1d769c3c90..72d20e1fcb 100644 --- a/.github/workflows/gen_docs.yaml +++ b/.github/workflows/gen_docs.yaml @@ -5,7 +5,7 @@ on: - main jobs: generate: - if: ${{ github.repository_owner == 'bazelbuild' }} + if: ${{ github.repository_owner == 'bazelbuild' }} name: Generate Docs runs-on: ubuntu-20.04 steps: From 24a3e3cee9b55519f4111f91f3436835bfe4c371 Mon Sep 17 00:00:00 2001 From: David Freese Date: Tue, 20 Apr 2021 14:28:16 -0700 Subject: [PATCH 3/3] update test_docs to build docs --- .bazelci/presubmit.yml | 8 ++++++++ docs/test_docs.sh | 14 +++----------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.bazelci/presubmit.yml b/.bazelci/presubmit.yml index 402801377f..4b22c882c8 100644 --- a/.bazelci/presubmit.yml +++ b/.bazelci/presubmit.yml @@ -78,6 +78,14 @@ tasks: working_directory: examples test_targets: - //... + docs_linux: + name: Docs + platform: ubuntu1804 + working_directory: docs + build_targets: + - //... + run_targets: + - "//:test_docs" clippy_examples: name: Clippy on Examples platform: ubuntu1804 diff --git a/docs/test_docs.sh b/docs/test_docs.sh index f6677b9e4f..4a98ca93e4 100755 --- a/docs/test_docs.sh +++ b/docs/test_docs.sh @@ -1,6 +1,6 @@ #!/bin/bash -set -euo pipefail +set -euxo pipefail if [[ -n "${BUILD_WORKSPACE_DIRECTORY:-}" ]]; then DOCS_WORKSPACE="${BUILD_WORKSPACE_DIRECTORY}" @@ -13,15 +13,7 @@ fi pushd "${DOCS_WORKSPACE}" &> /dev/null # It's important to clean the workspace so we don't end up with unintended # docs artifacts in the new commit. -bazel clean \ -&& bazel build //... \ -&& cp bazel-bin/*.md . \ -&& chmod 0644 *.md - -if [ -n "$(git status --porcelain)" ]; then - git status - echo '/docs is out of date. Please run `./docs/update_docs.sh` from the root of rules_rust and push the results' >&2 - exit 1 -fi +bazel clean +bazel build //... popd &> /dev/null