From ec7ecd74705ceadc064fd21aea6c04b0a0f749e4 Mon Sep 17 00:00:00 2001 From: Googler Date: Fri, 19 Mar 2021 16:20:52 -0700 Subject: [PATCH] Docs: Rewrite Bazel pages to clarify intended user: Tutorials, part7 PiperOrigin-RevId: 363992464 --- site/docs/tutorial/android-app.md | 12 ++-- site/docs/tutorial/cc-toolchain-config.md | 77 ++++++++++++----------- site/docs/tutorial/cpp.md | 34 +++++----- site/docs/tutorial/ios-app.md | 4 +- site/docs/tutorial/java.md | 31 ++++----- 5 files changed, 81 insertions(+), 77 deletions(-) diff --git a/site/docs/tutorial/android-app.md b/site/docs/tutorial/android-app.md index db0637f1d718ec..36be5b4c75bf47 100644 --- a/site/docs/tutorial/android-app.md +++ b/site/docs/tutorial/android-app.md @@ -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. @@ -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. ``` . @@ -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 diff --git a/site/docs/tutorial/cc-toolchain-config.md b/site/docs/tutorial/cc-toolchain-config.md index 3c0103af092341..5502f2bf1dca39 100644 --- a/site/docs/tutorial/cc-toolchain-config.md +++ b/site/docs/tutorial/cc-toolchain-config.md @@ -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: @@ -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 @@ -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: @@ -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") @@ -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): @@ -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") @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/site/docs/tutorial/cpp.md b/site/docs/tutorial/cpp.md index 9ade206c0e344d..4367ebf87aa80d 100644 --- a/site/docs/tutorial/cpp.md +++ b/site/docs/tutorial/cpp.md @@ -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: @@ -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)" \ @@ -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 @@ -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 @@ -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: ``` @@ -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: ``` @@ -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: @@ -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: ``` diff --git a/site/docs/tutorial/ios-app.md b/site/docs/tutorial/ios-app.md index cf1ac03df0fac2..55329e46f65727 100644 --- a/site/docs/tutorial/ios-app.md +++ b/site/docs/tutorial/ios-app.md @@ -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 diff --git a/site/docs/tutorial/java.md b/site/docs/tutorial/java.md index 120c9b93992df6..bb47db02ddeae7 100644 --- a/site/docs/tutorial/java.md +++ b/site/docs/tutorial/java.md @@ -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: @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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