Docs: Rewrite Bazel pages to clarify intended user PiperOrigin-RevId: 359812571
diff --git a/site/docs/android-instrumentation-test.md b/site/docs/android-instrumentation-test.md index dd65f54..0bf5c4a 100644 --- a/site/docs/android-instrumentation-test.md +++ b/site/docs/android-instrumentation-test.md
@@ -213,9 +213,9 @@ ## Maven dependencies -For managing dependencies on Maven artifacts from repositories like [Google +For managing dependencies on Maven artifacts from repositories, such as [Google Maven](https://maven.google.com) or [Maven Central](https://central.maven.org), -we recommend using a Maven resolver like +you should use a Maven resolver, such as [rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external). The rest of this page shows how to use `rules_jvm_external` to @@ -267,8 +267,8 @@ bazel query 'filter("x86_qemu2$", kind(android_device, @android_test_support//tools/android/emulated_devices/...:*))' ``` -Bazel currently supports x86-based emulators only. For better performance, we -also recommend using `QEMU2` `android_device` targets instead of `QEMU` ones. +Bazel currently supports x86-based emulators only. For better performance, use +`QEMU2` `android_device` targets instead of `QEMU` ones. ## Running tests
diff --git a/site/docs/android-ndk.md b/site/docs/android-ndk.md index abdf8a9..c7baa2a 100644 --- a/site/docs/android-ndk.md +++ b/site/docs/android-ndk.md
@@ -106,7 +106,7 @@ This example is available in the [Bazel examples repository](https://github.com/bazelbuild/examples/tree/master/android/ndk). -In the `BUILD.bazel` file, we define three targets with the `android_binary`, +In the `BUILD.bazel` file, three targets are defined with the `android_binary`, `android_library` and `cc_library` rules. The `android_binary` top-level target builds the APK. @@ -376,12 +376,12 @@ --host_crosstool_top=@bazel_tools//tools/cpp:toolchain ``` -Here, we specify that top-level `cc_library` and `cc_binary` targets are built +In this example, the top-level `cc_library` and `cc_binary` targets are built using the NDK toolchain. However, this causes Bazel's own host tools to be built with the NDK toolchain (and thus for Android), because the host toolchain is -copied from the target toolchain. To work around this, we specify the value of -`--host_crosstool_top` to be `@bazel_tools//tools/cpp:toolchain` to explicitly -set the host's C++ toolchain. +copied from the target toolchain. To work around this, specify the value of +`--host_crosstool_top` to be `@bazel_tools//tools/cpp:toolchain` to +explicitly set the host's C++ toolchain. With this approach, the entire build tree is affected.
diff --git a/site/docs/aquery.html b/site/docs/aquery.html index 02294fd..662f99e 100644 --- a/site/docs/aquery.html +++ b/site/docs/aquery.html
@@ -12,7 +12,7 @@ </p> <p> - <code>aquery</code> is useful when we are interested in the properties of the Actions/Artifacts + <code>aquery</code> is useful when you are interested in the properties of the Actions/Artifacts generated from the Configured Target Graph. For example, the actual commands run and their inputs/outputs/mnemonics. </p> @@ -305,7 +305,7 @@ <p><code class='flag'>--before, --after</code>: The aquery output files to be compared</p> <p> <code class='flag'>--input_type=(proto|text_proto), default=proto</code>: the format of the input - files. We currently support <code>proto</code> and <code>textproto</code> aquery output. + files. Support is provided for <code>proto</code> and <code>textproto</code> aquery output. </p> <p> <code class='flag'>--attrs=(cmdline|inputs), default=cmdline</code>: the attributes of actions @@ -382,7 +382,7 @@ <a href="https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/actions/Actions.java;l=241;drc=003b8734036a07b496012730964ac220f486b61f">simply considered as one</a> and only executed once. However, aquery operates on the pre-execution, post-analysis action graph, and hence treats these like separate actions whose output Artifacts have the exact same <code>execPath</code>. As a result, - we'll have equivalent Artifacts appearing duplicated. + equivalent Artifacts appear duplicated. </p> <p> The list of aquery issues/planned features can be found on
diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md index 240da27..6161974 100644 --- a/site/docs/backward-compatibility.md +++ b/site/docs/backward-compatibility.md
@@ -24,10 +24,9 @@ 1. Every breaking change is guarded with an `--incompatible_*` flag. 1. Newly introduced incompatible flags default to off. -1. For every `--incompatible_*` flag we have a GitHub issue that explains +1. For every `--incompatible_*` flag, there is a GitHub issue that explains the change in behavior and provides a migration recipe. 1. The migration window is at least one release long and is set by the author of the incompatible change. -1. We announce what set of flags we intend to flip with the next release one release in advance. 1. APIs and behavior guarded by an `--experimental_*` flag can change at any time. 1. Users should never run their production builds with `--experimental_*` or `--incompatible_*` flags. @@ -41,8 +40,9 @@ ## What is stable functionality? -In general, if an API or a behavior is available in Bazel without -`--experimental_...` flag, we consider it a stable, supported feature. +In general, APIs or behaviors without `--experimental_...` flags are considered +stable, supported features in Bazel. + This includes: * Starlark language and APIs @@ -52,20 +52,20 @@ ## Incompatible changes and migration recipes -When we introduce an incompatible change, we try to make it easier for Bazel -users to update their code. We do this by means of _migration windows_ and -_migration recipes_. +When a release contains an incompatible change, the Bazel team provides +_migration windows_ and _migration recipes_ to make it easier for Bazel users +to update their code. Migration window is one or more release of Bazel during which a migration from old functionality to new functionality is possible, according to a migration recipe. -During the migration window, both the old functionality and the new functionality -are available in the Bazel release. For every incompatible change, we provide -a _migration recipe_ that allows updating the user code (`BUILD` and `.bzl` files, -as well as any Bazel usage in scripts, usage of Bazel API and so on) in such a -way that **it works simultaneously without any flags with old and new -functionality**. +During the migration window, both the old and new functionality +are available in the Bazel release. For every incompatible change, a +_migration recipe_ is provided that allows updating the user code +(`BUILD` and `.bzl` files, as well as any Bazel usage in scripts, +usage of Bazel API, and so on) in such a way that **it works simultaneously +without any flags with old and new functionality**. In other words, during a migration window for an incompatible change `foo`:
diff --git a/site/docs/bazel-and-cpp.md b/site/docs/bazel-and-cpp.md index 2f3330d6..11ce1e5 100644 --- a/site/docs/bazel-and-cpp.md +++ b/site/docs/bazel-and-cpp.md
@@ -32,8 +32,8 @@ * Each BUILD file should contain one [`cc_library`](be/c-cpp.html#cc_library) rule target per compilation unit in the directory. -* We recommend that you granularize your C++ libraries as much as possible to - maximize incrementality and parallelize the build. +* You should granularize your C++ libraries as much as + possible to maximize incrementality and parallelize the build. * If there is a single source file in `srcs`, name the library the same as that C++ file's name. This library should contain C++ file(s), any matching
diff --git a/site/docs/build-javascript.md b/site/docs/build-javascript.md index 012cbda..f5e504c 100644 --- a/site/docs/build-javascript.md +++ b/site/docs/build-javascript.md
@@ -136,8 +136,8 @@ ``` then add scripts to your `package.json` that run Buildifier. -We've selected a set of enabled warnings here, you could add and remove from -this list. +Here is a set of enabled warnings you could add and remove from +this list: ```json "scripts": { @@ -177,8 +177,8 @@ **Tip:** You can try out the `ts_library` rule by running bazel build src in the [sample project](https://github.com/alexeagle/angular-bazel-example/wiki). -**Note:** We recommend standardizing your TypeScript settings into a single -`tsconfig.json` file or as few `tsconfig.json` files as possible. +**Recommendation:** Standardize your TypeScript settings into +a single `tsconfig.json` file or as few `tsconfig.json` files as possible. Note the following:
diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html index ddb99fc..6bc3efc 100644 --- a/site/docs/build-ref.html +++ b/site/docs/build-ref.html
@@ -316,7 +316,7 @@ </p> <p>While it is common to use <code>/</code> in the name of a file - target, we recommend that you avoid the use of <code>/</code> in the + target, it is recommended that you avoid the use of <code>/</code> in the names of rules. Especially when the shorthand form of a label is used, it may confuse the reader. The label <code>//foo/bar/wiz</code> is always a shorthand @@ -436,8 +436,8 @@ <p> The previous section described packages, targets and labels, and the - build dependency graph abstractly. In this section, we'll look at - the concrete syntax used to define a package. + build dependency graph abstractly. This section describes the + concrete syntax used to define a package. </p> <p> @@ -608,7 +608,7 @@ <code>B</code> if <code>B</code> is needed by <code>A</code> at build or execution time. The <i>depends upon</i> relation induces a <a href="https://en.wikipedia.org/wiki/Directed_acyclic_graph">Directed - Acyclic Graph</a> (DAG) over targets, and we call this a + Acyclic Graph</a> (DAG) over targets, and it is called a <em>dependency graph</em>. A target's <em>direct</em> dependencies are those other targets @@ -646,7 +646,7 @@ For correct builds, the graph of actual dependencies <i>A</i> must be a subgraph of the graph of declared dependencies <i>D</i>. That is, every pair of directly-connected nodes <code>x --> y</code> - in <i>A</i> must also be directly connected in <i>D</i>. We say + in <i>A</i> must also be directly connected in <i>D</i>. It can be said that <i>D</i> is an <em>overapproximation</em> of <i>A</i>. </p> @@ -893,8 +893,8 @@ <p>A build target might need some data files to run correctly. These data files aren't source code: they don't affect how the target is built. For example, a unit test might compare a function's output - to the contents of a file. When we build the unit test, we - don't need the file; but we do need it when we run the test. The + to the contents of a file. When you build the unit test you + don't need the file, but you do need it when you run the test. The same applies to tools that are launched during execution. <p>The build system runs tests in an isolated directory where only files
diff --git a/site/docs/cc-toolchain-config-reference.md b/site/docs/cc-toolchain-config-reference.md index 2481f90..c6b6078 100644 --- a/site/docs/cc-toolchain-config-reference.md +++ b/site/docs/cc-toolchain-config-reference.md
@@ -416,7 +416,7 @@ The last two attributes are redundant against the corresponding attributes on features and are included because some Bazel actions require certain flags or -environment variables and we want to avoid unnecessary `action_config`+`feature` +environment variables and the goal is to avoid unnecessary `action_config`+`feature` pairs. Typically, sharing a single feature across multiple `action_config`s is preferred. @@ -460,7 +460,7 @@ by iterating through the `tools` attribute on an `action_config` until a tool with a `with_feature` set matching the feature configuration is found (see [Feature relationships](#feature-relationships) earlier on this page -for more information). We recommend that you end your tool lists with a default +for more information). You should end your tool lists with a default tool that corresponds to an empty feature configuration. ### Example usage
diff --git a/site/docs/configurable-attributes.md b/site/docs/configurable-attributes.md index 275fbb8a..def638f 100644 --- a/site/docs/configurable-attributes.md +++ b/site/docs/configurable-attributes.md
@@ -332,7 +332,7 @@ allowing those `config_setting`s to match in `select()` expressions. For example, in order to set the `srcs` attribute of `my_rocks` to `calcite.sh`, -we can simply run +you can simply run ```sh bazel build //my_app:my_rocks --platforms=//myapp:marble_platform @@ -773,7 +773,7 @@ ERROR: error loading package 'myapp': Package 'myapp' contains errors. ``` -Building succeeds when we comment out `sad_macro`: +Building succeeds when you comment out `sad_macro`: ```sh # Comment out sad_macro so it doesn't mess up the build.