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.