Docs: Rewrite Bazel pages to clarify intended user, part 5
PiperOrigin-RevId: 362427806
diff --git a/site/docs/test-encyclopedia.html b/site/docs/test-encyclopedia.html
index 250a3a9..3eda209 100644
--- a/site/docs/test-encyclopedia.html
+++ b/site/docs/test-encyclopedia.html
@@ -30,10 +30,10 @@
for and expected behavior of Bazel tests. It will also impose requirements on
the test runner and the build system.
-Our intent is to help test authors avoid relying on unspecified
-behavior, and thus give the testing infrastructure more freedom to make
-implementation changes. We will also take the opportunity to tighten up some
-holes which currently allow many tests to pass despite not being
+The test environment specification helps test authors avoid relying on
+unspecified behavior, and thus gives the testing infrastructure more freedom
+to make implementation changes. The specification tightens up some
+holes that currently allow many tests to pass despite not being
properly hermetic, deterministic, and reentrant.</p>
<p>This page is intended to be both normative and authoritative. If
diff --git a/site/docs/toolchains.md b/site/docs/toolchains.md
index 740c4f7..10038dd 100644
--- a/site/docs/toolchains.md
+++ b/site/docs/toolchains.md
@@ -19,7 +19,7 @@
## Motivation
Let's first look at the problem toolchains are designed to solve. Suppose you
-were writing rules to support the "bar" programming language. Your `bar_binary`
+are writing rules to support the "bar" programming language. Your `bar_binary`
rule would compile `*.bar` files using the `barc` compiler, a tool that itself
is built as another target in your workspace. Since users who write `bar_binary`
targets shouldn't have to specify a dependency on the compiler, you make it an
@@ -47,7 +47,7 @@
BarcInfo = provider(
doc = "Information about how to invoke the barc compiler.",
# In the real world, compiler_path and system_lib might hold File objects,
- # but for simplicity we'll make them strings instead. arch_flags is a list
+ # but for simplicity they are strings for this example. arch_flags is a list
# of strings.
fields = ["compiler_path", "system_lib", "arch_flags"],
)
@@ -88,7 +88,7 @@
)
```
-We can improve on this solution by using `select` to choose the `compiler`
+You can improve on this solution by using `select` to choose the `compiler`
[based on the platform](configurable-attributes.html):
```python
@@ -134,7 +134,8 @@
Under the toolchain framework, instead of having rules depend directly on tools,
they instead depend on *toolchain types*. A toolchain type is a simple target
that represents a class of tools that serve the same role for different
-platforms. For instance, we can declare a type that represents the bar compiler:
+platforms. For instance, you can declare a type that represents the bar
+compiler:
```python
# By convention, toolchain_type targets are named "toolchain_type" and
@@ -179,7 +180,7 @@
[`ToolchainInfo` provider](skylark/lib/platform_common.html#ToolchainInfo)
of whatever target Bazel resolved the toolchain dependency to. The fields of the
`ToolchainInfo` object are set by the underlying tool's rule; in the next
-section we'll define this rule such that there is a `barcinfo` field that wraps
+section, this rule is defined such that there is a `barcinfo` field that wraps
a `BarcInfo` object.
Bazel's procedure for resolving toolchains to targets is described
@@ -208,7 +209,7 @@
## Defining toolchains
-To define some toolchains for a given toolchain type, we need three things:
+To define some toolchains for a given toolchain type, you need three things:
1. A language-specific rule representing the kind of tool or tool suite. By
convention this rule's name is suffixed with "\_toolchain".
@@ -253,11 +254,11 @@
the consuming rule retrieves using `ctx.toolchains` and the label of the
toolchain type. `ToolchainInfo`, like `struct`, can hold arbitrary field-value
pairs. The specification of exactly what fields are added to the `ToolchainInfo`
-should be clearly documented at the toolchain type. Here we have returned the
-values wrapped in a `BarcInfo` object in order to reuse the schema defined
-above; this style may be useful for validation and code reuse.
+should be clearly documented at the toolchain type. In this example, the values
+return wrapped in a `BarcInfo` object to reuse the schema defined above; this
+style may be useful for validation and code reuse.
-Now we can define targets for specific `barc` compilers.
+Now you can define targets for specific `barc` compilers.
```python
bar_toolchain(
@@ -281,7 +282,7 @@
)
```
-Finally, we create `toolchain` definitions for the two `bar_toolchain` targets.
+Finally, you create `toolchain` definitions for the two `bar_toolchain` targets.
These definitions link the language-specific targets to the toolchain type and
provide the constraint information that tells Bazel when the toolchain is
appropriate for a given platform.
@@ -326,7 +327,7 @@
## Registering and building with toolchains
-At this point all the building blocks are assembled, and we just need to make
+At this point all the building blocks are assembled, and you just need to make
the toolchains available to Bazel's resolution procedure. This is done by
registering the toolchain, either in a `WORKSPACE` file using
`register_toolchains()`, or by passing the toolchains' labels on the command
@@ -336,7 +337,7 @@
register_toolchains(
"//bar_tools:barc_linux_toolchain",
"//bar_tools:barc_windows_toolchain",
- # Target patterns are also permitted, so we could have also written:
+ # Target patterns are also permitted, so you could have also written:
# "//bar_tools:all",
)
```
@@ -413,7 +414,7 @@
the list of available execution platforms is filtered to remove
any that do not match the execution constraints.
-1. For each available execution platform, we associate each toolchain type with
+1. For each available execution platform, you associate each toolchain type with
the first available toolchain, if any, that is compatible with this execution
platform and the target platform.
diff --git a/site/docs/updating-bazel.md b/site/docs/updating-bazel.md
index b3d9955..8d8bf77 100644
--- a/site/docs/updating-bazel.md
+++ b/site/docs/updating-bazel.md
@@ -36,7 +36,7 @@
project can be prepared for the next Bazel release without breaking
compatibility with the current release.
-We recommend the following process for project migration:
+Follow this process for project migration:
1. Assume that your project already works with a given Bazel release, say 0.26,
and you want to prepare for the next release, say 0.27
diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html
index 21c69a7..df47225 100644
--- a/site/docs/user-manual.html
+++ b/site/docs/user-manual.html
@@ -78,8 +78,8 @@
</li>
</ol>
<p>
- If you use a non-default package path, we recommend that you specify
- it in your <a href='guide.html#bazelrc'>Bazel configuration file</a> for
+ If you use a non-default package path, specify it in your
+ <a href='guide.html#bazelrc'>Bazel configuration file</a> for
convenience.
</p>
<p>
@@ -1161,8 +1161,8 @@
generated for the set of targets specified on the command line.
</p>
<p>
- Note that our implementation of <code class='flag'>--save_temps</code> does not use the compiler's
- <code>-save-temps</code> flag. Instead, we do two passes, one with <code>-S</code>
+ Note that the implementation of <code class='flag'>--save_temps</code> does not use the compiler's
+ <code>-save-temps</code> flag. Instead, there are two passes, one with <code>-S</code>
and one with <code>-E</code>. A consequence of this is that if your build fails,
Bazel may not yet have produced the ".i" or ".ii" and ".s" files.
If you're trying to use <code class='flag'>--save_temps</code> to debug a failed compilation,
@@ -2150,20 +2150,17 @@
<p>
The <code>clean</code> command is provided primarily as a means of
reclaiming disk space for workspaces that are no longer needed.
- However, we recognize that Bazel's incremental rebuilds might not be
- perfect; <code>clean</code> may be used to recover a consistent
+ Bazel's incremental rebuilds may not be
+ perfect so <code>clean</code> can be used to recover a consistent
state when problems arise.
</p>
<p>
- Bazel's design is such that these problems are fixable; we consider
- such bugs a high priority, and will do our best fix them. If you
- ever find an incorrect incremental build, please file a bug report.
- We encourage developers to get out of the habit of
- using <code>clean</code> and into that of reporting bugs in the
- tools.
+ Bazel's design is such that these problems are fixable and
+ these bugs are a high priority to be fixed. If you
+ ever find an incorrect incremental build, file a bug report, and report bugs in the tools
+ rather than using <code>clean</code>.
</p>
-
<h2 id='run'>Running executables</h2>
<p>
The <code>bazel run</code> command is similar to <code>bazel build</code>, except
@@ -2823,9 +2820,8 @@
overriden with <code class='flag'>--output_base</code>. The directory
must either not exist or be owned by the calling user. In the past,
this was allowed to point to a directory shared among various users
- but it's not allowed any longer. (We can reconsider allowing this once
- <a href='https://github.com/bazelbuild/bazel/issues/11100'>#11100</a>
- is addressed.)
+ but it's not allowed any longer. This may be allowed once the following is addressed:
+ <a href='https://github.com/bazelbuild/bazel/issues/11100'>#11100</a>.
</p>
<p>
If the <code class='flag'>--output_base</code> option is specified, it overrides
@@ -2939,7 +2935,7 @@
<i>WARNING:</i> <code class='flag'>--batch</code> is sufficiently slower than standard
client/server mode. Additionally it might not support all of the features and optimizations which
are made possible by a persistent Bazel server. If you're using <code class='flag'>--batch</code>
- for the purpose of build isolation, we recommend using the command option
+ for the purpose of build isolation, you should use the command option
<code class='flag'>--nokeep_state_after_build</code>, which guarantees that no incremental
in-memory state is kept between builds. In order to restart the Bazel server and JVM after a
build, please explicitly do so using the "shutdown" command.
diff --git a/site/docs/windows.md b/site/docs/windows.md
index f057a4d..f76a1de 100644
--- a/site/docs/windows.md
+++ b/site/docs/windows.md
@@ -10,8 +10,8 @@
## Known issues
-We mark Windows-related Bazel issues on GitHub with the "team-Windows"
-label. [You can see the open issues here.](https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Ateam-Windows)
+Windows-related Bazel issues are marked with the "team-Windows"
+label on GitHub. [You can see the open issues here.](https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Ateam-Windows)
## Best practices
@@ -52,10 +52,10 @@
<a name="running-bazel-shells"></a>
### Running Bazel: MSYS2 shell vs. command prompt vs. PowerShell
-We recommend running Bazel from the command prompt (`cmd.exe`) or from
+**Recommendation:** Run Bazel from the command prompt (`cmd.exe`) or from
PowerShell.
-As of 2020-01-15, we **do not recommend** running Bazel from `bash` -- either
+As of 2020-01-15, **do not** run Bazel from `bash` -- either
from MSYS2 shell, or Git Bash, or Cygwin, or any other Bash variant. While Bazel
may work for most use cases, some things are broken, like
[interrupting the build with Ctrl+C from MSYS2](https://github.com/bazelbuild/bazel/issues/10573)).
@@ -115,9 +115,9 @@
applies not only to rules in your project, but to rules in any of the external
repositories your project depends on (even transitively).
-We may explore the option to use Windows Subsystem for Linux (WSL) to build
-these rules, but as of 2020-01-15 it is not a priority for the Bazel-on-Windows
-subteam.
+In the future, there may be an option to use Windows Subsystem for
+Linux (WSL) to build these rules, but currently it is not a priority for
+the Bazel-on-Windows subteam.
### Setting environment variables
@@ -215,8 +215,9 @@
From 0.29.0, Bazel supports building with LLVM's MSVC-compatible compiler driver (`clang-cl.exe`).
**Requirement**: To build with Clang, you have to install **both**
-[LLVM](http://releases.llvm.org/download.html) and Visual C++ Build tools, because although we use
-`clang-cl.exe` as compiler, we still need to link to Visual C++ libraries.
+[LLVM](http://releases.llvm.org/download.html) and Visual C++ Build tools,
+because although you use `clang-cl.exe` as compiler, you still need to link to
+Visual C++ libraries.
Bazel can automatically detect LLVM installation on your system, or you can explicitly tell
Bazel where LLVM is installed by `BAZEL_LLVM`.
diff --git a/site/docs/workspace-log.md b/site/docs/workspace-log.md
index bd20173..17f0362 100644
--- a/site/docs/workspace-log.md
+++ b/site/docs/workspace-log.md
@@ -5,7 +5,7 @@
# Finding Non-Hermetic Behavior in WORKSPACE Rules
-In the following, we say that a host machine is the machine where Bazel runs.
+In the following, a host machine is the machine where Bazel runs.
When using remote execution, the actual build and/or test steps are not
happening on the host machine, but are instead sent off to the remote execution
