Docs: Rewrite Bazel pages to clarify intended user, Part 2
PiperOrigin-RevId: 359870355
diff --git a/site/docs/cpp-use-cases.md b/site/docs/cpp-use-cases.md
index 25fb63f..a58253f 100644
--- a/site/docs/cpp-use-cases.md
+++ b/site/docs/cpp-use-cases.md
@@ -121,15 +121,15 @@
Google Test has several "special" requirements that make its `cc_library` rule
more complicated:
-* `googletest-release-1.7.0/src/gtest-all.cc` `#include`s all of the other
- files in `googletest-release-1.7.0/src/`, so we need to exclude it from the
- compile or we'll get link errors for duplicate symbols.
+* `googletest-release-1.7.0/src/gtest-all.cc` `#include`s all other
+ files in `googletest-release-1.7.0/src/`: exclude it from the
+ compile to prevent link errors for duplicate symbols.
* It uses header files that are relative to the
-`googletest-release-1.7.0/include/` directory (`"gtest/gtest.h"`), so we must
+`googletest-release-1.7.0/include/` directory (`"gtest/gtest.h"`), so you must
add that directory to the include paths.
-* It needs to link in `pthread`, so we add that as a `linkopt`.
+* It needs to link in `pthread`, so add that as a `linkopt`.
The final rule therefore looks like this:
@@ -192,7 +192,7 @@
## Writing and running C++ tests
-For example, we could create a test `./test/hello-test.cc` such as:
+For example, you could create a test `./test/hello-test.cc`, such as:
```cpp
#include "gtest/gtest.h"
@@ -217,7 +217,7 @@
)
```
-Note that in order to make `hello-greet` visible to `hello-test`, we have to add
+To make `hello-greet` visible to `hello-test`, you must add
`"//test:__pkg__",` to the `visibility` attribute in `./main/BUILD`.
Now you can use `bazel test` to run the test.
diff --git a/site/docs/cquery.html b/site/docs/cquery.html
index d9ec85e..b0d2f9e 100644
--- a/site/docs/cquery.html
+++ b/site/docs/cquery.html
@@ -324,8 +324,8 @@
<code>--universe_scope</code> could prevent building targets multiple times in
configurations you don't care about. It could also help specify which configuration version of a
target you're looking for (since it's not currently possible
- to fully specify this any other way). We recommend that you set this
- flag if your query expression is more complex than <code>deps(//foo)</code>.
+ to fully specify this any other way). You should set this flag
+ if your query expression is more complex than <code>deps(//foo)</code>.
</p>
<h4><code>--implicit_deps</code> (boolean, default=True)</h4>
@@ -696,7 +696,7 @@
</p>
<p>
- We can see the lingering effects of that transition below.
+ You can see the lingering effects of that transition below.
</p>
<pre>
diff --git a/site/docs/guide.md b/site/docs/guide.md
index 76b36cb..40bb606 100644
--- a/site/docs/guide.md
+++ b/site/docs/guide.md
@@ -101,10 +101,10 @@
INFO: Build completed successfully, 1 total action
```
-We see a "null" build: in this case, there are no packages to re-load, since
-nothing has changed, and no build steps to execute. (If something had changed in
+You see a "null" build: in this case, there are no packages to reload, since
+nothing changed, and no build steps to execute. (If something changed in
"foo" or some of its dependencies, resulting in the re-execution of some build
-actions, we would call it an "incremental" build, not a "null" build.)
+actions, you would call it an "incremental" build, not a "null" build.)
Before you can start a build, you will need a Bazel workspace. This is simply a
directory tree that contains all the source files needed to build your
diff --git a/site/docs/install-compile-source.md b/site/docs/install-compile-source.md
index 2848357..6b834da 100644
--- a/site/docs/install-compile-source.md
+++ b/site/docs/install-compile-source.md
@@ -179,7 +179,7 @@
2. Unpack the distribution archive somewhere on disk.
- We recommend to also verify the signature made by our
+ You should verify the signature made by Bazel's
[release key](https://bazel.build/bazel-release.pub.gpg) 3D5919B448457EE0.
<h3 id="bootstrap-unix">Step 2a: Bootstrap Bazel on Ubuntu Linux, macOS, and other Unix-like systems</h3>
@@ -216,8 +216,8 @@
The compiled output is placed into `output/bazel`. This is a self-contained
Bazel binary, without an embedded JDK. You can copy it anywhere or use it
-in-place. For convenience we recommend copying this binary to a directory that's
-on your `PATH` (such as `/usr/local/bin` on Linux).
+in-place. For convenience, copy this binary to a directory that's on your
+`PATH` (such as `/usr/local/bin` on Linux).
To build the `bazel` binary in a reproducible way, also set
[`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/)
@@ -287,8 +287,8 @@
The compiled output is placed into `output/bazel.exe`. This is a self-contained
Bazel binary, without an embedded JDK. You can copy it anywhere or use it
-in-place. For convenience we recommend copying this binary to a directory that's
-on your `PATH`.
+in-place. For convenience, copy this binary to a directory that's on
+your `PATH`.
To build the `bazel.exe` binary in a reproducible way, also set
[`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/)
diff --git a/site/docs/install-os-x.md b/site/docs/install-os-x.md
index 238e890..32ec4d2 100644
--- a/site/docs/install-os-x.md
+++ b/site/docs/install-os-x.md
@@ -66,8 +66,8 @@
curl -fLO "https://github.com/bazelbuild/bazel/releases/download/${BAZEL_VERSION}/bazel-${BAZEL_VERSION}-installer-darwin-x86_64.sh"
```
-This is a temporary workaround until we fix notarization in our macOS release
-workflow ([#9304](https://github.com/bazelbuild/bazel/issues/9304)).
+This is a temporary workaround until the macOS release flow supports
+notarization ([#9304](https://github.com/bazelbuild/bazel/issues/9304)).
### Step 3: Run the installer
diff --git a/site/docs/install-ubuntu.md b/site/docs/install-ubuntu.md
index e53eb05..52b34fe 100644
--- a/site/docs/install-ubuntu.md
+++ b/site/docs/install-ubuntu.md
@@ -15,9 +15,8 @@
* 18.04 (LTS)
* 16.04 (LTS)
-Bazel will probably work fine on other Ubuntu releases and Debian stretch and
-above, but we currently do not test this on Bazel's CI and thus can't promise
-it.
+Bazel should be compatible with other Ubuntu releases and Debian
+"stretch" and above, but is untested and not guaranteed to work.
Install Bazel on Ubuntu using one of the following methods:
@@ -48,12 +47,12 @@
echo "deb [arch=amd64] https://storage.googleapis.com/bazel-apt stable jdk1.8" | sudo tee /etc/apt/sources.list.d/bazel.list
```
-The component name "jdk1.8" is kept for legacy reasons only and doesn't relate
-to supported or included JDK versions anymore. In the past, when Bazel did not
-yet bundle a private JRE, we had two release versions, one compatible with JDK 7
-and one with JDK 8. However, since we dropped Java 7 support and started
-bundling a private runtime, Bazel releases are Java version agnostic. Changing
-the "jdk1.8" component name would break existing users of the repo though.
+The component name "jdk1.8" is kept only for legacy reasons and doesn't relate
+to supported or included JDK versions. In the past, when Bazel did not
+yet bundle a private JRE, there were two release versions, one compatible with
+JDK 7 and one with JDK 8. However, since Java 7 support stopped and
+bundling a private runtime started, Bazel releases are Java version agnostic.
+Changing the "jdk1.8" component name would break existing users of the repo.
### Step 2: Install and update Bazel
@@ -104,9 +103,9 @@
<h2 id="install-with-installer-ubuntu">Using the binary installer</h2>
-While we generally recommend to use the apt repository, the binary installer can
-be useful in case you don't have admin permissions on your machine or can't add
-custom repositories.
+Generally, you should use the apt repository, but the binary installer
+can be useful if you don't have admin permissions on your machine or
+can't add custom repositories.
The binary installers can be downloaded from Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
diff --git a/site/docs/integrating-with-rules-cc.md b/site/docs/integrating-with-rules-cc.md
index fbed051..cf6a572e 100644
--- a/site/docs/integrating-with-rules-cc.md
+++ b/site/docs/integrating-with-rules-cc.md
@@ -12,8 +12,8 @@
Because of
[ongoing migration of C++ rules](https://github.com/bazelbuild/bazel/issues/6516)
to [platforms](https://docs.bazel.build/versions/master/platforms.html) and
-[toolchains](https://docs.bazel.build/versions/master/toolchains.html), we
-advise to use the helper function available at
+[toolchains](https://docs.bazel.build/versions/master/toolchains.html), you
+should use the helper function available at
[@bazel_tools//tools/cpp:toolchain_utils.bzl](https://source.bazel.build/bazel/+/master:tools/cpp/toolchain_utils.bzl;l=23),
which works both when toolchains are disabled and enabled. To depend on a C++
toolchain in your rule, add a
@@ -81,6 +81,6 @@
## Reusing logic and actions of C++ rules
-_Not stable yet, we will update this section once the API stabilizes. Follow
-[#4570](https://github.com/bazelbuild/bazel/issues/4570) for up to date
+_Not stable yet; This section will be updated once the API stabilizes. Follow
+[#4570](https://github.com/bazelbuild/bazel/issues/4570) for up-to-date
information._
diff --git a/site/docs/migrate-maven.md b/site/docs/migrate-maven.md
index 7d292b4..8f44604 100644
--- a/site/docs/migrate-maven.md
+++ b/site/docs/migrate-maven.md
@@ -65,10 +65,10 @@
#### <a name="guava-1"></a>Guava project example: external dependencies
-Using the
+You can list the external dependencies of the
+[Guava project](https://github.com/google/guava) with the
[`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external)
-ruleset, we can list the external dependencies of the
-[Guava project](https://github.com/google/guava).
+ruleset.
Add the following snippet to the `WORKSPACE` file:
@@ -160,8 +160,8 @@
)
```
* Specify the attributes:
- * `name`: Give the target a meaningful name. In the examples above
- we call the target "everything."
+ * `name`: Give the target a meaningful name. In the examples above,
+ the target is called "everything."
* `srcs`: Use globbing to list all .java files in your project.
* `resources`: Use globbing to list all resources in your project.
* `deps`: You need to determine which external dependencies your
diff --git a/site/docs/mobile-install.md b/site/docs/mobile-install.md
index 112d559..99b32e6 100644
--- a/site/docs/mobile-install.md
+++ b/site/docs/mobile-install.md
@@ -58,7 +58,7 @@
## Problems with traditional app installation
-We identified the following bottlenecks of building an Android app:
+Building an Android app has some issues, including:
- Dexing. By default, "dx" is invoked exactly once in the build and it does not
know how to reuse work from previous builds: it dexes every method again, even
@@ -110,8 +110,8 @@
alphabetically, then cut the list up into equal-sized parts, but this proved to
be suboptimal: if a class was added or removed (even a nested or an anonymous
one), it would cause all the classes alphabetically after it to shift by one,
-resulting in dexing those shards again. Thus, we settled upon sharding not
-individual classes, but Java packages instead. Of course, this still results in
+resulting in dexing those shards again. Thus, it was decided to shard Java
+packages rather than individual classes. Of course, this still results in
dexing many shards if a new package is added or removed, but that is much less
frequent than adding or removing a single class.
@@ -147,8 +147,8 @@
be uploaded.
Note that it is possible to fool the incremental installation algorithm by
-changing a file on the device, but not its checksum in the manifest. We could
-have safeguarded against this by computing the checksum of the files on the
+changing a file on the device, but not its checksum in the manifest. This could
+have been safeguarded against by computing the checksum of the files on the
device, but this was deemed to be not worth the increase in installation time.
### The Stub application
@@ -188,8 +188,9 @@
### Performance
In general, `bazel mobile-install` results in a 4x to 10x speedup of building
-and installing large apps after a small change. We computed the following
-numbers for a few Google products:
+and installing large apps after a small change.
+
+The following numbers were computed for a few Google products:
<img src="/assets/mobile-install-performance.svg"/>
@@ -198,8 +199,8 @@
### Limitations
-The tricks the stub application plays don't work in every case. We have
-identified the following cases where it does not work as expected:
+The tricks the stub application plays don't work in every case.
+The following cases highlight where it does not work as expected:
- When `Context` is cast to the `Application` class in
`ContentProvider#onCreate()`. This method is called during application
