Docs: Rewrite Bazel pages to clarify intended user: Tutorials, part7
PiperOrigin-RevId: 363992464
diff --git a/site/docs/tutorial/android-app.md b/site/docs/tutorial/android-app.md
index db0637f..36be5b4 100644
--- a/site/docs/tutorial/android-app.md
+++ b/site/docs/tutorial/android-app.md
@@ -34,18 +34,18 @@
### Install Bazel
-You will need to install the following software:
+Before you begin the tutorial, install the following software:
* **Bazel.** To install, follow the [installation instructions](../install.md).
* **Android Studio.** To install, follow the steps to [download Android
Studio](https://developer.android.com/sdk/index.html). Execute the setup
wizard to download the SDK and configure your environment.
-* (Optional) **Git.** We will use `git` to download the Android app project.
+* (Optional) **Git.** Use `git` to download the Android app project.
### Get the sample project
-We will be using a basic Android app project in [Bazel's examples
-repository](https://github.com/bazelbuild/examples).
+For the sample project, use a basic Android app project in
+[Bazel's examples repository](https://github.com/bazelbuild/examples).
This app has a single button that prints a greeting when clicked.
@@ -64,7 +64,7 @@
### Review the source files
-Let's take a look at the source files for the app.
+Take a look at the source files for the app.
```
.
@@ -308,7 +308,7 @@
### Build the app
-Let's try building the app! Run the following command to build the
+Try building the app! Run the following command to build the
`android_binary` target:
```bash
diff --git a/site/docs/tutorial/cc-toolchain-config.md b/site/docs/tutorial/cc-toolchain-config.md
index 3c0103a..5502f2b 100644
--- a/site/docs/tutorial/cc-toolchain-config.md
+++ b/site/docs/tutorial/cc-toolchain-config.md
@@ -28,10 +28,9 @@
### Set up the build environment
-This tutorial assumes you are on Linux on which you have successfully built
-C++ applications - in other words, we assume that appropriate tooling and
-libraries have been installed. The tutorial uses `clang version 9.0.1` which you
-can install on your system.
+This tutorial assumes you are on Linux and have successfully built
+C++ applications and installed the appropriate tooling and libraries.
+The tutorial uses `clang version 9.0.1`, which you can install on your system.
Set up your build environment as follows:
@@ -71,23 +70,24 @@
```
For an entry `build:{config_name} --flag=value`, the command line flag
-`--config={config_name}` will be associated with that particular flag. See
+`--config={config_name}` is associated with that particular flag. See
documentation for the flags used:
[crosstool_top](../user-manual.html#flag--crosstool_top),
[cpu](../user-manual.html#flag--cpu) and
[host_crosstool_top](../user-manual.html#flag--host_crosstool_top).
-What this means is that when we build our [target](../build-ref.html#targets)
-with `bazel build --config=clang_config //main:hello-world` Bazel will use our
+When you build your [target](../build-ref.html#targets)
+with `bazel build --config=clang_config //main:hello-world`, Bazel uses your
custom toolchain from the
[cc_toolchain_suite](../be/c-cpp.html#cc_toolchain_suite)
-`//toolchain:clang_suite`. The suite may list different [toolchains](../be/c-cpp.html#cc_toolchain)
-for different CPUs, that's why we differentiate with the flag `--cpu=k8`.
+`//toolchain:clang_suite`. The suite may list different
+[toolchains](../be/c-cpp.html#cc_toolchain) for different CPUs,
+and that's why it is differentiated with the flag `--cpu=k8`.
-Since Bazel uses many internal tools written in
-C++ during the build, such as process-wrapper, we are specifying the
-pre-existing default C++ toolchain for the host platform, so that these tools
-are built using that toolchain instead of the one created in this tutorial.
+Because Bazel uses many internal tools written in C++ during the build, such as
+process-wrapper, the pre-existing default C++ toolchain is specified for
+the host platform, so that these tools are built using that toolchain instead of
+the one created in this tutorial.
## Configuring the C++ toolchain
@@ -139,7 +139,7 @@
Bazel discovered that the `--crosstool_top` flag points to a rule that
doesn't provide the necessary [`ToolchainInfo`](../skylark/lib/ToolchainInfo.html)
- provider. So we need to point `--crosstool_top` to a rule that does provide
+ provider. So you need to point `--crosstool_top` to a rule that does provide
`ToolchainInfo` - that is the `cc_toolchain_suite` rule. In the
`toolchain/BUILD` file, replace the empty filegroup with the following:
@@ -190,7 +190,7 @@
Rule '//toolchain:k8_toolchain_config' does not exist
```
- Let's add a ":k8_toolchain_config" target to the `toolchain/BUILD` file:
+ Next, add a ":k8_toolchain_config" target to the `toolchain/BUILD` file:
```python
filegroup(name = "k8_toolchain_config")
@@ -203,10 +203,10 @@
'CcToolchainConfigInfo'
```
- `CcToolchainConfigInfo` is a provider that we use to configure our C++
- toolchains. We are going to create a Starlark rule that will provide
- `CcToolchainConfigInfo`. Create a `toolchain/cc_toolchain_config.bzl`
- file with the following content:
+ `CcToolchainConfigInfo` is a provider that you use to configure
+ your C++ toolchains. To fix this error, create a Starlark rule
+ that provides `CcToolchainConfigInfo` to Bazel by making a
+ `toolchain/cc_toolchain_config.bzl` file with the following content:
```python
def _impl(ctx):
@@ -230,9 +230,8 @@
```
`cc_common.create_cc_toolchain_config_info()` creates the needed provider
- `CcToolchainConfigInfo`. Now let's declare a rule that will make use of
- the newly implemented `cc_toolchain_config` rule. Add a load statement to
- `toolchains/BUILD`:
+ `CcToolchainConfigInfo`. To use the `cc_toolchain_config` rule, add a load
+ statement to `toolchains/BUILD`:
```python
load(":cc_toolchain_config.bzl", "cc_toolchain_config")
@@ -256,8 +255,8 @@
At this point, Bazel has enough information to attempt building the code but
it still does not know what tools to use to complete the required build
- actions. We will modify our Starlark rule implementation to tell Bazel what
- tools to use. For that, we'll need the tool_path() constructor from
+ actions. You will modify the Starlark rule implementation to tell Bazel what
+ tools to use. For that, you need the tool_path() constructor from
[`@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl`](https://source.bazel.build/bazel/+/4eea5c62a566d21832c93e4c18ec559e75d5c1ce:tools/cpp/cc_toolchain_config_lib.bzl;l=400):
```python
@@ -327,8 +326,8 @@
....
```
Bazel needs to know where to search for included headers. There are
- multiple ways to solve this like using the `includes` attribute of
- `cc_binary`, but here we will solve it at the toolchain level with the
+ multiple ways to solve this, such as using the `includes` attribute of
+ `cc_binary`, but here this is solved at the toolchain level with the
[`cxx_builtin_include_directories`](../skylark/lib/cc_common.html#create_cc_toolchain_config_info)
parameter of `cc_common.create_cc_toolchain_config_info`. Beware that if
you are using a different version of `clang`, the include path will be
@@ -361,11 +360,13 @@
/usr/bin/ld: bazel-out/k8-fastbuild/bin/main/_objs/hello-world/hello-world.o: in function `print_localtime()':
hello-world.cc:(.text+0x68): undefined reference to `std::cout'
```
- The reason for this is because the linker is missing the C++ standard library
- and it can't find its symbols. There are many ways to solve this, like using
- the `linkopts` attribute of `cc_binary`. Here we will solve it making sure
- that any target using our toolchain doesn't have to specify this flag. Copy
- the following code to `cc_toolchain_config.bzl`.
+ The reason for this is because the linker is missing the C++ standard
+ library and it can't find its symbols. There are many ways to solve this,
+ such as using the `linkopts` attribute of `cc_binary`. Here it is solved by
+ making sure that any target using the toolchain doesn't have to specify
+ this flag.
+
+ Copy the following code to `cc_toolchain_config.bzl`:
```python
# NEW
@@ -480,14 +481,14 @@
- The cc_toolchain_suite may list `cc_toolchains` for different CPUs and
compilers. You can use command line flags like `--cpu` to differentiate.
- You have to let the toolchain know where the tools live. In this tutorial
- we have a simplified version where we access the tools from the system. If you
- are interested in a more self-contained approach you can read about workspaces
- [here](../be/workspace.html). Your tools
- could come from a different workspace and you would have to make their files
- available to the `cc_toolchain` via target dependencies on attributes like
+ there is a simplified version where you access the tools from the system. If
+ you are interested in a more self-contained approach, you can read about
+ workspaces [here](../be/workspace.html). Your tools could come from a
+ different workspace and you would have to make their files available
+ to the `cc_toolchain` with target dependencies on attributes, such as
`compiler_files`. The `tool_paths` would need to be changed as well.
-- You can create features to customize which flags should be passed to different
- actions, be it linking or any other type of action.
+- You can create features to customize which flags should be passed to
+ different actions, be it linking or any other type of action.
## Further reading
diff --git a/site/docs/tutorial/cpp.md b/site/docs/tutorial/cpp.md
index 9ade206..4367ebf 100644
--- a/site/docs/tutorial/cpp.md
+++ b/site/docs/tutorial/cpp.md
@@ -125,16 +125,16 @@
### Build the project
-Let's build your sample project. Change into the `cpp-tutorial/stage1` directory
-and run the following command:
+To build your sample project, navigate to the `cpp-tutorial/stage1` directory
+and run:
```
bazel build //main:hello-world
```
-Notice the target label - the `//main:` part is the location of our `BUILD`
-file relative to the root of the workspace, and `hello-world` is what we named
-that target in the `BUILD` file. (You will learn about target labels in more
+In the target label, the `//main:` part is the location of the `BUILD`
+file relative to the root of the workspace, and `hello-world` is the target
+name in the `BUILD` file. (You will learn about target labels in more
detail at the end of this tutorial.)
Bazel produces output similar to the following:
@@ -162,8 +162,9 @@
file. Bazel uses those statements to create the project's dependency graph,
which enables accurate incremental builds.
-Let's visualize our sample project's dependencies. First, generate a text
-representation of the dependency graph (run the command at the workspace root):
+To visualize the sample project's dependencies, you can generate a text
+representation of the dependency graph by running this command at the
+workspace root:
```
bazel query --notool_deps --noimplicit_deps "deps(//main:hello-world)" \
@@ -196,8 +197,8 @@
-Now that you have set up your workspace, built your project, and examined its
-dependencies, let's add some complexity.
+After you set up your workspace, build your project, and examine its
+dependencies, then you can add some complexity.
## Refine your Bazel build
@@ -208,7 +209,7 @@
### Specify multiple build targets
-Let's split our sample project build into two targets. Take a look at the
+You can split the sample project build into two targets. Take a look at the
`BUILD` file in the `cpp-tutorial/stage2/main` directory:
```python
@@ -233,7 +234,7 @@
tells Bazel that the `hello-greet` library is required to build the `hello-world`
binary.
-Let's build this new version of our project. Change into the
+Next, build this new version of the project. Change into the
`cpp-tutorial/stage2` directory and run the following command:
```
@@ -269,7 +270,7 @@
### Use multiple packages
-Let's now split the project into multiple packages. Take a look at the contents
+You can split the project into multiple packages. Take a look at the contents
of the `cpp-tutorial/stage3` directory:
```
@@ -285,8 +286,9 @@
│ └── hello-time.h
└── WORKSPACE
```
-Notice that we now have two sub-directories, and each contains a `BUILD` file.
-Therefore, to Bazel, the workspace now contains two packages, `lib` and `main`.
+Notice that now there are two sub-directories, and each contains a `BUILD`
+file. Therefore, to Bazel, the workspace now contains two packages,
+`lib` and `main`.
Take a look at the `lib/BUILD` file:
@@ -325,13 +327,13 @@
-Notice that for the build to succeed, we make the `//lib:hello-time` target in
+Notice that for the build to succeed, you make the `//lib:hello-time` target in
`lib/BUILD` explicitly visible to targets in `main/BUILD` using the `visibility`
attribute. This is because by default targets are only visible to other targets
in the same `BUILD` file. (Bazel uses target visibility to prevent issues such
as libraries containing implementation details leaking into public APIs.)
-Let's build this final version of our project. Change into the
+Next you can build this final version of the project. Change into the
`cpp-tutorial/stage3` directory and run the following command:
```
diff --git a/site/docs/tutorial/ios-app.md b/site/docs/tutorial/ios-app.md
index cf1ac03..55329e4 100644
--- a/site/docs/tutorial/ios-app.md
+++ b/site/docs/tutorial/ios-app.md
@@ -171,8 +171,8 @@
load("@build_bazel_rules_apple//apple:ios.bzl", "ios_application")
```
-We only need to load the `ios_application` rule because the `objc_library` rule
-is built into the Bazel package.
+You only need to load the `ios_application` rule because the `objc_library`
+rule is built into the Bazel package.
### Add an objc_library rule
diff --git a/site/docs/tutorial/java.md b/site/docs/tutorial/java.md
index 120c9b9..bb47db0 100644
--- a/site/docs/tutorial/java.md
+++ b/site/docs/tutorial/java.md
@@ -128,15 +128,15 @@
### Build the project
-Let's build your sample project. Change into the `java-tutorial` directory
-and run the following command:
+To build your sample project, navigate to the `java-tutorial` directory
+and run:
```
bazel build //:ProjectRunner
```
-Notice the target label - the `//` part is the location of our `BUILD` file
-relative to the root of the workspace (in this case, the root itself), and
-`ProjectRunner` is what we named that target in the `BUILD` file. (You will
+In the target label, the `//` part is the location of the `BUILD` file
+relative to the root of the workspace (in this case, the root itself),
+and `ProjectRunner` is the target name in the `BUILD` file. (You will
learn about target labels in more detail at the end of this tutorial.)
Bazel produces output similar to the following:
@@ -165,8 +165,9 @@
Bazel uses those statements to create the project's dependency graph, which
enables accurate incremental builds.
-Let's visualize our sample project's dependencies. First, generate a text
-representation of the dependency graph (run the command at the workspace root):
+To visualize the sample project's dependencies, you can generate a text
+representation of the dependency graph by running this command at the
+workspace root:
```
bazel query --notool_deps --noimplicit_deps "deps(//:ProjectRunner)" --output graph
@@ -184,8 +185,8 @@
-Now that you have set up your workspace, built your project, and examined its
-dependencies, let's add some complexity.
+After you set up your workspace, build your project, and examine its
+dependencies, then you can add some complexity.
## Refine your Bazel build
@@ -196,7 +197,7 @@
### Specify multiple build targets
-Let's split our sample project build into two targets. Replace the contents of
+You can split the sample project build into two targets. Replace the contents of
the `java-tutorial/BUILD` file with the following:
```python
@@ -217,7 +218,7 @@
`ProjectRunner` binary. The `deps` attribute in `java_binary` tells Bazel that
the `greeter` library is required to build the `ProjectRunner` binary.
-Let's build this new version of our project. Run the following command:
+To build this new version of the project, run the following command:
```
bazel build //:ProjectRunner
@@ -277,8 +278,8 @@
-However, for the build to succeed, you must explicitly give the `runner` target in
-`//src/main/java/com/example/cmdline/BUILD` visibility to targets in
+However, for the build to succeed, you must explicitly give the `runner` target
+in `//src/main/java/com/example/cmdline/BUILD` visibility to targets in
`//BUILD` using the `visibility` attribute. This is because by default targets
are only visible to other targets in the same `BUILD` file. (Bazel uses target
visibility to prevent issues such as libraries containing implementation details
@@ -295,8 +296,8 @@
)
```
-Let's now build the new package. Run the following command at the root of the
-workspace:
+Now you can build the new package by running the following command at the root
+of the workspace:
```
bazel build //src/main/java/com/example/cmdline:runner
