Docs: Fix spacing after periods.
PiperOrigin-RevId: 353258851
diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html
index 7df9047..ea2a0d0 100644
--- a/site/docs/build-ref.html
+++ b/site/docs/build-ref.html
@@ -53,7 +53,7 @@
<h3 id="packages">Packages</h3>
<p>
The primary unit of code organization in a repository is
- the <i>package</i>. A package is a collection of related files and a
+ the <i>package</i>. A package is a collection of related files and a
specification of the dependencies among them.
</p>
@@ -61,7 +61,7 @@
A package is defined as a directory containing a file
named <code>BUILD</code> or <code>BUILD.bazel</code>,
residing beneath the top-level directory in the
- workspace. A package includes all files in its directory, plus all
+ workspace. A package includes all files in its directory, plus all
subdirectories beneath it, except those which themselves contain a BUILD
file.
</p>
@@ -101,10 +101,10 @@
</p>
<p>
- The second kind of target is the <i>rule</i>. A rule specifies the
+ The second kind of target is the <i>rule</i>. A rule specifies the
relationship between a set of input and a set of output files,
including the necessary steps to derive the outputs from the inputs.
- The outputs of a rule are always generated files. The inputs to a
+ The outputs of a rule are always generated files. The inputs to a
rule may be source files, but they may be generated files also;
consequently, outputs of one rule may be the inputs to another,
allowing long chains of rules to be constructed.
@@ -113,17 +113,17 @@
<p>
Whether the input to a rule is a source file or a generated file is
in most cases immaterial; what matters is only the contents of that
- file. This fact makes it easy to replace a complex source file with
+ file. This fact makes it easy to replace a complex source file with
a generated file produced by a rule, such as happens when the burden
of manually maintaining a highly structured file becomes too
- tiresome, and someone writes a program to derive it. No change is
- required to the consumers of that file. Conversely, a generated
+ tiresome, and someone writes a program to derive it. No change is
+ required to the consumers of that file. Conversely, a generated
file may easily be replaced by a source file with only local
changes.
</p>
<p>
- The inputs to a rule may also include <i>other rules</i>. The
+ The inputs to a rule may also include <i>other rules</i>. The
precise meaning of such relationships is often quite complex and
language- or rule-dependent, but intuitively it is simple: a C++
library rule A might have another C++ library rule B for an input.
@@ -136,7 +136,7 @@
<p>
An invariant of all rules is that the files generated by a rule
always belong to the same package as the rule itself; it is not
- possible to generate files into another package. It is not uncommon
+ possible to generate files into another package. It is not uncommon
for a rule's inputs to come from another package, though.
</p>
@@ -156,7 +156,7 @@
<h3 id="labels">Labels</h3>
<p>
- All targets belong to exactly one package. The name of a target is
+ All targets belong to exactly one package. The name of a target is
called its <em>label</em>, and a typical label in canonical form
looks like this:
</p>
@@ -179,8 +179,8 @@
<p>
Each label has two parts, a package name (<code>my/app/main</code>)
- and a target name (<code>app_binary</code>). Every label uniquely
- identifies a target. Labels sometimes appear in other forms; when
+ and a target name (<code>app_binary</code>). Every label uniquely
+ identifies a target. Labels sometimes appear in other forms; when
the colon is omitted, the target name is assumed to be the same as
the last component of the package name, so these two labels are
equivalent:
@@ -193,7 +193,7 @@
<p>
Short-form labels such as <code>//my/app</code> are not to
- be confused with package names. Labels start with <code>//</code>,
+ be confused with package names. Labels start with <code>//</code>,
but package names never do, thus <code>my/app</code> is the
package containing <code>//my/app</code>.
@@ -204,7 +204,7 @@
<p>
Within a BUILD file, the package-name part of label may be omitted,
- and optionally the colon too. So within the BUILD file for package
+ and optionally the colon too. So within the BUILD file for package
<code>my/app</code> (i.e. <code>//my/app:BUILD</code>),
the following "relative" labels are all equivalent:
</p>
@@ -242,11 +242,11 @@
<p>
Relative labels cannot be used to refer to targets in other
packages; the complete package name must always be specified in this
- case. For example, if the source tree contains both the package
+ case. For example, if the source tree contains both the package
<code>my/app</code> and the package
<code>my/app/testdata</code> (i.e., each of these two
- packages has its own BUILD file). The latter package contains a
- file named <code>testdepot.zip</code>. Here are two ways (one
+ packages has its own BUILD file). The latter package contains a
+ file named <code>testdepot.zip</code>. Here are two ways (one
wrong, one correct) to refer to this file within
<code>//my/app:BUILD</code>:
</p>
@@ -261,7 +261,7 @@
label, such as <code>//my/app:testdata/testdepot.zip</code>
or <code>//my:app/testdata/testdepot.zip</code>, you will get an
error from the build tool saying that the label "crosses a package
- boundary". You should correct the label by putting the colon after
+ boundary". You should correct the label by putting the colon after
the directory containing the innermost enclosing BUILD file, i.e.,
<code>//my/app/testdata:testdepot.zip</code>.
</p>
@@ -282,7 +282,7 @@
<p>
The syntax of labels is intentionally strict, so as to
- forbid metacharacters that have special meaning to the shell. This
+ forbid metacharacters that have special meaning to the shell. This
helps to avoid inadvertent quoting problems, and makes it easier to
construct tools and scripts that manipulate labels, such as the
@@ -308,24 +308,24 @@
they must neither start nor end with a slash
(e.g. <code>/foo</code> and <code>foo/</code> are forbidden) nor
contain multiple consecutive slashes as path separators
- (e.g. <code>foo//bar</code>). Similarly, up-level references
+ (e.g. <code>foo//bar</code>). Similarly, up-level references
(<code>..</code>) and current-directory references
- (<code>./</code>) are forbidden. The sole exception to this
+ (<code>./</code>) are forbidden. The sole exception to this
rule is that a target name may consist of exactly
'<code>.</code>'.
</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
- names of rules. Especially when the shorthand form of a label is
- used, it may confuse the reader. 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
for <code>//foo/bar/wiz:wiz</code>, even if there is no such package
<code>foo/bar/wiz</code>; it never refers to <code>//foo:bar/wiz</code>,
even if that target exists.</p>
<p>However, there are some situations where use of a slash is
- convenient, or sometimes even necessary. For example, the name of
+ convenient, or sometimes even necessary. For example, the name of
certain rules must match their principal source file, which may
reside in a subdirectory of the package.</p>
@@ -361,7 +361,7 @@
<p>
A rule specifies the relationship between inputs and outputs, and the
- steps to build the outputs. Rules can be of one of many different
+ steps to build the outputs. Rules can be of one of many different
kinds or <i>classes</i>, which produce compiled
executables and libraries, test executables and other supported
outputs as described in the
@@ -370,10 +370,10 @@
<p>
Every rule has a name, specified by the <code>name</code> attribute,
- of type string. The name must be a syntactically valid target name,
- as specified <a href='#name'>above</a>. In some cases, the name is
+ of type string. The name must be a syntactically valid target name,
+ as specified <a href='#name'>above</a>. In some cases, the name is
somewhat arbitrary, and more interesting are the names of the files
- generated by the rule; this is true of genrules. In other
+ generated by the rule; this is true of genrules. In other
cases, the name is significant: for <code>*_binary</code>
and <code>*_test</code> rules, for example, the rule name determines
the name of the executable produced by the build.
@@ -396,11 +396,11 @@
attribute are a function of the rule's class; see
the <a href='be/overview.html'>Build
Encyclopedia</a> for a list of rules and their
- corresponding attributes. Each attribute has a name and a
- type. Some of the common types an attribute can have are integer,
+ corresponding attributes. Each attribute has a name and a
+ type. Some of the common types an attribute can have are integer,
label, list of labels, string, list of strings, output label,
- list of output labels. Not all attributes need to be specified in
- every rule. Attributes thus form a dictionary from keys (names) to
+ list of output labels. Not all attributes need to be specified in
+ every rule. Attributes thus form a dictionary from keys (names) to
optional, typed values.
</p>
@@ -414,13 +414,13 @@
The <code>outs</code> attribute present in many rules has type "list
of output labels"; this is similar to the type of
the <code>srcs</code> attribute, but differs in two significant
- ways. Firstly, due to the invariant that the outputs of a rule
+ ways. Firstly, due to the invariant that the outputs of a rule
belong to the same package as the rule itself, output labels cannot
include a package component; they must be in one of the "relative"
- forms shown above. Secondly, the relationship implied by an
+ forms shown above. Secondly, the relationship implied by an
(ordinary) label attribute is inverse to that implied by an output
label: a rule <i>depends on</i> its <code>srcs</code>, whereas a rule <i>is
- depended on by</i> its <code>outs</code>. The two types of label attributes
+ depended on by</i> its <code>outs</code>. The two types of label attributes
thus assign direction to the edges between targets, giving rise to a
dependency graph.
</p>
@@ -436,7 +436,7 @@
<p>
The previous section described packages, targets and labels, and the
- build dependency graph abstractly. In this section, we'll look at
+ build dependency graph abstractly. In this section, we'll look at
the concrete syntax used to define a package.
</p>
@@ -451,7 +451,7 @@
<p>
In general, order does matter: variables must be defined before they are used, for
- example. However, most BUILD files consist only of declarations of
+ example. However, most BUILD files consist only of declarations of
build rules, and the relative order of these statements is
immaterial; all that matters is <em>which</em> rules were declared,
and with what values, by the time package evaluation completes.
@@ -477,7 +477,7 @@
<p>
Crucially, programs in Starlark are unable to perform
- arbitrary I/O. This invariant makes the
+ arbitrary I/O. This invariant makes the
interpretation of BUILD files hermetic, i.e. dependent only on a
known set of inputs, which is essential for ensuring that builds are
reproducible.
@@ -546,10 +546,9 @@
<p>
The majority of build rules come in families, grouped together by
- language. For
- example, <code>cc_binary</code>, <code>cc_library</code>
+ language. For example, <code>cc_binary</code>, <code>cc_library</code>
and <code>cc_test</code> are the build rules for C++ binaries,
- libraries, and tests, respectively. Other languages use the same
+ libraries, and tests, respectively. Other languages use the same
naming scheme, with a different prefix, e.g. <code>java_*</code> for
Java. Some of these functions are documented in the
<a href="be/overview.html">Build Encyclopedia</a>, but it is possible
@@ -558,7 +557,7 @@
<ul>
<li><p><code>*_binary</code>
- rules build executable programs in a given language. After a
+ rules build executable programs in a given language. After a
build, the executable will reside in the build tool's binary
output tree at the corresponding name for the rule's label,
so <code>//my:program</code> would appear at
@@ -574,14 +573,14 @@
<li><p><code>*_test</code>
rules are a specialization of a <code>*_binary</code> rule, used for automated
- testing. Tests are simply programs that return zero on success.
+ testing. Tests are simply programs that return zero on success.
</p>
<p>
Like binaries, tests also have runfiles trees, and the files
beneath it are the only files that a test may legitimately open
- at runtime. For example, a program <code>cc_test(name='x',
+ at runtime. For example, a program <code>cc_test(name='x',
data=['//foo:bar'])</code> may open and
read <code>$TEST_SRCDIR/workspace/foo/bar</code> during execution.
@@ -596,7 +595,7 @@
<li><code>*_library</code>
rules specify separately-compiled modules in the given
- programming language. Libraries can depend on other libraries,
+ programming language. Libraries can depend on other libraries,
and binaries and tests can depend on libraries, with the expected
separate-compilation behavior.
</li>
@@ -607,13 +606,13 @@
<p>
A target <code>A</code> <i>depends upon</i> a target
<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
+ 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
<em>dependency graph</em>.
A target's <em>direct</em> dependencies are those other targets
- reachable by a path of length 1 in the dependency graph. A target's
+ reachable by a path of length 1 in the dependency graph. A target's
<em>transitive</em> dependencies are those targets upon which it
depends via a path of any length through the graph.
</p>
@@ -621,7 +620,7 @@
<p>
In fact, in the context of builds, there are two dependency graphs,
the graph of <em>actual dependencies</em> and the graph of
- <em>declared dependencies</em>. Most of the time, the two graphs
+ <em>declared dependencies</em>. Most of the time, the two graphs
are so similar that this distinction need not be made, but it is
useful for the discussion below.
</p>
@@ -645,9 +644,9 @@
<p>
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
+ 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>. We say
<i>D</i> is an <em>overapproximation</em> of <i>A</i>.
</p>
@@ -665,7 +664,7 @@
Failure to observe this principle causes undefined behavior: the
build may fail, but worse, the build may depend on some prior
operations, or upon transitive declared dependencies the target
- happens to have. The build tool attempts aggressively to check for
+ happens to have. The build tool attempts aggressively to check for
missing dependencies and report errors, but it is not possible for
this checking to be complete in all cases.
</p>
@@ -687,8 +686,8 @@
The transitive nature of dependencies leads to a common mistake.
Through careless programming, code in one file may use code provided
by an <em>indirect</em> dependency, i.e. a transitive but not direct
- edge in the declared dependency graph. Indirect dependencies do not
- appear in the BUILD file. Since the rule doesn't
+ edge in the declared dependency graph. Indirect dependencies do not
+ appear in the BUILD file. Since the rule doesn't
directly depend on the provider, there is no way to track changes,
as shown in the following example timeline:
</p>
@@ -799,7 +798,7 @@
</td>
</tr></table>
The declared dependencies no longer overapproximate the actual
-dependencies. This may build ok, because the transitive closures of
+dependencies. This may build ok, because the transitive closures of
the two graphs are equal, but masks a problem: <code>a</code> has an
actual but undeclared dependency on <code>c</code>.
</div>
@@ -876,7 +875,7 @@
<p>
Many rules also have additional attributes for rule-specific kinds
of dependency, e.g. <code>compiler</code>, <code>resources</code>,
- etc. These are detailed in the Build Encyclopedia.
+ etc. These are detailed in the Build Encyclopedia.
</p>
<h4 id="srcs"><code>srcs</code> dependencies</h4>
@@ -891,10 +890,10 @@
</p>
<h4 id="data"><code>data</code> dependencies</h4>
-<p>A build target might need some data files to run correctly. These
+<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
+ 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
same applies to tools that are launched during execution.
@@ -957,10 +956,10 @@
use all the data files in the directory).
</p>
- <p>But try not to do this. In order to ensure correct incremental rebuilds (and
+ <p>But try not to do this. In order to ensure correct incremental rebuilds (and
re-execution of tests) after a change, the build system must be
aware of the complete set of files that are inputs to the build (or
- test). When you specify a directory, the build system will perform
+ test). When you specify a directory, the build system will perform
a rebuild only when the directory itself changes (due to addition or
deletion of files), but won't be able to detect edits to individual
files as those changes do not affect the enclosing directory.
@@ -982,7 +981,7 @@
(e.g. they contain certain punctuation symbols), then explicit
enumeration of files, or use of the
<a href='be/functions.html#glob'><code>glob()</code></a> function will
- produce an invalid labels error. You must use directory labels in this case,
+ produce an invalid labels error. You must use directory labels in this case,
but beware of the concomitant risk of incorrect rebuilds described above.
</p>
@@ -991,7 +990,7 @@
"<code>//data/regression:unittest/.</code>".
</p>
- <p>Note that directory labels are only valid for data dependencies. If you try to use
+ <p>Note that directory labels are only valid for data dependencies. If you try to use
a directory as a label in an argument other than <code>data</code>, it
will fail and you will get a (probably cryptic) error message.
</p>
diff --git a/site/docs/cc-toolchain-config-reference.md b/site/docs/cc-toolchain-config-reference.md
index c28b0c3..2481f90 100644
--- a/site/docs/cc-toolchain-config-reference.md
+++ b/site/docs/cc-toolchain-config-reference.md
@@ -43,7 +43,7 @@
When a C++ target enters the analysis phase, Bazel selects the appropriate
`cc_toolchain` target based on the BUILD file, and obtains the
`CcToolchainConfigInfo` provider from the target specified in the
-`cc_toolchain.toolchain_config` attribute. The `cc_toolchain` target
+`cc_toolchain.toolchain_config` attribute. The `cc_toolchain` target
passes this information to the C++ target through a `CcToolchainProvider`.
For example, a compile or link action, instantiated by a rule such as
@@ -515,7 +515,7 @@
This same feature can be implemented entirely differently for Linux, which uses
-`fission`, or for Windows, which produces `.pdb` files. For example, the
+`fission`, or for Windows, which produces `.pdb` files. For example, the
implementation for `fission`-based debug symbol generation might look as
follows:
diff --git a/site/docs/cpp-use-cases.md b/site/docs/cpp-use-cases.md
index b7e98c7..135c923 100644
--- a/site/docs/cpp-use-cases.md
+++ b/site/docs/cpp-use-cases.md
@@ -32,9 +32,9 @@
## Using transitive includes
If a file includes a header, then the file's rule should depend on that header's
-library. Conversely, only direct dependencies need to be specified as
-dependencies. For example, suppose `sandwich.h` includes `bread.h` and
-`bread.h` includes `flour.h`. `sandwich.h` doesn't include `flour.h` (who wants
+library. Conversely, only direct dependencies need to be specified as
+dependencies. For example, suppose `sandwich.h` includes `bread.h` and
+`bread.h` includes `flour.h`. `sandwich.h` doesn't include `flour.h` (who wants
flour in their sandwich?), so the `BUILD` file would look like this:
```python
@@ -66,7 +66,7 @@
Sometimes you cannot (or do not want to) root include paths at the workspace
root. Existing libraries might already have an include directory that doesn't
-match its path in your workspace. For example, suppose you have the following
+match its path in your workspace. For example, suppose you have the following
directory structure:
```
@@ -82,7 +82,7 @@
Bazel will expect `some_lib.h` to be included as
`legacy/some_lib/include/some_lib.h`, but suppose `some_lib.cc` includes
-`"some_lib.h"`. To make that include path valid,
+`"some_lib.h"`. To make that include path valid,
`legacy/some_lib/BUILD` will need to specify that the `some_lib/include`
directory is an include directory:
diff --git a/site/docs/external.md b/site/docs/external.md
index c7dc664..e04e1bc 100644
--- a/site/docs/external.md
+++ b/site/docs/external.md
@@ -5,12 +5,12 @@
# Working with External Dependencies
-Bazel can depend on targets from other projects. Dependencies from these other
+Bazel can depend on targets from other projects. Dependencies from these other
projects are called _external dependencies_.
The `WORKSPACE` file (or `WORKSPACE.bazel` file) in the [workspace directory](build-ref.html#workspace)
-tells Bazel how to get other projects' sources. These other projects can
-contain one or more `BUILD` files with their own targets. `BUILD` files within
+tells Bazel how to get other projects' sources. These other projects can
+contain one or more `BUILD` files with their own targets. `BUILD` files within
the main project can depend on these external targets by using their name from
the `WORKSPACE` file.
@@ -363,7 +363,7 @@
[#5116](https://github.com/bazelbuild/bazel/issues/5116) for more information.
-Do not use `bind()`. See "[Consider removing
+Do not use `bind()`. See "[Consider removing
bind](https://github.com/bazelbuild/bazel/issues/1952)" for a long discussion of its issues and
alternatives.
@@ -376,6 +376,6 @@
- Downloading resources from URLs.
- Generating or symlinking BUILD files into the external repository directory.
-Avoid using `repository_ctx.execute` when possible. For example, when using a non-Bazel C++
+Avoid using `repository_ctx.execute` when possible. For example, when using a non-Bazel C++
library that has a build using Make, it is preferable to use `repository_ctx.download()` and then
write a BUILD file that builds it, instead of running `ctx.execute(["make"])`.
diff --git a/site/docs/install-windows.md b/site/docs/install-windows.md
index daaab5d..6dd934b 100644
--- a/site/docs/install-windows.md
+++ b/site/docs/install-windows.md
@@ -88,7 +88,7 @@
* Common MSYS2 packages
- You will likely need these to build and run targets that depend on Bash. MSYS2 does not install
+ You will likely need these to build and run targets that depend on Bash. MSYS2 does not install
these tools by default, so you need to install them manually. Projects that depend on Bash tools in `PATH` need this step (for example TensorFlow).
Open the MSYS2 terminal and run this command:
diff --git a/site/docs/mobile-install.md b/site/docs/mobile-install.md
index 76bab4b..112d559 100644
--- a/site/docs/mobile-install.md
+++ b/site/docs/mobile-install.md
@@ -65,7 +65,7 @@
though only one method was changed.
- Uploading data to the device. adb does not use the full bandwidth of a USB 2.0
-connection, and larger apps can take a lot of time to upload. The entire app is
+connection, and larger apps can take a lot of time to upload. The entire app is
uploaded, even if only small parts have changed, for example, a resource or a
single method, so this can be a major bottleneck.
diff --git a/site/docs/output_directories.md b/site/docs/output_directories.md
index 07fe2c5..8d9a888 100644
--- a/site/docs/output_directories.md
+++ b/site/docs/output_directories.md
@@ -123,7 +123,7 @@
foo/bartest.log e.g. foo/bar.log might be an output of the //foo:bartest test with
foo/bartest.status foo/bartest.status containing exit status of the test (e.g.
PASSED or FAILED (Exit 1), etc)
- include/ <== a tree with include symlinks, generated as needed. The
+ include/ <== a tree with include symlinks, generated as needed. The
bazel-include symlinks point to here. This is used for
linkstamp stuff, etc.
host/ <== BuildConfiguration for build host (user's workstation), for
diff --git a/site/docs/platforms.md b/site/docs/platforms.md
index 55969ef..99bec91 100644
--- a/site/docs/platforms.md
+++ b/site/docs/platforms.md
@@ -139,7 +139,7 @@
```
When building for anything but 64-bit Windows we say that `:win_driver_lib` is
-incompatible. Incompatibility is transitive. Any targets that transitively
+incompatible. Incompatibility is transitive. Any targets that transitively
depend on an incompatible target are themselves considered incompatible.
### When are targets skipped?
diff --git a/site/docs/query-how-to.html b/site/docs/query-how-to.html
index f783fef..c147580 100644
--- a/site/docs/query-how-to.html
+++ b/site/docs/query-how-to.html
@@ -106,16 +106,16 @@
<p>Certain rules include implicit dependencies on additional libraries or tools.
For example, to build a <code>genproto</code> rule, you need first to build the Protocol
Compiler, so every <code>genproto</code> rule carries an implicit dependency on the
-protocol compiler. These dependencies are not mentioned in the build file,
-but added in by the build tool. The full set of implicit dependencies is
+protocol compiler. These dependencies are not mentioned in the build file,
+but added in by the build tool. The full set of implicit dependencies is
currently undocumented. Using <code>--noimplicit_deps</code> allows you to filter out
these deps from your query results.
<h2 id="Reverse_Dependencies">Reverse dependencies</h2>
-<p>You might want to know the set of targets that depends on some target. e.g.,
+<p>You might want to know the set of targets that depends on some target. e.g.,
if you're going to change some code, you might want to know what other code
-you're about to break. You can use <code>rdeps(u, x)</code> to find the reverse
+you're about to break. You can use <code>rdeps(u, x)</code> to find the reverse
dependencies of the targets in <code>x</code> within the transitive closure of <code>u</code>.</p>
Bazel's <a href="query.html#sky-query">Sky Query</a>
@@ -258,7 +258,7 @@
<p>Once you have the results of this query, you will often find that a single
target stands out as being an unexpected or egregious and undesirable
-dependency of <code>bar</code>. The query can then be further refined to:</p>
+dependency of <code>bar</code>. The query can then be further refined to:</p>
<h4 id="Show_me_a_path_from_docker_updater">Show me a path from <code>docker/updater:updater_systest</code> (a <code>py_test</code>) to some <code>cc_library</code> that it depends upon:</h4>
@@ -268,7 +268,7 @@
<h4 id="Why_does_library_photos_frontend">Why does library <code>//photos/frontend:lib</code> depend on two variants of the same library <code>//third_party/jpeglib</code> and <code>//third_party/jpeg</code>?</h4>
<p>This query boils down to: "show me the subgraph of <code>//photos/frontend:lib</code> that
-depends on both libraries". When shown in topological order, the last element
+depends on both libraries". When shown in topological order, the last element
of the result is the most likely culprit.</p>
<pre>bazel query 'allpaths(//photos/frontend:lib, //third_party/jpeglib)
@@ -314,7 +314,7 @@
<p>Unfortunately, the query language can't currently give you the longest path
from x to y, but it can find the (or rather <em>a</em>) most distant node from the
starting point, or show you the <em>lengths</em> of the longest path from x to every
-y that it depends on. Use <code>maxrank</code>:</p>
+y that it depends on. Use <code>maxrank</code>:</p>
<pre>bazel query 'deps(//foo-tests)' --output maxrank | tail -1
85 //third_party/zlib:zutil.c</pre>
diff --git a/site/docs/query.html b/site/docs/query.html
index fcec308..9faf8c6 100644
--- a/site/docs/query.html
+++ b/site/docs/query.html
@@ -46,8 +46,8 @@
<ul>
<li>
<p>
- <b>Keywords</b>, such as <code>let</code>. Keywords are the reserved words of the
- language, and each of them is described below. The complete set
+ <b>Keywords</b>, such as <code>let</code>. Keywords are the reserved words of the
+ language, and each of them is described below. The complete set
of keywords is:
</p>
@@ -128,7 +128,7 @@
</p>
<li><b>Punctuation</b>, such as parens <code>()</code>, period
- <code>.</code> and comma <code>,</code>, etc. Words containing
+ <code>.</code> and comma <code>,</code>, etc. Words containing
punctuation (other than the exceptions listed above) must be quoted.
</ul>
@@ -138,16 +138,16 @@
<h2 id='concepts'>Bazel query language concepts</h2>
<p>
- The Bazel query language is a language of expressions. Every
+ The Bazel query language is a language of expressions. Every
expression evaluates to a <b>partially-ordered set</b> of targets,
- or equivalently, a <b>graph</b> (DAG) of targets. This is the only
+ or equivalently, a <b>graph</b> (DAG) of targets. This is the only
datatype.
</p>
<p>
In some expressions, the partial order of the graph is
not interesting; In this case, we call the values
"sets". In cases where the partial order of elements
- is significant, we call values "graphs". Note
+ is significant, we call values "graphs". Note
that both terms refer to the same datatype, but merely emphasize
different aspects of it.
</p>
@@ -157,7 +157,7 @@
Build dependency graphs should be acyclic.
The algorithms used by the query language are intended for use in
- acyclic graphs, but are robust against cycles. The details of how
+ acyclic graphs, but are robust against cycles. The details of how
cycles are treated are not specified and should not be relied upon.
</p>
@@ -183,9 +183,9 @@
<p>
Bazel query language expressions operate over the build
dependency graph, which is the graph implicitly defined by all
- rule declarations in all BUILD files. It is important to understand
+ rule declarations in all BUILD files. It is important to understand
that this graph is somewhat abstract, and does not constitute a
- complete description of how to perform all the steps of a build. In
+ complete description of how to perform all the steps of a build. In
order to perform a build, a <em>configuration</em> is required too;
see the <a href='user-manual.html#configurations'>configurations</a>
section of the User's Guide for more detail.
@@ -194,7 +194,7 @@
<p>
The result of evaluating an expression in the Bazel query language
is true <em>for all configurations</em>, which means that it may be
- a conservative over-approximation, and not exactly precise. If you
+ a conservative over-approximation, and not exactly precise. If you
use the query tool to compute the set of all source files needed
during a build, it may report more than are actually necessary
because, for example, the query tool will include all the files
@@ -206,11 +206,11 @@
<p>
Operations preserve any ordering
- constraints inherited from their subexpressions. You can think of
- this as "the law of conservation of partial order". Consider an
+ constraints inherited from their subexpressions. You can think of
+ this as "the law of conservation of partial order". Consider an
example: if you issue a query to determine the transitive closure of
dependencies of a particular target, the resulting set is ordered
- according to the dependency graph. If you filter that set to
+ according to the dependency graph. If you filter that set to
include only the targets of <code>file</code> kind, the same
<em>transitive</em> partial ordering relation holds between every
pair of targets in the resulting subset—even though none of
@@ -231,7 +231,7 @@
The order of the final result set is guaranteed to preserve all the
ordering constraints of its subexpressions, namely, that all the
transitive dependencies of <code>x</code> are correctly ordered with
- respect to each other. However, the query guarantees nothing about
+ respect to each other. However, the query guarantees nothing about
the ordering of the targets in <code>y</code>, nor about the
ordering of the targets in <code>deps(x)</code> relative to those in
<code>y</code> (except for those targets in
@@ -337,9 +337,9 @@
<pre>expr ::= <var>word</var></pre>
<p>
Syntactically, a <em>target pattern</em> is just a word. It
- is interpreted as an (unordered) set of targets. The simplest
+ is interpreted as an (unordered) set of targets. The simplest
target pattern is a label,
- which identifies a single target (file or rule). For example, the
+ which identifies a single target (file or rule). For example, the
target pattern <code>//foo:bar</code> evaluates to a set
containing one element, the target, the <code>bar</code>
rule.
@@ -347,7 +347,7 @@
<p>
Target patterns generalize labels to include wildcards over packages
- and targets. For example, <code>foo/...:all</code> (or
+ and targets. For example, <code>foo/...:all</code> (or
just <code>foo/...</code>) is a target pattern that evaluates to a
set containing all <em>rules</em> in every package recursively
beneath the <code>foo</code> directory;
@@ -394,8 +394,8 @@
ordered relative to each other according to the dependency relation.
So, the result of <code>foo:*</code> is not just the set of targets
in package <code>foo</code>, it is also the <em>graph</em> over
- those targets. (No guarantees are made about the relative ordering
- of the result nodes against other nodes.) See the section
+ those targets. (No guarantees are made about the relative ordering
+ of the result nodes against other nodes.) See the section
on <a href='#graph-order'>graph order</a> for more details.
</p>
@@ -404,7 +404,7 @@
| <var>$name</var></pre>
<p>
The Bazel query language allows definitions of and references to
- variables. The
+ variables. The
result of evaluation of a <code>let</code> expression is the same as
that of <var>expr</var><sub>2</sub>, with all free occurrences of
variable <var>name</var> replaced by the value of
@@ -420,7 +420,7 @@
<p>
An occurrence of a variable reference <code>name</code> other than in
an enclosing <code>let <var>name</var> = ...</code> expression is an
- error. In other words, toplevel query expressions cannot have free
+ error. In other words, toplevel query expressions cannot have free
variables.
</p>
@@ -440,7 +440,7 @@
(Both <a
href='#target-patterns'>target patterns</a> and variable references
consist of just a single token, a word, creating a syntactic
- ambiguity. However, there is no semantic ambiguity, because the
+ ambiguity. However, there is no semantic ambiguity, because the
subset of words that are legal variable names is disjoint from the
subset of words that are legal target patterns.)
</p>
@@ -448,7 +448,7 @@
<p>
(Technically speaking, <code>let</code> expressions do not increase
the expressiveness of the query language: any query expressible in
- the language can also be expressed without them. However, they
+ the language can also be expressed without them. However, they
improve the conciseness of many queries, and may also lead to more
efficient query evaluation.)
</p>
@@ -476,10 +476,10 @@
<p>
These three operators compute the usual set operations over their
- arguments. Each operator has two forms, a nominal form such
+ arguments. Each operator has two forms, a nominal form such
as <code>intersect</code> and a symbolic form such
- as <code>^</code>. Both forms are equivalent;
- the symbolic forms are quicker to type. (For clarity, the rest of
+ as <code>^</code>. Both forms are equivalent;
+ the symbolic forms are quicker to type. (For clarity, the rest of
this manual uses the nominal forms.) For example,
</p>
@@ -487,14 +487,14 @@
evaluates to the set of targets that match
<code>foo/...</code> but not
- <code>foo/bar/...</code> . Equivalently:
+ <code>foo/bar/...</code> . Equivalently:
<pre>foo/... - foo/bar/...</pre>
The <code>intersect</code> (<code>^</code>)
and <code>union</code> (<code>+</code>) operations are commutative
(symmetric); <code>except</code> (<code>-</code>) is
- asymmetric. The parser treats all three operators as
+ asymmetric. The parser treats all three operators as
left-associative and of equal precedence, so you might want parentheses.
For example, the first two of these expressions are
equivalent, but the third is not:
@@ -523,7 +523,7 @@
of one query in a regular text file, manipulating that text file
using other programs (e.g. standard UNIX shell tools), and then
introducing the result back into the query tool as a value for
- further processing. For example:
+ further processing. For example:
</p>
<pre>
bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo
@@ -550,7 +550,7 @@
<p>
Note, <code>set()</code> introduces no graph ordering constraints,
so path information may be lost when saving and reloading sets of
- nodes using it. See the <a href='#graph-order'>graph order</a>
+ nodes using it. See the <a href='#graph-order'>graph order</a>
section below for more detail.
</p>
@@ -633,19 +633,19 @@
</p>
<p>
- The resulting graph is ordered according to the dependency relation. See the
+ The resulting graph is ordered according to the dependency relation. See the
section on <a href='#graph-order'>graph order</a> for more details.
</p>
<p>
The <code>rdeps</code> operator accepts an optional third argument,
which is an integer literal specifying an upper bound on the depth of the
- search. The resulting graph will only include nodes within a distance of the
- specified depth from any node in the argument set. So
+ search. The resulting graph will only include nodes within a distance of the
+ specified depth from any node in the argument set. So
<code>rdeps(//foo, //common, 1)</code> evaluates to all nodes in the
transitive closure of <code>//foo</code> that directly depend on
- <code>//common</code>. (These numbers correspond to the ranks shown in the
- <a href='#output-ranked'><code>minrank</code></a> output format.) If the
+ <code>//common</code>. (These numbers correspond to the ranks shown in the
+ <a href='#output-ranked'><code>minrank</code></a> output format.) If the
<var>depth</var> parameter is omitted, the search is unbounded.
</p>
@@ -680,7 +680,7 @@
<p>
The <code>some(<var>x</var>)</code> operator selects one target
arbitrarily from its argument set <var>x</var>, and evaluates to a
- singleton set containing only that target. For example, the
+ singleton set containing only that target. For example, the
expression <code>some(//foo:main union //bar:baz)</code>
evaluates to a set containing either <code>//foo:main</code> or
<code>//bar:baz</code>—though which one is not defined.
@@ -701,9 +701,9 @@
<p>
The <code>somepath(<var>S</var>, <var>E</var>)</code> and
<code>allpaths(<var>S</var>, <var>E</var>)</code> operators compute
- paths between two sets of targets. Both queries accept two
+ paths between two sets of targets. Both queries accept two
arguments, a set <var>S</var> of starting points and a set
- <var>E</var> of ending points. <code>somepath</code> returns the
+ <var>E</var> of ending points. <code>somepath</code> returns the
graph of nodes on <em>some</em> arbitrary path from a target in
<var>S</var> to a target in <var>E</var>; <code>allpaths</code>
returns the graph of nodes on <em>all</em> paths from any target in
@@ -827,7 +827,7 @@
<ul>
<li><code><var>ruletype</var> rule</code>
<li><code><var>ruletype</var></code><br>
- Where <var>ruletype</var> is a build rule. The difference between these
+ Where <var>ruletype</var> is a build rule. The difference between these
forms is that including "rule" causes the <a href="#regex">regular expression</a> match for
<var>ruletype</var> to be anchored.
</ul>
@@ -894,12 +894,12 @@
<p>
The first argument, <var>pattern</var> is a word containing a
- <a href="#regex">regular expression</a> over target names. A <code>filter</code> expression
+ <a href="#regex">regular expression</a> over target names. A <code>filter</code> expression
evaluates to the set containing all targets <var>x</var> such that
<var>x</var> is a member of the set <var>input</var> and the
label (in absolute form, e.g. <code>//foo:bar</code>)
of <var>x</var> contains an (unanchored) match
- for the regular expression <var>pattern</var>. Since all
+ for the regular expression <var>pattern</var>. Since all
target names start with <code>//</code>, it may be used as an alternative
to the <code>^</code> regular expression anchor.
</p>
@@ -971,7 +971,7 @@
starting with a <code>[</code> bracket, ending with a <code>]</code> bracket
and using "<code>, </code>" (comma, space) to delimit multiple values.
Labels are converted to strings by using the absolute form of the
- label. For example, an attribute <code>deps=[":foo",
+ label. For example, an attribute <code>deps=[":foo",
"//otherpkg:bar", "wiz"]</code> would be converted to the
string <code>[//thispkg:foo, //otherpkg:bar, //thispkg:wiz]</code>.
Brackets
@@ -1023,7 +1023,7 @@
<p>
For example, <code>labels(srcs, //foo)</code> returns the set of
targets appearing in the <code>srcs</code> attribute of
- the <code>//foo</code> rule. If there are multiple rules
+ the <code>//foo</code> rule. If there are multiple rules
with <code>srcs</code> attributes in the <var>inputs</var> set, the
union of their <code>srcs</code> is returned.
</p>
@@ -1044,8 +1044,8 @@
<p>
For example, the query <code>kind(test, foo:*)</code> lists all
the <code>*_test</code> and <code>test_suite</code> rules
- in the <code>foo</code> package. All the results are (by
- definition) members of the <code>foo</code> package. In contrast,
+ in the <code>foo</code> package. All the results are (by
+ definition) members of the <code>foo</code> package. In contrast,
the query <code>tests(foo:*)</code> will return all of the
individual tests that would be executed by <code>bazel test
foo:*</code>: this may include tests belonging to other packages,
@@ -1060,7 +1060,7 @@
The <code>buildfiles(<var>x</var>)</code> operator returns the set
of files that define the packages of each target in
set <var>x</var>; in other words, for each package, its BUILD file,
- plus any files it references via <code>load</code>. Note that this also returns the BUILD files
+ plus any files it references via <code>load</code>. Note that this also returns the BUILD files
of the packages containing these <code>load</code>ed files.
</p>
@@ -1068,7 +1068,7 @@
This operator is typically used when determining what files or
packages are required to build a specified target, often in conjunction with
the <a href='#output-package'><code>--output package</code></a>
- option, below). For example,
+ option, below). For example,
</p>
<pre>bazel query 'buildfiles(deps(//foo))' --output package</pre>
<p>
@@ -1143,7 +1143,7 @@
</p>
<p>
- Some of the output formats accept additional options. The name of
+ Some of the output formats accept additional options. The name of
each output option is prefixed with the output format to which it
applies, so <code>--graph:factored</code> applies only
when <code>--output=graph</code> is being used; it has no effect if
@@ -1233,9 +1233,9 @@
Caveat: in some corner cases, there may be two distinct targets with
the same label; for example, a <code>sh_binary</code> rule and its
sole (implicit) <code>srcs</code> file may both be called
- <code>foo.sh</code>. If the result of a query contains both of
+ <code>foo.sh</code>. If the result of a query contains both of
these targets, the output (in <code>label</code> format) will appear
- to contain a duplicate. When using the <code>label_kind</code> (see
+ to contain a duplicate. When using the <code>label_kind</code> (see
below) format, the distinction becomes clear: the two targets have
the same name, but one has kind <code>sh_binary rule</code> and the
other kind <code>source file</code>.
@@ -1267,19 +1267,19 @@
There are two variants of this format: <code>minrank</code> ranks
each node by the length of the shortest path from a root node to it.
"Root" nodes (those which have no incoming edges) are of rank 0,
- their successors are of rank 1, etc. (As always, edges point from a
+ their successors are of rank 1, etc. (As always, edges point from a
target to its prerequisites: the targets it depends upon.)
</p>
<p>
<code>maxrank</code> ranks each node by the length of the longest
- path from a root node to it. Again, "roots" have rank 0, all other
+ path from a root node to it. Again, "roots" have rank 0, all other
nodes have a rank which is one greater than the maximum rank of all
their predecessors.
</p>
<p>
- All nodes in a cycle are considered of equal rank. (Most graphs are
+ All nodes in a cycle are considered of equal rank. (Most graphs are
acyclic, but cycles do occur
simply because BUILD files contain erroneous cycles.)
</p>
@@ -1290,7 +1290,7 @@
or <code>allpaths</code> query, then the rank number is equal to the
length of the shortest (with <code>minrank</code>) or longest
(with <code>maxrank</code>) path from <code>x</code> to a node in
- that rank. <code>maxrank</code> can be used to determine the
+ that rank. <code>maxrank</code> can be used to determine the
longest sequence of build steps required to build a target.
</p>
@@ -1346,7 +1346,7 @@
Like <code>label_kind</code>, this option prints out, for each
target in the result, the target's kind and label, but it is
prefixed by a string describing the location of that target, as a
- filename and line number. The format resembles the output of
+ filename and line number. The format resembles the output of
<code>grep</code>. Thus, tools that can parse the latter (such as Emacs
or vi) can also use the query output to step through a series of
matches, allowing the Bazel query tool to be used as a
@@ -1355,11 +1355,11 @@
<p>
The location information varies by target kind (see the <a
- href='#kind'>kind</a> operator). For rules, the
+ href='#kind'>kind</a> operator). For rules, the
location of the rule's declaration within the BUILD file is printed.
For source files, the location of line 1 of the actual file is
- printed. For a generated file, the location of the rule that
- generates it is printed. (The query tool does not have sufficient
+ printed. For a generated file, the location of the rule that
+ generates it is printed. (The query tool does not have sufficient
information to find the actual location of the generated file, and
in any case, it might not exist if a build has not yet been
performed.)
@@ -1369,8 +1369,8 @@
<pre>--output package</pre>
<p>
This option prints the name of all packages to which
- some target in the result set belongs. The names are printed in
- lexicographical order; duplicates are excluded. Formally, this
+ some target in the result set belongs. The names are printed in
+ lexicographical order; duplicates are excluded. Formally, this
is a <em>projection</em> from the set of labels (package, target) onto
packages.
</p>
@@ -1390,7 +1390,7 @@
<pre>--output graph</pre>
<p>
This option causes the query result to be printed as a directed
- graph in the popular AT&T GraphViz format. Typically the
+ graph in the popular AT&T GraphViz format. Typically the
result is saved to a file, such as <code>.png</code> or <code>.svg</code>.
(If the <code>dot</code> program is not installed on your workstation, you
can install it using the command <code>sudo apt-get install graphviz</code>.)
@@ -1405,25 +1405,25 @@
</p>
<p>
- By default, the graph is rendered in a <em>factored</em> form. That is,
+ By default, the graph is rendered in a <em>factored</em> form. That is,
topologically-equivalent nodes are merged together into a single
- node with multiple labels. This makes the graph more compact
+ node with multiple labels. This makes the graph more compact
and readable, because typical result graphs contain highly
- repetitive patterns. For example, a <code>java_library</code> rule
+ repetitive patterns. For example, a <code>java_library</code> rule
may depend on hundreds of Java source files all generated by the
same <code>genrule</code>; in the factored graph, all these files
- are represented by a single node. This behavior may be disabled
+ are represented by a single node. This behavior may be disabled
with the <code>--nograph:factored</code> option.
</p>
<h4><code>--graph:node_limit <var>n</var></code></h4>
<p>
The option specifies the maximum length of the label string for a
- graph node in the output. Longer labels will be truncated; -1
- disables truncation. Due to the factored form in which graphs are
- usually printed, the node labels may be very long. GraphViz cannot
+ graph node in the output. Longer labels will be truncated; -1
+ disables truncation. Due to the factored form in which graphs are
+ usually printed, the node labels may be very long. GraphViz cannot
handle labels exceeding 1024 characters, which is the default value
- of this option. This option has no effect unless
+ of this option. This option has no effect unless
<code>--output=graph</code> is being used.
</p>
@@ -1432,9 +1432,9 @@
By default, graphs are displayed in factored form, as explained
<a href='#output-graph'>above</a>.
When <code>--nograph:factored</code> is specified, graphs are
- printed without factoring. This makes visualization using GraphViz
+ printed without factoring. This makes visualization using GraphViz
impractical, but the simpler format may ease processing by other
- tools (e.g. grep). This option has no effect
+ tools (e.g. grep). This option has no effect
unless <code>--output=graph</code> is being used.
</p>
@@ -1442,7 +1442,7 @@
<pre>--output xml</pre>
<p>
This option causes the resulting targets to be printed in an XML
- form. The output starts with an XML header such as this
+ form. The output starts with an XML header such as this
</p>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
@@ -1533,7 +1533,7 @@
By default, XML output does not include rule attribute whose value
is the default value for that kind of attribute (e.g. because it
were not specified in the BUILD file, or the default value was
- provided explicitly). This option causes such attribute values to
+ provided explicitly). This option causes such attribute values to
be included in the XML output.
</p>
diff --git a/site/docs/remote-execution-caching-debug.md b/site/docs/remote-execution-caching-debug.md
index 3a6f336..583fa04 100644
--- a/site/docs/remote-execution-caching-debug.md
+++ b/site/docs/remote-execution-caching-debug.md
@@ -48,7 +48,7 @@
3. Run the build(s) and test(s) that you are investigating again (on the same
machine).
-4. Check the `INFO` line for cache hit rate. If you see no processes except
+4. Check the `INFO` line for cache hit rate. If you see no processes except
`remote cache hit`, then your cache is being correctly populated and
accessed. In that case, skip to the next section.
diff --git a/site/docs/test-encyclopedia.html b/site/docs/test-encyclopedia.html
index 46d913a..0faf2f5 100644
--- a/site/docs/test-encyclopedia.html
+++ b/site/docs/test-encyclopedia.html
@@ -27,16 +27,16 @@
<h2>Objective</h2>
<p>The goal of this page is to formally establish the runtime environment
-for and expected behavior of Bazel tests. It will also impose requirements on
+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
+implementation changes. We will also take the opportunity to tighten up some
holes which 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
+<p>This page is intended to be both normative and authoritative. If
this specification and the implemented behavior of test runner disagree, the
specification takes precedence.</p>
@@ -49,11 +49,11 @@
<h2>Purpose of tests</h2>
<p>The purpose of Bazel tests is to confirm some property of the source files
-checked into the repository. (On this page, "source files" includes test data,
-golden outputs, and anything else kept under version control.) One
+checked into the repository. (On this page, "source files" includes test data,
+golden outputs, and anything else kept under version control.) One
user writes a test to assert an invariant which they expect to be maintained.
Other users execute the test later to check whether the invariant has been
-broken. If the test depends on any variables other than source files
+broken. If the test depends on any variables other than source files
(non-hermetic), its value is diminished, because the later users cannot be sure
their changes are at fault when the test stops passing.</p>
@@ -70,14 +70,14 @@
<h2>Role of the build system</h2>
<p>Test rules are analogous to binary rules in that each must yield an
-executable program. For some languages, this is a stub program which combines
-a language-specific harness with the test code. Test rules must produce other
-outputs as well. In addition to the primary test executable, the test runner
+executable program. For some languages, this is a stub program which combines
+a language-specific harness with the test code. Test rules must produce other
+outputs as well. In addition to the primary test executable, the test runner
will need a manifest of <b>runfiles</b>, input files which should be made
available to the test at runtime, and it may need information about the type,
size, and tags of a test.</p>
-<p>The build system may use the runfiles to deliver code as well as data. (This
+<p>The build system may use the runfiles to deliver code as well as data. (This
might be used as an optimization to make each test binary smaller by sharing
files across tests, e.g. through the use of dynamic linking.) The build system
should ensure that the generated executable loads these files via the runfiles
@@ -87,18 +87,18 @@
<h2>Role of the test runner</h2>
<p>From the point of view of the test runner, each test is a program which can
-be invoked with <code>execve()</code>. There may be other ways to execute
+be invoked with <code>execve()</code>. There may be other ways to execute
tests; for example, an IDE might allow the execution of Java tests in-process.
However, the result of running the test as a standalone process must be
-considered authoritative. If a test process runs to completion and terminates
-normally with an exit code of zero, the test has passed. Any other result is
-considered a test failure. In particular, writing any of the strings
+considered authoritative. If a test process runs to completion and terminates
+normally with an exit code of zero, the test has passed. Any other result is
+considered a test failure. In particular, writing any of the strings
<code>PASS</code> or <code>FAIL</code> to stdout has no significance to the test
runner.</p>
<p>If a test takes too long to execute, exceeds some resource limit, or the test
runner otherwise detects prohibited behavior, it may choose to kill the test
-and treat the run as a failure. The runner must not report the test as passing
+and treat the run as a failure. The runner must not report the test as passing
after sending a signal to the test process or any children thereof.</p>
<p id="timeout">The whole test target (not individual methods or tests) is given a
@@ -150,7 +150,7 @@
<p>All combinations of <code>size</code> and <code>timeout</code> labels are
legal, so an "enormous" test may be declared to have a timeout of "short".
Presumably it would do some really horrible things very quickly.</p>
-<p>Tests may return arbitrarily fast regardless of timeout. A test is not
+<p>Tests may return arbitrarily fast regardless of timeout. A test is not
penalized for an overgenerous timeout, although a warning may be issued: you
should generally set your timeout as tight as you can without incurring any
flakiness.</p>
@@ -185,8 +185,8 @@
<p>If the main process of a test exits, but some of its children are still
running, the test runner should consider the run complete and count it as a
-success or failure based on the exit code observed from the main process. The
-test runner may kill any stray processes. Tests should not leak processes in
+success or failure based on the exit code observed from the main process. The
+test runner may kill any stray processes. Tests should not leak processes in
this fashion.</p>
<h2 id="test-sharding">Test sharding</h2>
@@ -214,7 +214,7 @@
conditions.</p>
<p>The test runner must invoke each test with the path to the test
-executable in <code>argv[0]</code>. This path must be relative and
+executable in <code>argv[0]</code>. This path must be relative and
beneath the test's current directory (which is in the runfiles tree,
see below).
The test runner should not pass any other arguments to a
@@ -288,29 +288,29 @@
</tbody>
</table>
<br>
-<p>The environment may contain additional entries. Tests should not depend on the
+<p>The environment may contain additional entries. Tests should not depend on the
presence, absence, or value of any environment variable not listed above.</p>
<p>The initial working directory shall be <code>$TEST_SRCDIR/$TEST_WORKSPACE</code>.</p>
<p> The current process id, process group id, session id, and parent process
-id are unspecified. The process may or may not be a process group leader or a
-session leader. The process may or may not have a controlling terminal. The
-process may have zero or more running or unreaped child processes. The process
+id are unspecified. The process may or may not be a process group leader or a
+session leader. The process may or may not have a controlling terminal. The
+process may have zero or more running or unreaped child processes. The process
should not have multiple threads when the test code gains control.</p>
<p>File descriptor 0 (stdin) shall be open for reading, but what it is attached
-to is unspecified. Tests must not read from it. File descriptors 1 (stdout)
+to is unspecified. Tests must not read from it. File descriptors 1 (stdout)
and 2 (stderr) shall be open for writing, but what they are attached to is
-unspecified. It could be a terminal, a pipe, a regular file, or anything else
-to which characters can be written. They may share an entry in the open file
-table (meaning that they cannot seek independently). Tests should not inherit
+unspecified. It could be a terminal, a pipe, a regular file, or anything else
+to which characters can be written. They may share an entry in the open file
+table (meaning that they cannot seek independently). Tests should not inherit
any other open file descriptors.</p>
<p>The initial umask shall be 022 or 027.</p>
<p>No alarm or interval timer shall be pending.</p>
-<p>The initial mask of blocked signals shall be empty. All signals shall be set
+<p>The initial mask of blocked signals shall be empty. All signals shall be set
to their default action.</p>
<p>The initial resource limits, both soft and hard, should be set as follows:</p>
@@ -368,16 +368,16 @@
<p>The users root, nobody, and unittest must exist. The groups root, nobody,
and eng must exist.</p>
-<p>Tests must be executed as a non-root user. The real and effective user ids
-must be equal; likewise for group ids. Beyond this, the current user id, group
-id, user name, and group name are unspecified. The set of supplementary group
+<p>Tests must be executed as a non-root user. The real and effective user ids
+must be equal; likewise for group ids. Beyond this, the current user id, group
+id, user name, and group name are unspecified. The set of supplementary group
ids is unspecified.</p>
<p>The current user id and group id must have corresponding names which can be
-retrieved with <code>getpwuid()</code> and <code>getgrgid()</code>. The same
+retrieved with <code>getpwuid()</code> and <code>getgrgid()</code>. The same
may not be true for supplementary group ids.</p>
-<p>The current user must have a home directory. It may not be writable. Tests
+<p>The current user must have a home directory. It may not be writable. Tests
must not attempt to write to it.</p>
<h4>Networking</h4>
@@ -463,12 +463,12 @@
may fail).</p>
<p>The runfiles tree (including paths which traverse symlinks) must not change
-during test execution. Parent directories and filesystem mounts must not change
+during test execution. Parent directories and filesystem mounts must not change
in any way which affects the result of resolving a path within the runfiles
tree.</p>
<p>In order to catch early exit, a test may create a file at the path specified by
-<code>TEST_PREMATURE_EXIT_FILE</code> upon start and remove it upon exit. If
+<code>TEST_PREMATURE_EXIT_FILE</code> upon start and remove it upon exit. If
Bazel sees the file when the test finishes, it will assume that the test exited
prematurely and mark it as having failed.</p>
