Docs: Standardize tutorials for similar format, headings and layout
PiperOrigin-RevId: 345323395
diff --git a/site/docs/tutorial/android-app.md b/site/docs/tutorial/android-app.md
index 00de0c1..4e998c0 100644
--- a/site/docs/tutorial/android-app.md
+++ b/site/docs/tutorial/android-app.md
@@ -3,9 +3,9 @@
title: Build Tutorial - Android
---
-# Introduction to Bazel: Building an Android App
+# Bazel Tutorial: Build an Android App
-In this tutorial, you will learn how to build a simple Android app using Bazel.
+This tutorial covers how to build a simple Android app using Bazel.
Bazel supports building Android apps using the
[Android rules](../be/android.html).
@@ -14,7 +14,24 @@
require experience with Bazel or Android app development. You do not need to
write any Android code in this tutorial.
-## Prerequisites
+## What you'll learn
+
+In this tutorial you learn how to:
+
+* Set up your environment by installing Bazel and Android Studio, and
+ downloading the sample project.
+* Set up a Bazel [workspace](../be/workspace.md) that contains the source code
+ for the app and a `WORKSPACE` file that identifies the top level of the
+ workspace directory.
+* Update the `WORKSPACE` file to contain references to the required
+ external dependencies, like the Android SDK.
+* Create a `BUILD` file.
+* Build the app with Bazel.
+* Deploy and run the app on an Android emulator or physical device.
+
+## Before you begin
+
+### Install Bazel
You will need to install the following software:
@@ -24,7 +41,7 @@
wizard to download the SDK and configure your environment.
* (Optional) **Git.** We will use `git` to download the Android app project.
-## Getting started
+### Get the sample project
We will be using a basic Android app project in [Bazel's examples
repository](https://github.com/bazelbuild/examples).
@@ -44,7 +61,7 @@
The sample project for this tutorial is in `examples/android/tutorial`. For
the rest of the tutorial, you will be executing commands in this directory.
-## Review the source files
+### Review the source files
Let's take a look at the source files for the app.
@@ -76,7 +93,10 @@
| Android source files | `src/main/java/com/example/bazel/MainActivity.java` and `Greeter.java` |
| Resource file directory | `src/main/java/com/example/bazel/res/` |
-## Initialize the project's workspace
+
+## Build with Bazel
+
+### Set up the workspace
A [workspace](../build-ref.html#workspace) is a directory that contains the
source files for one or more software projects, and has a `WORKSPACE` file at
@@ -106,7 +126,7 @@
ERROR: The 'info' command is only supported from within a workspace.
```
-## Integrate with the Android SDK
+### Integrate with the Android SDK
Bazel needs to run the Android SDK [build
tools](https://developer.android.com/tools/revisions/build-tools.html) to build
@@ -194,7 +214,7 @@
[This page](https://developer.android.com/ndk/guides/stable_apis.html) contains
a map from Android releases to NDK-supported API levels.
-## Create a BUILD file
+### Create a BUILD file
A [`BUILD` file](../build-ref.html#BUILD_files) describes the relationship
between a set of build outputs, like compiled Android resources from `aapt` or
@@ -218,7 +238,7 @@
comprise a single Bazel package. A more complex project may have many nested
packages.
-### Add an android_library rule
+#### Add an android_library rule
A `BUILD` file contains several different types of declarations for Bazel. The
most important type is the [build rule](../build-ref.html#funcs), which tells
@@ -259,7 +279,7 @@
Note also that the name of the rule is `greeter_activity`. You'll reference the
rule using this name as a dependency in the `android_binary` rule.
-### Add an android_binary rule
+#### Add an android_binary rule
The [`android_binary`](../be/android.html#android_binary) rule builds
the Android application package (`.apk` file) for your app.
@@ -285,7 +305,7 @@
Now, save and close the file.
-## Build the app
+### Build the app
Let's try building the app! Run the following command to build the
`android_binary` target:
@@ -317,7 +337,7 @@
bazel-bin/src/main/app.apk
```
-## Locate the build outputs
+#### Locate the build outputs
Bazel puts the outputs of both intermediate and final build operations in a set
of per-user, per-workspace output directories. These directories are symlinked
@@ -341,7 +361,7 @@
| Windows (PowerShell) | `ls bazel-bin\src\main` |
-## Run the app
+### Run the app
You can now deploy the app to a connected Android device or emulator from the
command line using the [`bazel
@@ -371,26 +391,9 @@
It also supports the `--start_app` flag to start the app immediately upon
installing it.
-## Review your work
-
-In this tutorial, you used Bazel to build an Android app. To accomplish that,
-you:
-
-* Set up your environment by installing Bazel and Android Studio, and
- downloading the sample project.
-* Set up a Bazel [workspace](../be/workspace.md) that contains the source code
- for the app and a `WORKSPACE` file that identifies the top level of the
- workspace directory.
-* Updated the `WORKSPACE` file to contain references to the required
- external dependencies, like the Android SDK.
-* Created a `BUILD` file.
-* Built the app with Bazel.
-* Deployed and ran the app on an Android emulator or physical device.
-
## Further reading
-You now know the basics of building an Android project with Bazel. Here are some
-other pages to check out:
+For more details, see these pages:
* More information on [mobile-install](../mobile-install.md)
* Integrate external dependencies like AppCompat, Guava and JUnit from Maven
diff --git a/site/docs/tutorial/cc-toolchain-config.md b/site/docs/tutorial/cc-toolchain-config.md
index bf9d0c7..7b81f50 100644
--- a/site/docs/tutorial/cc-toolchain-config.md
+++ b/site/docs/tutorial/cc-toolchain-config.md
@@ -3,23 +3,29 @@
title: Configuring C++ toolchains
---
-# Configuring C++ toolchains
-
-## Overview
+# Bazel Tutorial: Configure C++ toolchains
This tutorial uses an example scenario to describe how to configure C++
toolchains for a project. It's based on an
[example C++ project](https://github.com/bazelbuild/examples/tree/master/cpp-tutorial/stage1)
that builds error-free using `clang`.
-In this tutorial, you will create a Starlark rule that provides additional
-configuration for the `cc_toolchain` so that Bazel can build the application
-with `clang`. The expected outcome is to run
-`bazel build --config=clang_config //main:hello-world` on a Linux machine and
-build the C++ application. For additional details please visit
-[C++ toolchain configuration](../cc-toolchain-config-reference.html)
+## What you'll learn
-## Setting up the build environment
+In this tutorial you learn how to:
+
+* Set up the build environment
+* Configure the C++ toolchain
+* Create a Starlark rule that provides additional
+configuration for the `cc_toolchain` so that Bazel can build the application
+with `clang`
+* Confirm expected outcome by running
+`bazel build --config=clang_config //main:hello-world` on a Linux machine
+* Build the C++ application
+
+## Before you begin
+
+### 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
@@ -460,10 +466,10 @@
10. If you run `bazel build --config=clang_config //main:hello-world`, it should
finally build.
-In this tutorial you have learned how to configure a basic C++ toolchain. But
-toolchains are much more powerful than this simple example. You can visit
-[C++ toolchain configuration](../cc-toolchain-config-reference.html)
-to learn more about them.
+## Review your work
+
+In this tutorial you learned how to configure a basic C++ toolchain, but
+toolchains are more powerful than this simple example.
The key take-aways are:
- You need to specify a `--crosstool_top` flag in the command line which should
@@ -481,3 +487,7 @@
`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.
+
+## Further reading
+
+For more details, see [C++ toolchain configuration](../cc-toolchain-config-reference.html)
diff --git a/site/docs/tutorial/cpp.md b/site/docs/tutorial/cpp.md
index ac30691..ce254d7 100644
--- a/site/docs/tutorial/cpp.md
+++ b/site/docs/tutorial/cpp.md
@@ -3,9 +3,9 @@
title: Build Tutorial - C++
---
-# Introduction to Bazel: Building a C++ Project
+# Bazel Tutorial: Build a C++ Project
-In this tutorial, you'll learn the basics of building C++ applications with
+This tutorial covers the basics of building C++ applications with
Bazel. You will set up your workspace and build a simple C++ project that
illustrates key Bazel concepts, such as targets and `BUILD` files. After
completing this tutorial, take a look at
@@ -16,7 +16,7 @@
## What you'll learn
-In this tutorial you'll learn how to:
+In this tutorial you learn how to:
* Build a target
* Visualize the project's dependencies
@@ -381,7 +381,8 @@
Congratulations! You now know the basics of building a C++ project with Bazel.
Next, read up on the most common [C++ build use cases](../cpp-use-cases.md).
-Then, check out the following:
+
+For more details, see:
* [External Dependencies](../external.html) to learn more about working with
local and remote repositories.
diff --git a/site/docs/tutorial/ios-app.md b/site/docs/tutorial/ios-app.md
index cd94c03..74fab6b 100644
--- a/site/docs/tutorial/ios-app.md
+++ b/site/docs/tutorial/ios-app.md
@@ -3,9 +3,24 @@
title: Build Tutorial - iOS
---
-# Introduction to Bazel: Building an iOS App
+# Bazel Tutorial: Build an iOS App
-In this tutorial, you will learn how to build a simple iOS app.
+This tutorial covers how to build a simple iOS app using Bazel.
+
+## What you'll learn
+
+In this tutorial, you learn how to:
+
+* Set up the environment by installing Bazel and Xcode, and downloading the
+ sample project
+* Set up a Bazel [workspace](workspace.md) that contained the source code
+ for the app and a `WORKSPACE` file that identifies the top level of the
+ workspace directory
+* Update the `WORKSPACE` file to contain references to the required
+ external dependencies
+* Create a `BUILD` file
+* Run Bazel to build the app for the simulator and an iOS device
+* Run the app in the simulator and on an iOS device
## Set up your environment
@@ -231,6 +246,13 @@
produce output. See the README file in the sample project directory to find out
how to build the backend server.
+The built app is located in the `$WORKSPACE/bazel-bin` directory.
+
+Completed `WORKSPACE` and `BUILD` files for this tutorial are located in the
+[master branch](https://github.com/bazelbuild/examples/tree/master/tutorial)
+of the GitHub repo. You can compare your work to the completed files for
+additional help or troubleshooting.
+
### Build the app for the simulator
Make sure that your current working directory is inside your Bazel workspace:
@@ -329,24 +351,9 @@
provisioning profile. The `View Device Logs` button on the `Devices` screen in
Xcode may provide other information as to what has gone wrong.
-## Review your work
+## Further reading
-In this tutorial, you used Bazel to build an iOS app. To accomplish that, you:
-
-* Set up your environment by installing Bazel and Xcode, and downloading the
- sample project
-* Set up a Bazel [workspace](workspace.md) that contained the source code
- for the app and a `WORKSPACE` file that identifies the top level of the
- workspace directory
-* Updated the `WORKSPACE` file to contain references to the required
- external dependencies
-* Created a `BUILD` file
-* Ran Bazel to build the app for the simulator and an iOS device
-* Ran the app in the simulator and on an iOS device
-
-The built app is located in the `$WORKSPACE/bazel-bin` directory.
-
-Completed `WORKSPACE` and `BUILD` files for this tutorial are located in the
+For more details, see
[master branch](https://github.com/bazelbuild/examples/tree/master/tutorial)
-of the GitHub repo. You can compare your work to the completed files for
-additional help or troubleshooting.
+of the GitHub repo.
+
diff --git a/site/docs/tutorial/java.md b/site/docs/tutorial/java.md
index 2f27f87..c7b8cb3 100644
--- a/site/docs/tutorial/java.md
+++ b/site/docs/tutorial/java.md
@@ -3,9 +3,9 @@
title: Build Tutorial - Java
---
-# Introduction to Bazel: Building a Java Project
+# Bazel Tutorial: Build a Java Project
-In this tutorial, you'll learn the basics of building Java applications with
+This tutorial covers the basics of building Java applications with
Bazel. You will set up your workspace and build a simple Java project that
illustrates key Bazel concepts, such as targets and `BUILD` files.
@@ -13,7 +13,7 @@
## What you'll learn
-In this tutorial you'll learn how to:
+In this tutorial you learn how to:
* Build a target
* Visualize the project's dependencies
@@ -399,6 +399,8 @@
## Further reading
+For more details, see:
+
* [rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external) for
rules to manage transitive Maven dependencies.