Skip to content

Commit

Permalink
Docs: Rewrite Bazel pages to clarify intended user: Tutorials, part7
Browse files Browse the repository at this point in the history 
PiperOrigin-RevId: 363992464
  • Loading branch information
@copybara-github
Googler authored and copybara-github committed Mar 19, 2021
1 parent b01fc82 commit ec7ecd7
Show file tree
Hide file tree
Showing 5 changed files with 81 additions and 77 deletions.
12 changes: 6 additions & 6 deletions site/docs/tutorial/android-app.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,18 +34,18 @@ In this tutorial you learn how to:

### 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.

Expand All @@ -64,7 +64,7 @@ the rest of the tutorial, you will be executing commands in this directory.

### 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.

```
.
Expand Down Expand Up @@ -308,7 +308,7 @@ Now, save and close the file.

### 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
Expand Down
77 changes: 39 additions & 38 deletions site/docs/tutorial/cc-toolchain-config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,9 @@ with `clang`

### 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:

Expand Down Expand Up @@ -71,23 +70,24 @@ Set up your build environment as follows:
```

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

Expand Down Expand Up @@ -139,7 +139,7 @@ slightly between different versions of clang.

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:

Expand Down Expand Up @@ -190,7 +190,7 @@ slightly between different versions of clang.
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")
Expand All @@ -203,10 +203,10 @@ slightly between different versions of clang.
'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):
Expand All @@ -230,9 +230,8 @@ slightly between different versions of clang.
```

`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")
Expand All @@ -256,8 +255,8 @@ slightly between different versions of clang.

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
Expand Down Expand Up @@ -327,8 +326,8 @@ slightly between different versions of clang.
....
```
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
Expand Down Expand Up @@ -361,11 +360,13 @@ slightly between different versions of clang.
/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
Expand Down Expand Up @@ -480,14 +481,14 @@ The key take-aways are:
- 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

Expand Down
34 changes: 18 additions & 16 deletions site/docs/tutorial/cpp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,16 +125,16 @@ source file(s) from which Bazel builds the target.

### 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:
Expand Down Expand Up @@ -162,8 +162,9 @@ A successful build has all of its dependencies explicitly stated in the `BUILD`
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)" \
Expand Down Expand Up @@ -196,8 +197,8 @@ that builds a single source file with no additional dependencies:

![Dependency graph for 'hello-world'](/assets/cpp-tutorial-stage1.png)

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

Expand All @@ -208,7 +209,7 @@ building multiple parts of a project at once.

### 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
Expand All @@ -233,7 +234,7 @@ then the `hello-world` binary. The `deps` attribute in the `hello-world` target
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:

```
Expand Down Expand Up @@ -269,7 +270,7 @@ builds two additional source files.

### 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:

```
Expand All @@ -285,8 +286,9 @@ of the `cpp-tutorial/stage3` directory:
│ └── 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:

Expand Down Expand Up @@ -325,13 +327,13 @@ at the dependency graph:

![Dependency graph for 'hello-world'](/assets/cpp-tutorial-stage3.png)

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:

```
Expand Down
4 changes: 2 additions & 2 deletions site/docs/tutorial/ios-app.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -171,8 +171,8 @@ following load statement to the beginning of your `BUILD` file:
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

Expand Down
31 changes: 16 additions & 15 deletions site/docs/tutorial/java.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,15 +128,15 @@ instead of listing them one by one.)

### 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:
Expand Down Expand Up @@ -165,8 +165,9 @@ Bazel requires build dependencies to be explicitly declared in BUILD files.
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
Expand All @@ -184,8 +185,8 @@ no additional dependencies:

![Dependency graph of the target 'ProjectRunner'](/assets/tutorial_java_01.svg)

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

Expand All @@ -196,7 +197,7 @@ building multiple parts of a project at once.

### 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
Expand All @@ -217,7 +218,7 @@ With this configuration, Bazel first builds the `greeter` library, then the
`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
Expand Down Expand Up @@ -277,8 +278,8 @@ Take a look at the dependency graph:

![Dependency graph of the target 'runner'](/assets/tutorial_java_03.svg)

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
Expand All @@ -295,8 +296,8 @@ java_library(
)
```

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
Expand Down

0 comments on commit ec7ecd7

Please sign in to comment.