From d691eacc1bc64cca0fac9a8abc3be7b35d52037a Mon Sep 17 00:00:00 2001 From: Andre Brisco Date: Wed, 31 Mar 2021 10:19:08 -0700 Subject: [PATCH 1/6] Added test script for ensuring docs are up to date. --- .bazelci/presubmit.yml | 110 ++++++++++++++++++++--------------------- .gitignore | 3 ++ docs/BUILD.bazel | 10 ++++ docs/test_docs.sh | 26 ++++++++++ docs/update_docs.sh | 13 ++++- 5 files changed, 103 insertions(+), 59 deletions(-) create mode 100755 docs/test_docs.sh diff --git a/.bazelci/presubmit.yml b/.bazelci/presubmit.yml index c57d817954..4b22c882c8 100644 --- a/.bazelci/presubmit.yml +++ b/.bazelci/presubmit.yml @@ -1,12 +1,12 @@ --- default_linux_targets: &default_linux_targets -- "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245 -- "..." -- "@examples//..." -# TODO: Switch manual tag to platform constraint after bazel 4.0. -- "//test/versioned_dylib:versioned_dylib_test" -# Bindgen currently only has a working toolchain for 18.04 -- "-@examples//ffi/rust_calling_c/simple/..." + - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245 + - "..." + - "@examples//..." + # TODO: Switch manual tag to platform constraint after bazel 4.0. + - "//test/versioned_dylib:versioned_dylib_test" + # Bindgen currently only has a working toolchain for 18.04 + - "-@examples//ffi/rust_calling_c/simple/..." tasks: ubuntu1604: build_targets: *default_linux_targets @@ -25,51 +25,51 @@ tasks: test_targets: *default_linux_targets macos: osx_targets: &osx_targets - - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245 - - "..." - - "@examples//..." - # Skip tests for dylib support on osx, since we don't support it yet. - - "-@examples//ffi/rust_calling_c:matrix_dylib_test" - - "-@examples//ffi/rust_calling_c:matrix_dynamically_linked" - - "-@examples//ffi/rust_calling_c/simple/..." + - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245 + - "..." + - "@examples//..." + # Skip tests for dylib support on osx, since we don't support it yet. + - "-@examples//ffi/rust_calling_c:matrix_dylib_test" + - "-@examples//ffi/rust_calling_c:matrix_dynamically_linked" + - "-@examples//ffi/rust_calling_c/simple/..." build_targets: *osx_targets test_targets: *osx_targets rbe_ubuntu1604: test_targets: - - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245 - - "..." - - "//test/..." - - "@examples//..." - - "-//test/conflicting_deps:conflicting_deps_test" - # rust_doc_test is likely not fully sandboxed - - "-//test/chained_direct_deps:mod3_doc_test" - - "-@examples//fibonacci:fibonacci_doc_test" - - "-@examples//hello_lib:hello_lib_doc_test" - - "-//tools/runfiles:runfiles_doc_test" - - "-@examples//ffi/rust_calling_c/simple/..." - # See https://github.com/bazelbuild/bazel/issues/9987 - - "-@examples//ffi/rust_calling_c:matrix_dylib_test" + - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245 + - "..." + - "//test/..." + - "@examples//..." + - "-//test/conflicting_deps:conflicting_deps_test" + # rust_doc_test is likely not fully sandboxed + - "-//test/chained_direct_deps:mod3_doc_test" + - "-@examples//fibonacci:fibonacci_doc_test" + - "-@examples//hello_lib:hello_lib_doc_test" + - "-//tools/runfiles:runfiles_doc_test" + - "-@examples//ffi/rust_calling_c/simple/..." + # See https://github.com/bazelbuild/bazel/issues/9987 + - "-@examples//ffi/rust_calling_c:matrix_dylib_test" windows: build_flags: - - "--enable_runfiles" # this is not enabled by default on windows and is necessary for the cargo build scripts + - "--enable_runfiles" # this is not enabled by default on windows and is necessary for the cargo build scripts windows_targets: &windows_targets - - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245 - - "..." - - "-//bindgen/..." - - "-//test/load_arbitrary_tool/..." - - "-//test/test_env/..." - - "-//test/proto/..." - - "-//tools/rust_analyzer/..." - - "-//tools/runfiles/..." - - "-//test/rustfmt/..." - - "@examples//..." - - "-@examples//ffi/rust_calling_c:matrix_dylib_test" - - "-@examples//ffi/rust_calling_c:matrix_dynamically_linked" - - "-@examples//ffi/rust_calling_c/simple/..." - - "-@examples//hello_sys/..." - - "-@examples//complex_sys/..." - - "-@examples//proto/..." - - "-@examples//wasm/..." + - "--" # Allows negative patterns; hack for https://github.com/bazelbuild/continuous-integration/pull/245 + - "..." + - "-//bindgen/..." + - "-//test/load_arbitrary_tool/..." + - "-//test/test_env/..." + - "-//test/proto/..." + - "-//tools/rust_analyzer/..." + - "-//tools/runfiles/..." + - "-//test/rustfmt/..." + - "@examples//..." + - "-@examples//ffi/rust_calling_c:matrix_dylib_test" + - "-@examples//ffi/rust_calling_c:matrix_dynamically_linked" + - "-@examples//ffi/rust_calling_c/simple/..." + - "-@examples//hello_sys/..." + - "-@examples//complex_sys/..." + - "-@examples//proto/..." + - "-@examples//wasm/..." build_targets: *windows_targets test_targets: *windows_targets examples: @@ -77,33 +77,29 @@ tasks: platform: ubuntu1804 working_directory: examples test_targets: - - //... + - //... docs_linux: name: Docs platform: ubuntu1804 working_directory: docs build_targets: - - //... - docs_macos: - name: Docs - platform: macos - working_directory: docs - build_targets: - - //... + - //... + run_targets: + - "//:test_docs" clippy_examples: name: Clippy on Examples platform: ubuntu1804 working_directory: examples build_flags: - - "--aspects=@rules_rust//rust:rust.bzl%rust_clippy_aspect" - - "--output_groups=clippy_checks" + - "--aspects=@rules_rust//rust:rust.bzl%rust_clippy_aspect" + - "--output_groups=clippy_checks" build_targets: - - //... + - //... clippy_failure: name: Negative Clippy Tests platform: ubuntu1804 shell_commands: - - ./test/clippy/clippy_failure_test.sh + - ./test/clippy/clippy_failure_test.sh ubuntu2004_clang: name: Ubuntu 20.04 with Clang platform: ubuntu2004 diff --git a/.gitignore b/.gitignore index 38926597df..1c2a7774e7 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,6 @@ # vscode .vscode *.code-workspace + +# BazelCI +bazelci.py \ No newline at end of file diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index d526b95fd3..712587c1fb 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -119,3 +119,13 @@ stardoc( symbol_names = [symbol for k in PAGES.keys() for symbol in PAGES[k]], deps = [":all_docs"], ) + +sh_binary( + name = "update_docs", + srcs = ["update_docs.sh"], +) + +sh_binary( + name = "test_docs", + srcs = ["test_docs.sh"], +) diff --git a/docs/test_docs.sh b/docs/test_docs.sh new file mode 100755 index 0000000000..50c6652f79 --- /dev/null +++ b/docs/test_docs.sh @@ -0,0 +1,26 @@ +#!/bin/bash + +set -euo pipefail + +if [[ -n "${BUILD_WORKSPACE_DIRECTORY:-}" ]]; then + DOCS_WORKSPACE="${BUILD_WORKSPACE_DIRECTORY}" +else + # https://stackoverflow.com/a/246128/7768383 + DOCS_WORKSPACE="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" +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 + +popd &> /dev/null diff --git a/docs/update_docs.sh b/docs/update_docs.sh index 569cd8b201..d43d85ac6a 100755 --- a/docs/update_docs.sh +++ b/docs/update_docs.sh @@ -1,6 +1,15 @@ #!/bin/bash -pushd ${0%/*} +set -euo pipefail + +if [[ -n "${BUILD_WORKSPACE_DIRECTORY:-}" ]]; then + DOCS_WORKSPACE="${BUILD_WORKSPACE_DIRECTORY}" +else + # https://stackoverflow.com/a/246128/7768383 + DOCS_WORKSPACE="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" +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 \ @@ -9,5 +18,5 @@ bazel clean \ && chmod 0644 *.md \ && git add *.md \ && git commit -m "Regenerate documentation" -popd +popd &> /dev/null From 0738c569316df3e7be56b45d57730311f0390fc8 Mon Sep 17 00:00:00 2001 From: Andre Brisco Date: Wed, 31 Mar 2021 12:29:02 -0700 Subject: [PATCH 2/6] Fixed bug in doc attribute formatting. --- .gitignore | 2 +- rust/private/rust.bzl | 47 +++++++++++++++++++++++++++---------------- 2 files changed, 31 insertions(+), 18 deletions(-) diff --git a/.gitignore b/.gitignore index 1c2a7774e7..2f8bfb1f1d 100644 --- a/.gitignore +++ b/.gitignore @@ -23,4 +23,4 @@ *.code-workspace # BazelCI -bazelci.py \ No newline at end of file +bazelci.py diff --git a/rust/private/rust.bzl b/rust/private/rust.bzl index 92f3ee1add..22f571c84f 100644 --- a/rust/private/rust.bzl +++ b/rust/private/rust.bzl @@ -521,18 +521,31 @@ def _tidy(doc_string): Returns: str: A string optimized for stardoc rendering """ - return "\n".join([line.strip() for line in doc_string.splitlines()]) + lines = doc_string.splitlines() + if not lines: + return doc_string + + # Detect how much space prepends the first line and subtract that from all lines + space_count = len(lines[0]) - len(lines[0].lstrip()) + + # If there are no leading spaces, do not alter the docstring + if space_count == 0: + return doc_string + else: + # Remove the leading block of spaces from the current line + block = " " * space_count + return "\n".join([line.replace(block, "", 1).rstrip() for line in lines]) _common_attrs = { "aliases": attr.label_keyed_string_dict( - doc = _tidy(""" + doc = _tidy("""\ 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. """), ), "compile_data": attr.label_list( - doc = _tidy(""" + doc = _tidy("""\ List of files used by this rule at compile time. This attribute can be used to specify any data files that are embedded into @@ -543,7 +556,7 @@ _common_attrs = { allow_files = True, ), "crate_features": attr.string_list( - doc = _tidy(""" + doc = _tidy("""\ List of features to enable for this crate. Features are defined in the code using the `#[cfg(feature = "foo")]` @@ -552,7 +565,7 @@ _common_attrs = { """), ), "crate_name": attr.string( - doc = _tidy(""" + doc = _tidy("""\ Crate name to use for this target. This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. @@ -560,7 +573,7 @@ _common_attrs = { """), ), "crate_root": attr.label( - doc = _tidy(""" + doc = _tidy("""\ 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) @@ -569,7 +582,7 @@ _common_attrs = { allow_single_file = [".rs"], ), "data": attr.label_list( - doc = _tidy(""" + doc = _tidy("""\ List of files used by this rule at compile time and runtime. If including data at compile time with include_str!() and similar, @@ -579,7 +592,7 @@ _common_attrs = { allow_files = True, ), "deps": attr.label_list( - doc = _tidy(""" + doc = _tidy("""\ List of other libraries to be linked to this library target. These can be either other `rust_library` targets or `cc_library` targets if @@ -601,14 +614,14 @@ _common_attrs = { # This fails for remote execution, which needs cfg="exec", and there isn't anything like # `@local_config_platform//:exec` exposed. "proc_macro_deps": attr.label_list( - doc = _tidy(""" + doc = _tidy("""\ List of `rust_library` targets with kind `proc-macro` used to help build this library target. """), cfg = "exec", providers = [rust_common.crate_info], ), "rustc_env": attr.string_dict( - doc = _tidy(""" + doc = _tidy("""\ 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 @@ -619,7 +632,7 @@ _common_attrs = { """), ), "rustc_env_files": attr.label_list( - doc = _tidy(""" + doc = _tidy("""\ Files containing additional environment variables to set for rustc. These files should contain a single variable per line, of format @@ -638,7 +651,7 @@ _common_attrs = { # doc = "This name will also be used as the name of the crate built by this rule.", # `), "srcs": attr.label_list( - doc = _tidy(""" + doc = _tidy("""\ 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 @@ -666,7 +679,7 @@ _common_attrs = { _rust_test_attrs = { "crate": attr.label( mandatory = False, - doc = _tidy(""" + doc = _tidy("""\ Target inline tests declared in the given crate These tests are typically those that would be held out under @@ -675,7 +688,7 @@ _rust_test_attrs = { ), "env": attr.string_dict( mandatory = False, - doc = _tidy(""" + doc = _tidy("""\ 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. @@ -685,7 +698,7 @@ _rust_test_attrs = { executable = True, default = Label("//util/launcher:launcher"), cfg = "exec", - doc = _tidy(""" + doc = _tidy("""\ A launcher executable for loading environment and argument files passed in via the `env` attribute and ensuring the variables are set for the underlying test executable. """), @@ -831,7 +844,7 @@ rust_proc_macro = rule( _rust_binary_attrs = { "crate_type": attr.string( - doc = _tidy(""" + doc = _tidy("""\ 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 @@ -840,7 +853,7 @@ _rust_binary_attrs = { default = "bin", ), "linker_script": attr.label( - doc = _tidy(""" + doc = _tidy("""\ Link script to forward into linker via rustc options. """), cfg = "exec", From a9e7b15be29b342080279cb03561c6457e63d402 Mon Sep 17 00:00:00 2001 From: Andre Brisco Date: Wed, 31 Mar 2021 12:29:33 -0700 Subject: [PATCH 3/6] Regenerate documentation --- docs/cargo_build_script.md | 8 +- docs/defs.md | 239 ++++++++++++++++++----------------- docs/flatten.md | 247 +++++++++++++++++++------------------ 3 files changed, 258 insertions(+), 236 deletions(-) diff --git a/docs/cargo_build_script.md b/docs/cargo_build_script.md index a1f4ee0103..6df78c3e9a 100644 --- a/docs/cargo_build_script.md +++ b/docs/cargo_build_script.md @@ -6,7 +6,7 @@ ## cargo_build_script 
-cargo_build_script(name, crate_name, crate_features, version, deps, build_script_env, data, links,
+cargo_build_script(name, crate_features, version, deps, build_script_env, data, links, rustc_env,
                    kwargs)
@@ -73,14 +73,14 @@ The `hello_lib` target will be build with the flags and the environment variable | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| name | The target name for the underlying rule | none | -| crate_name | Name of the crate associated with this build script target. | "" | +| 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 defined by crate_name. | [] | +| 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 index 33986110f9..28979849ee 100644 --- a/docs/defs.md +++ b/docs/defs.md @@ -12,8 +12,9 @@ ## rust_benchmark 
-rust_benchmark(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-               out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, version)
+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. @@ -30,27 +31,27 @@ Suppose you have the following directory structure for a Rust project with a [workspace]/ WORKSPACE fibonacci/ -BUILD -src/ -lib.rs -benches/ -fibonacci_bench.rs + 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 + 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 } ``` @@ -65,7 +66,7 @@ use test::Bencher; #[bench] fn bench_fibonacci(b: &mut Bencher) { -b.iter(|| fibonacci::fibonacci(40)); + b.iter(|| fibonacci::fibonacci(40)); } ``` @@ -101,6 +102,7 @@ Run the benchmark test using: `bazel run //fibonacci:fibonacci_bench`. | 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 | [] | @@ -119,8 +121,8 @@ Run the benchmark test using: `bazel run //fibonacci:fibonacci_bench`. ## rust_binary 
-rust_binary(name, aliases, compile_data, crate_features, crate_root, crate_type, data, deps,
-            edition, linker_script, out_binary, out_dir_tar, proc_macro_deps, rustc_env,
+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)
@@ -134,31 +136,31 @@ library crate, `hello_lib`, and a binary crate, `hello_world` that uses the ```output [workspace]/ -WORKSPACE -hello_lib/ -BUILD -src/ -lib.rs -hello_world/ -BUILD -src/ -main.rs + WORKSPACE + hello_lib/ + BUILD + src/ + lib.rs + hello_world/ + BUILD + src/ + main.rs ``` `hello_lib/src/lib.rs`: ```rust pub struct Greeter { -greeting: String, + greeting: String, } impl Greeter { -pub fn new(greeting: &str) -> Greeter { -Greeter { greeting: greeting.to_string(), } -} + pub fn new(greeting: &str) -> Greeter { + Greeter { greeting: greeting.to_string(), } + } -pub fn greet(&self, thing: &str) { -println!("{} {}", &self.greeting, thing); -} + pub fn greet(&self, thing: &str) { + println!("{} {}", &self.greeting, thing); + } } ``` @@ -169,8 +171,8 @@ package(default_visibility = ["//visibility:public"]) load("@rules_rust//rust:rust.bzl", "rust_library") rust_library( -name = "hello_lib", -srcs = ["src/lib.rs"], + name = "hello_lib", + srcs = ["src/lib.rs"], ) ``` @@ -179,8 +181,8 @@ srcs = ["src/lib.rs"], extern crate hello_lib; fn main() { -let hello = hello_lib::Greeter::new("Hello"); -hello.greet("world"); + let hello = hello_lib::Greeter::new("Hello"); + hello.greet("world"); } ``` @@ -189,9 +191,9 @@ hello.greet("world"); load("@rules_rust//rust:rust.bzl", "rust_binary") rust_binary( -name = "hello_world", -srcs = ["src/main.rs"], -deps = ["//hello_lib"], + name = "hello_world", + srcs = ["src/main.rs"], + deps = ["//hello_lib"], ) ``` @@ -216,6 +218,7 @@ Hello world | 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 | [] | @@ -237,8 +240,9 @@ Hello world ## rust_library 
-rust_library(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-             out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, version)
+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. @@ -249,28 +253,28 @@ Suppose you have the following directory structure for a simple Rust library cra ```output [workspace]/ -WORKSPACE -hello_lib/ -BUILD -src/ -greeter.rs -lib.rs + WORKSPACE + hello_lib/ + BUILD + src/ + greeter.rs + lib.rs ``` `hello_lib/src/greeter.rs`: ```rust pub struct Greeter { -greeting: String, + greeting: String, } impl Greeter { -pub fn new(greeting: &str) -> Greeter { -Greeter { greeting: greeting.to_string(), } -} + pub fn new(greeting: &str) -> Greeter { + Greeter { greeting: greeting.to_string(), } + } -pub fn greet(&self, thing: &str) { -println!("{} {}", &self.greeting, thing); -} + pub fn greet(&self, thing: &str) { + println!("{} {}", &self.greeting, thing); + } } ``` @@ -287,11 +291,11 @@ 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", -], + name = "hello_lib", + srcs = [ + "src/greeter.rs", + "src/lib.rs", + ], ) ``` @@ -314,6 +318,7 @@ INFO: Elapsed time: 1.245s, Critical Path: 1.01s | 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 | [] | @@ -332,8 +337,9 @@ INFO: Elapsed time: 1.245s, Critical Path: 1.01s ## rust_proc_macro 
-rust_proc_macro(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-                out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, version)
+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. @@ -348,6 +354,7 @@ Builds a Rust proc-macro crate. | 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 | [] | @@ -366,9 +373,9 @@ Builds a Rust proc-macro crate. ## rust_shared_library 
-rust_shared_library(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-                    out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-                    version)
+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. @@ -391,6 +398,7 @@ When building the whole binary in Bazel, use `rust_library` instead. | 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 | [] | @@ -409,9 +417,9 @@ When building the whole binary in Bazel, use `rust_library` instead. ## rust_static_library 
-rust_static_library(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-                    out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-                    version)
+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. @@ -434,6 +442,7 @@ When building the whole binary in Bazel, use `rust_library` instead. | 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 | [] | @@ -452,8 +461,9 @@ When building the whole binary in Bazel, use `rust_library` instead. ## rust_test 
-rust_test(name, aliases, compile_data, crate, crate_features, crate_root, data, deps, edition, env,
-          out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, version)
+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. @@ -464,38 +474,38 @@ Suppose you have the following directory structure for a Rust library crate ```output [workspace]/ -WORKSPACE -hello_lib/ -BUILD -src/ -lib.rs + WORKSPACE + hello_lib/ + BUILD + src/ + lib.rs ``` `hello_lib/src/lib.rs`: ```rust pub struct Greeter { -greeting: String, + greeting: String, } impl Greeter { -pub fn new(greeting: &str) -> Greeter { -Greeter { greeting: greeting.to_string(), } -} + pub fn new(greeting: &str) -> Greeter { + Greeter { greeting: greeting.to_string(), } + } -pub fn greet(&self, thing: &str) { -println!("{} {}", &self.greeting, thing); -} + pub fn greet(&self, thing: &str) { + println!("{} {}", &self.greeting, thing); + } } #[cfg(test)] mod test { -use super::Greeter; + use super::Greeter; -#[test] -fn test_greeting() { -let hello = Greeter::new("Hi"); -assert_eq!("Hi Rust", hello.greet("Rust")); -} + #[test] + fn test_greeting() { + let hello = Greeter::new("Hi"); + assert_eq!("Hi Rust", hello.greet("Rust")); + } } ``` @@ -508,13 +518,13 @@ package(default_visibility = ["//visibility:public"]) load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") rust_library( -name = "hello_lib", -srcs = ["src/lib.rs"], + name = "hello_lib", + srcs = ["src/lib.rs"], ) rust_test( -name = "hello_lib_test", -deps = [":hello_lib"], + name = "hello_lib_test", + deps = [":hello_lib"], ) ``` @@ -524,10 +534,10 @@ To run a crate or lib with the `#[cfg(test)]` configuration, handling inline ```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"], + name = "hello_lib_test", + crate = ":hello_lib", + # You may add other deps that are specific to the test configuration + deps = ["//some/dev/dep"], ) ``` @@ -539,13 +549,13 @@ Integration tests that live in the [`tests` directory][int-tests], they are ```output [workspace]/ -WORKSPACE -hello_lib/ -BUILD -src/ -lib.rs -tests/ -greeting.rs + WORKSPACE + hello_lib/ + BUILD + src/ + lib.rs + tests/ + greeting.rs ``` `hello_lib/tests/greeting.rs`: @@ -556,8 +566,8 @@ use hello_lib; #[test] fn test_greeting() { -let hello = greeter::Greeter::new("Hello"); -assert_eq!("Hello world", hello.greeting("world")); + let hello = greeter::Greeter::new("Hello"); + assert_eq!("Hello world", hello.greeting("world")); } ``` @@ -571,14 +581,14 @@ package(default_visibility = ["//visibility:public"]) load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") rust_library( -name = "hello_lib", -srcs = ["src/lib.rs"], + name = "hello_lib", + srcs = ["src/lib.rs"], ) rust_test( -name = "greeting_test", -srcs = ["tests/greeting.rs"], -deps = [":hello_lib"], + name = "greeting_test", + srcs = ["tests/greeting.rs"], + deps = [":hello_lib"], ) ``` @@ -594,6 +604,7 @@ Run the test with `bazel build //hello_lib:hello_lib_test`. | 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 | [] | diff --git a/docs/flatten.md b/docs/flatten.md index b8708979d9..f3c75963cc 100644 --- a/docs/flatten.md +++ b/docs/flatten.md @@ -56,8 +56,9 @@ Produces a rust-project.json for the given targets. Configure rust-analyzer to l ## rust_benchmark 
-rust_benchmark(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-               out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, version)
+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. @@ -74,27 +75,27 @@ Suppose you have the following directory structure for a Rust project with a [workspace]/ WORKSPACE fibonacci/ -BUILD -src/ -lib.rs -benches/ -fibonacci_bench.rs + 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 + 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 } ``` @@ -109,7 +110,7 @@ use test::Bencher; #[bench] fn bench_fibonacci(b: &mut Bencher) { -b.iter(|| fibonacci::fibonacci(40)); + b.iter(|| fibonacci::fibonacci(40)); } ``` @@ -145,6 +146,7 @@ Run the benchmark test using: `bazel run //fibonacci:fibonacci_bench`. | 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 | [] | @@ -163,8 +165,8 @@ Run the benchmark test using: `bazel run //fibonacci:fibonacci_bench`. ## rust_binary 
-rust_binary(name, aliases, compile_data, crate_features, crate_root, crate_type, data, deps,
-            edition, linker_script, out_binary, out_dir_tar, proc_macro_deps, rustc_env,
+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)
@@ -178,31 +180,31 @@ library crate, `hello_lib`, and a binary crate, `hello_world` that uses the ```output [workspace]/ -WORKSPACE -hello_lib/ -BUILD -src/ -lib.rs -hello_world/ -BUILD -src/ -main.rs + WORKSPACE + hello_lib/ + BUILD + src/ + lib.rs + hello_world/ + BUILD + src/ + main.rs ``` `hello_lib/src/lib.rs`: ```rust pub struct Greeter { -greeting: String, + greeting: String, } impl Greeter { -pub fn new(greeting: &str) -> Greeter { -Greeter { greeting: greeting.to_string(), } -} + pub fn new(greeting: &str) -> Greeter { + Greeter { greeting: greeting.to_string(), } + } -pub fn greet(&self, thing: &str) { -println!("{} {}", &self.greeting, thing); -} + pub fn greet(&self, thing: &str) { + println!("{} {}", &self.greeting, thing); + } } ``` @@ -213,8 +215,8 @@ package(default_visibility = ["//visibility:public"]) load("@rules_rust//rust:rust.bzl", "rust_library") rust_library( -name = "hello_lib", -srcs = ["src/lib.rs"], + name = "hello_lib", + srcs = ["src/lib.rs"], ) ``` @@ -223,8 +225,8 @@ srcs = ["src/lib.rs"], extern crate hello_lib; fn main() { -let hello = hello_lib::Greeter::new("Hello"); -hello.greet("world"); + let hello = hello_lib::Greeter::new("Hello"); + hello.greet("world"); } ``` @@ -233,9 +235,9 @@ hello.greet("world"); load("@rules_rust//rust:rust.bzl", "rust_binary") rust_binary( -name = "hello_world", -srcs = ["src/main.rs"], -deps = ["//hello_lib"], + name = "hello_world", + srcs = ["src/main.rs"], + deps = ["//hello_lib"], ) ``` @@ -260,6 +262,7 @@ Hello world | 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 | [] | @@ -537,8 +540,9 @@ rust_binary( ## rust_library 
-rust_library(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-             out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, version)
+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. @@ -549,28 +553,28 @@ Suppose you have the following directory structure for a simple Rust library cra ```output [workspace]/ -WORKSPACE -hello_lib/ -BUILD -src/ -greeter.rs -lib.rs + WORKSPACE + hello_lib/ + BUILD + src/ + greeter.rs + lib.rs ``` `hello_lib/src/greeter.rs`: ```rust pub struct Greeter { -greeting: String, + greeting: String, } impl Greeter { -pub fn new(greeting: &str) -> Greeter { -Greeter { greeting: greeting.to_string(), } -} + pub fn new(greeting: &str) -> Greeter { + Greeter { greeting: greeting.to_string(), } + } -pub fn greet(&self, thing: &str) { -println!("{} {}", &self.greeting, thing); -} + pub fn greet(&self, thing: &str) { + println!("{} {}", &self.greeting, thing); + } } ``` @@ -587,11 +591,11 @@ 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", -], + name = "hello_lib", + srcs = [ + "src/greeter.rs", + "src/lib.rs", + ], ) ``` @@ -614,6 +618,7 @@ INFO: Elapsed time: 1.245s, Critical Path: 1.01s | 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 | [] | @@ -632,8 +637,9 @@ INFO: Elapsed time: 1.245s, Critical Path: 1.01s ## rust_proc_macro 
-rust_proc_macro(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-                out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, version)
+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. @@ -648,6 +654,7 @@ Builds a Rust proc-macro crate. | 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 | [] | @@ -764,9 +771,9 @@ See @rules_rust//proto:BUILD for examples of defining the toolchain. ## rust_shared_library 
-rust_shared_library(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-                    out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-                    version)
+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. @@ -789,6 +796,7 @@ When building the whole binary in Bazel, use `rust_library` instead. | 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 | [] | @@ -807,9 +815,9 @@ When building the whole binary in Bazel, use `rust_library` instead. ## rust_static_library 
-rust_static_library(name, aliases, compile_data, crate_features, crate_root, data, deps, edition,
-                    out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs,
-                    version)
+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. @@ -832,6 +840,7 @@ When building the whole binary in Bazel, use `rust_library` instead. | 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 | [] | @@ -850,8 +859,9 @@ When building the whole binary in Bazel, use `rust_library` instead. ## rust_test 
-rust_test(name, aliases, compile_data, crate, crate_features, crate_root, data, deps, edition, env,
-          out_dir_tar, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, srcs, version)
+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. @@ -862,38 +872,38 @@ Suppose you have the following directory structure for a Rust library crate ```output [workspace]/ -WORKSPACE -hello_lib/ -BUILD -src/ -lib.rs + WORKSPACE + hello_lib/ + BUILD + src/ + lib.rs ``` `hello_lib/src/lib.rs`: ```rust pub struct Greeter { -greeting: String, + greeting: String, } impl Greeter { -pub fn new(greeting: &str) -> Greeter { -Greeter { greeting: greeting.to_string(), } -} + pub fn new(greeting: &str) -> Greeter { + Greeter { greeting: greeting.to_string(), } + } -pub fn greet(&self, thing: &str) { -println!("{} {}", &self.greeting, thing); -} + pub fn greet(&self, thing: &str) { + println!("{} {}", &self.greeting, thing); + } } #[cfg(test)] mod test { -use super::Greeter; + use super::Greeter; -#[test] -fn test_greeting() { -let hello = Greeter::new("Hi"); -assert_eq!("Hi Rust", hello.greet("Rust")); -} + #[test] + fn test_greeting() { + let hello = Greeter::new("Hi"); + assert_eq!("Hi Rust", hello.greet("Rust")); + } } ``` @@ -906,13 +916,13 @@ package(default_visibility = ["//visibility:public"]) load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") rust_library( -name = "hello_lib", -srcs = ["src/lib.rs"], + name = "hello_lib", + srcs = ["src/lib.rs"], ) rust_test( -name = "hello_lib_test", -deps = [":hello_lib"], + name = "hello_lib_test", + deps = [":hello_lib"], ) ``` @@ -922,10 +932,10 @@ To run a crate or lib with the `#[cfg(test)]` configuration, handling inline ```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"], + name = "hello_lib_test", + crate = ":hello_lib", + # You may add other deps that are specific to the test configuration + deps = ["//some/dev/dep"], ) ``` @@ -937,13 +947,13 @@ Integration tests that live in the [`tests` directory][int-tests], they are ```output [workspace]/ -WORKSPACE -hello_lib/ -BUILD -src/ -lib.rs -tests/ -greeting.rs + WORKSPACE + hello_lib/ + BUILD + src/ + lib.rs + tests/ + greeting.rs ``` `hello_lib/tests/greeting.rs`: @@ -954,8 +964,8 @@ use hello_lib; #[test] fn test_greeting() { -let hello = greeter::Greeter::new("Hello"); -assert_eq!("Hello world", hello.greeting("world")); + let hello = greeter::Greeter::new("Hello"); + assert_eq!("Hello world", hello.greeting("world")); } ``` @@ -969,14 +979,14 @@ package(default_visibility = ["//visibility:public"]) load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") rust_library( -name = "hello_lib", -srcs = ["src/lib.rs"], + name = "hello_lib", + srcs = ["src/lib.rs"], ) rust_test( -name = "greeting_test", -srcs = ["tests/greeting.rs"], -deps = [":hello_lib"], + name = "greeting_test", + srcs = ["tests/greeting.rs"], + deps = [":hello_lib"], ) ``` @@ -992,6 +1002,7 @@ Run the test with `bazel build //hello_lib:hello_lib_test`. | 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 | [] | @@ -1230,7 +1241,7 @@ For additional information, see the [Bazel toolchains documentation][toolchains] ## cargo_build_script 
-cargo_build_script(name, crate_name, crate_features, version, deps, build_script_env, data, links,
+cargo_build_script(name, crate_features, version, deps, build_script_env, data, links, rustc_env,
                    kwargs)
@@ -1297,14 +1308,14 @@ The `hello_lib` target will be build with the flags and the environment variable | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| name | The target name for the underlying rule | none | -| crate_name | Name of the crate associated with this build script target. | "" | +| 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 defined by crate_name. | [] | +| 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 | From 6803fc7cbc0255ab401e8747ad0b8a046a32d53e Mon Sep 17 00:00:00 2001 From: Andre Brisco Date: Wed, 7 Apr 2021 07:45:16 -0700 Subject: [PATCH 4/6] `_tidy` now ignores empty first lines --- docs/defs.md | 1 + docs/flatten.md | 1 + rust/private/rust.bzl | 7 ++++++- 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/defs.md b/docs/defs.md index 28979849ee..d1f77cadd1 100644 --- a/docs/defs.md +++ b/docs/defs.md @@ -245,6 +245,7 @@ rust_library(name, version) + Builds a Rust library crate. Example: diff --git a/docs/flatten.md b/docs/flatten.md index f3c75963cc..1b0b9afbfe 100644 --- a/docs/flatten.md +++ b/docs/flatten.md @@ -545,6 +545,7 @@ rust_library(name, version) + Builds a Rust library crate. Example: diff --git a/rust/private/rust.bzl b/rust/private/rust.bzl index 22f571c84f..0101c707bf 100644 --- a/rust/private/rust.bzl +++ b/rust/private/rust.bzl @@ -525,8 +525,13 @@ def _tidy(doc_string): if not lines: return doc_string + # If the first line is empty, use the second line + first_line = lines[0] + if not first_line: + first_line = lines[1] + # Detect how much space prepends the first line and subtract that from all lines - space_count = len(lines[0]) - len(lines[0].lstrip()) + space_count = len(first_line) - len(first_line.lstrip()) # If there are no leading spaces, do not alter the docstring if space_count == 0: From ac2764be5e356a0792b2cbb272aacb3dcae538b4 Mon Sep 17 00:00:00 2001 From: Andre Brisco Date: Wed, 7 Apr 2021 07:48:48 -0700 Subject: [PATCH 5/6] Updated comment --- docs/test_docs.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/test_docs.sh b/docs/test_docs.sh index 50c6652f79..f6677b9e4f 100755 --- a/docs/test_docs.sh +++ b/docs/test_docs.sh @@ -5,7 +5,8 @@ set -euo pipefail if [[ -n "${BUILD_WORKSPACE_DIRECTORY:-}" ]]; then DOCS_WORKSPACE="${BUILD_WORKSPACE_DIRECTORY}" else - # https://stackoverflow.com/a/246128/7768383 + # Get the directory of the current script when not running under + # Bazel (as indicated by the lack of BUILD_WORKSPACE_DIRECTORY). DOCS_WORKSPACE="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" fi From 630fc3510d89c2d19bb7df55e880df395ca5663d Mon Sep 17 00:00:00 2001 From: Andre Brisco Date: Wed, 7 Apr 2021 08:42:04 -0700 Subject: [PATCH 6/6] Regenerate documentation --- docs/defs.md | 1 - docs/flatten.md | 1 - 2 files changed, 2 deletions(-) diff --git a/docs/defs.md b/docs/defs.md index d1f77cadd1..28979849ee 100644 --- a/docs/defs.md +++ b/docs/defs.md @@ -245,7 +245,6 @@ rust_library(name, version) - Builds a Rust library crate. Example: diff --git a/docs/flatten.md b/docs/flatten.md index 1b0b9afbfe..f3c75963cc 100644 --- a/docs/flatten.md +++ b/docs/flatten.md @@ -545,7 +545,6 @@ rust_library(name, version) - Builds a Rust library crate. Example: