Repository: bazelbuild/bazel
Issue: Refresh Android build tutorial on docs.bazel.build
Labels: type: feature request
P2
team-Android

Link: https://docs.bazel.build/versions/master/tutorial/android-app.html

Ideas:

- [ ] Remove references to OS specific commands. e.g. `touch`, `export`, `WORKSPACE` environment variables.
- [ ] Update versions
- [ ] Improve the flow of the tutorial. It asks the user to add snippets or create files that already exists in the examples repository.
- [ ] More screenshots. The tutorial looks very dense.

Issue comments:
Revamped in https://github.com/bazelbuild/bazel/commit/92b14d3f5ada6c857ba9a3cefbfcf7affaf16450

Pull request review comments:
how about "This tutorial does not require experience with Bazel or Android app development."
hmm, this seems to contradict the Android Studio being in Prerequisites?
"Initialize the project's workspace"?
this reassurance feels a bit odd, since presumably people are here because they want to work with android code
"and has a WORKSPACE file ..."
"the app" -> "your project"?
hmm how about "The `WORKSPACE` file contains the references to external dependencies that are required to build the project (it can also be empty if your project is self-contains)."
"Integrate with the Android SDK"? (though "Integrating with the Android SDK" sounds better, but I think you're trying to keep the parallelism with verbs)
"This will use the Android SDK at the path specified by the ANDROID_HOME environment variable ..."
", for example:"
it might be good to say why one might want to explicitly specify these attributes on the rule
i'm pretty sure that the package name would more accurately be "the path to the BUILD file relative to the WORKSPACE"
"Note that Bazel's package hierarchy is conceptually different from the Java package hierarchy of your Android App ..."?
"For the simple Android app in this tutorial, we'll make all the source files in `src/main/java` a single Bazel package"
"instructions" -> "declarations"?
consider putting the app's manifest one level up in `main`
"you'll first use the android_library rule to tell Bazel to build an Android library module" (i.e., maintaining the distinction between declaration and instruction)
"Locate" sounds better
"stores" sounds too fancy. "puts"?
I recommend omitting the `$` prompt indicator (for all platforms, for sake of consistency).
AFAIK it's not customary on Windows and may be confusing and considered part of the command.
In the Command Prompt, `setx` affects subsequent sessions but not the current one. `set` affects the current session only.
Their semantics are also different:
- `setx` understands quoting, so `setx FOO "some value"` is appropriate and stores the value without quotes
- `set` does not understand quoting, so `set FOO=some value` is the right approach; `set FOO="some value"` would include the quotes in the value

In Powershell, the command you specified affects subsequent sessions but not the current one.
To set an envvar for the current session, you have to run `$env:FOO="some value"`.
I recommend adding an example for Windows too. The key thing to call out is that `path` must use mixed-style ( see `cygpath --mixed`) paths, i.e. Windows path with forward slashes, e.g. `c:/path/to/sdk`.
`$WORKSPACE` does not make sense on Windows. I recommend some other notation, e.g. `<workspace>/bazel-out`.
done.
removed the line. I'll add it back when we have other tutorials on Android Studio and testing. 
done.
done.
done.
done.
I broke it the current paragraph up into two lines so it reads crispier.
done.
done.
done.
done.
done.
done.
done.
done.
done. https://github.com/bazelbuild/examples/pull/79
done.
done.
done.
done, removed all `$` prompts.
thank you for the clear explanation! I split the table to two: one to set it for the current session, and another to set it persistently.
done. added a Windows example.
I removed the prefix, and added a note about where these directories can be found.

Patch that resolved the issue:
diff --git a/site/docs/tutorial/android-app.md b/site/docs/tutorial/android-app.md
index 20db3e2ac81f78..20d6baef3126f5 100644
--- a/site/docs/tutorial/android-app.md
+++ b/site/docs/tutorial/android-app.md
@@ -3,140 +3,151 @@ layout: documentation
 title: Build Tutorial - Android
 ---
 
-Introduction to Bazel: Building an Android App
-==========
+# Introduction to Bazel: Building an Android App
 
-In this tutorial, you will learn how to build a simple Android app. You'll do
-the following:
+In this tutorial, you will learn how to build a simple Android app using Bazel.
 
-*   [Set up your environment](#set-up-your-environment)
-    *   [Install Bazel](#install-bazel)
-    *   [Install Android Studio](#install-android-studio)
-    *   [Get the sample project](#get-the-sample-project)
-*   [Set up a workspace](#set-up-a-workspace)
-    *   [Create a WORKSPACE file](#create-a-workspace-file)
-    *   [Update the WORKSPACE file](#update-the-workspace-file)
-*   [Review the source files](#review-the-source-files)
-*   [Create a BUILD file](#create-a-build-file)
-    *   [Add an android_library rule](#add-an-android_library-rule)
-    *   [Add an android_binary rule](#add_an-android_binary-rule)
-*   [Build the app](#build-the-app)
-*   [Find the build outputs](#find-the-build-outputs)
-*   [Run the app](#run-the-app)
-*   [Review  your work](#review-your-work)
+Bazel supports building Android apps using the [Android
+rules](https://docs.bazel.build/versions/master/be/android.html).
 
-## Set up your environment
+This tutorial is intended for Windows, macOS and Linux users and does not
+require experience with Bazel or Android app development. You do not need to
+write any Android code in this tutorial.
 
-To get started, install Bazel and Android Studio, and get the sample project.
+## Prerequisites
 
-### Install Bazel
+You will need to install the following software:
 
-Follow the [installation instructions](../install.md) to install Bazel and
-its dependencies.
+* 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).
+* (Optional) Git. We will use `git` to download the Android app project.
 
-### Install Android Studio
+## Getting started
 
-Download and install Android Studio as described in [Install Android Studio](https://developer.android.com/sdk/index.html).
+We will be using a basic Android app project in [Bazel's examples
+repository](https://github.com/bazelbuild/examples).
 
-The installer does not automatically set the `ANDROID_HOME` variable.
-Set it to the location of the Android SDK, which defaults to `$HOME/Android/Sdk/`
-.
+This app has a single button that prints a greeting when clicked.
 
-For example:
+<img src="/assets/android_tutorial_app.png" alt="screenshot of tutorial app"
+width="700">
 
-`export ANDROID_HOME=$HOME/Android/Sdk/`
+Clone the repository with `git` (or [download the ZIP file
+directly](https://github.com/bazelbuild/examples/archive/master.zip)):
 
-For convenience, add the above statement to your `~/.bashrc` file.
+``` bash
+git clone git@github.com:bazelbuild/examples.git bazel-examples
+cd bazel-examples/android/tutorial
+```
 
-### Get the sample project
+For the rest of the tutorial, you will be executing commands in this directory.
 
-You also need to get the sample project for the tutorial from GitHub. The repo
-has two branches: `source-only` and `master`. The `source-only` branch contains
-the source files for the project only. You'll use the files in this branch in
-this tutorial. The `master` branch contains both the source files and completed
-Bazel `WORKSPACE` and `BUILD` files. You can use the files in this branch to
-check your work when you've completed the tutorial steps.
+## Review the source files
 
-Enter the following at the command line to get the files in the `source-only`
-branch:
+Let's take a look at the source files for the app.
 
-```bash
-cd $HOME
-git clone -b source-only https://github.com/bazelbuild/examples
+```
+.
+├── README.md
+└── src
+    └── main
+        ├── AndroidManifest.xml
+        └── java
+            └── com
+                └── example
+                    └── bazel
+                        ├── AndroidManifest.xml
+                        ├── Greeter.java
+                        ├── MainActivity.java
+                        └── res
+                            ├── layout
+                            │   └── activity_main.xml
+                            └── values
+                                ├── colors.xml
+                                └── strings.xml
 ```
 
-The `git clone` command creates a directory named `$HOME/examples/`. This
-directory contains several sample projects for Bazel. The project files for this
-tutorial are in `$HOME/examples/tutorial/android`.
+The key files and directories are:
 
-## Set up a workspace
+| Name                    | Location                                                                                 |
+| Android manifest files  | `src/main/AndroidManifest.xml` and `src/main/java/com/example/bazel/AndroidManifest.xml` |
+| Android source files    | `src/main/java/com/example/bazel/MainActivity.java` and `Greeter.java`                   |
+| Resource file directory | `src/main/java/com/example/bazel/res/`                                                   |
 
-A [workspace](../build-ref.html#workspaces) is a directory that contains the
-source files for one or more software projects, as well as a `WORKSPACE` file
-and `BUILD` files that contain the instructions that Bazel uses to build
-the software. The workspace may also contain symbolic links to output
-directories.
+## Initialize the project's workspace
 
-A workspace directory can be located anywhere on your filesystem and is denoted
-by the presence of the `WORKSPACE` file at its root. In this tutorial, your
-workspace directory is `$HOME/examples/tutorial/`, which contains the sample
-project files you cloned from the GitHub repo in the previous step.
+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 in
+the top level of the directory.
 
-Note that Bazel itself doesn't make any requirements about how you organize
-source files in your workspace. The sample source files in this tutorial are
-organized according to conventions for the target platform.
+The `WORKSPACE` file may be empty or it may contain references to [external
+dependencies](../external.html) required to build your project. 
 
-For your convenience, set the `$WORKSPACE` environment variable now to refer to
-your workspace directory. At the command line, enter:
+First, run the following command to create an empty `WORKSPACE` file:
 
-```bash
-export WORKSPACE=$HOME/examples/tutorial
-```
+| Linux, macOS             | `touch WORKSPACE`                   |
+| Windows (Command Prompt) | `type nul > WORKSPACE`              |
+| Windows (PowerShell)     | `New-Item WORKSPACE -ItemType file` |
 
-### Create a WORKSPACE file
+### Running Bazel
 
-Every workspace must have a text file named `WORKSPACE` located in the top-level
-workspace directory. This file may be empty or it may contain references
-to [external dependencies](../external.html) required to build the
-software.
+You can now check if Bazel is running correctly with the command:
 
-For now, you'll create an empty `WORKSPACE` file, which simply serves to
-identify the workspace directory. In later steps, you'll update the file to add
-external dependency information.
+```bash
+bazel info workspace
+```
 
-Enter the following at the command line:
+If Bazel prints the path of the current directory, you're good to go! If the
+`WORKSPACE` file does not exist, you may see an error message like:
 
-```bash
-touch $WORKSPACE/WORKSPACE
 ```
-This creates the empty `WORKSPACE` file.
+ERROR: The 'info' command is only supported from within a workspace.
+```
 
-### Update the WORKSPACE file
+## Integrate with the Android SDK
 
-Bazel needs to run the Android SDK
-[build tools](https://developer.android.com/tools/revisions/build-tools.html)
-and uses the SDK libraries to build the app. This means that you need to add
-some information to your `WORKSPACE` file so that Bazel knows where to find
-them.  Note that this step is not required when you build for other platforms.
-For example, Bazel automatically detects the location of Java, C++ and
-Objective-C compilers from settings in your environment.
+Bazel needs to run the Android SDK [build
+tools](https://developer.android.com/tools/revisions/build-tools.html) to build
+the app. This means that you need to add some information to your `WORKSPACE`
+file so that Bazel knows where to find them.
 
-Add the following lines to your `WORKSPACE` file:
+Add the following line to your `WORKSPACE` file:
 
 ```python
-android_sdk_repository(
-    name = "androidsdk"
-)
+android_sdk_repository(name = "androidsdk")
 ```
 
-This will use the Android SDK referenced by the `ANDROID_HOME` environment
-variable, and automatically detect the highest API level and the latest version
-of build tools installed within that location.
+This will use the Android SDK at the path referenced by the `ANDROID_HOME`
+environment variable, and automatically detect the highest API level and the
+latest version of build tools installed within that location.
+
+You can set the `ANDROID_HOME` variable to the location of the Android SDK. Find
+the path to the installed SDK using Android Studio's [SDK
+Manager](https://developer.android.com/studio/intro/update#sdk-manager).
+
+For example, as the default SDK path is in your home directory for Linux and
+macOS, and `LOCALAPPDATA` for Windows, you can use the following commands to set
+the `ANDROID_HOME` variable:
+
+| Linux, macOS             | `export ANDROID_HOME=$HOME/Android/Sdk/`            |
+| Windows (Command Prompt) | `set ANDROID_HOME=%LOCALAPPDATA%\Android\Sdk`       |
+| Windows (PowerShell)     | `$env:ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"` |
 
-Alternatively, you can explicitly specify the location of the Android
-SDK, the API level, and the version of build tools to use by including the
-`path`,`api_level`, and `build_tools_version` attributes. You can specify any
-subset of these attributes:
+Note that the commands above will set the variable for the current shell session
+only. To make it permanent for future sessions, run the following:
+
+| Linux, macOS             | `echo "export ANDROID_HOME=$HOME/Android/Sdk/" >> ~/.bashrc`                                                                              |
+| Windows (Command Prompt) | `setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"`                                                                                          |
+| Windows (PowerShell)     | `[System.Environment]::SetEnvironmentVariable('ANDROID_HOME', "$env:LOCALAPPDATA\Android\Sdk", [System.EnvironmentVariableTarget]::User)` |
+
+Alternatively, you can explicitly specify the absolute path of the Android SDK,
+the API level, and the version of build tools to use by including the `path`,
+`api_level`, and `build_tools_version` attributes. If `api_level` and
+`build_tools_version` are not specified, the `android_sdk_repository` rule will
+use the respective latest version available in the SDK. You can specify any
+combination of these attributes, as long as they are present in the SDK, for
+example:
 
 ```python
 android_sdk_repository(
@@ -147,245 +158,217 @@ android_sdk_repository(
 )
 ```
 
-**Optional:** This is not required by this tutorial, but if you want to compile
-native code into your Android app, you also need to download the
-[Android NDK](https://developer.android.com/ndk/downloads/index.html) and
-tell Bazel where to find it by adding the following rule to your `WORKSPACE`
-file:
+On Windows, note that the `path` attribute must use the mixed-style path, that
+is, a Windows path with forward slashes:
 
 ```python
-android_ndk_repository(
-    name = "androidndk"
+android_sdk_repository(
+    name = "androidsdk",
+    path = "c:/path/to/Android/sdk",
 )
 ```
 
-`api_level` is the version of the Android API the SDK and the NDK target
-(for example, 23 for Android 6.0 and 25 for Android 7.1). If not explicitly
-set, `api_level` will default to the highest available API level for
-`android_sdk_repository` and `android_ndk_repository`. It's not necessary to
-set the API levels to the same value for the SDK and NDK.
-[This web page](https://developer.android.com/ndk/guides/stable_apis.html)
-contains a map from Android releases to NDK-supported API levels.
-
-Similar to `android_sdk_repository`, the path to the Android NDK is inferred
-from the `ANDROID_NDK_HOME` environment variable by default. The path can also
-be explicitly specified with a `path` attribute on `android_ndk_repository`.
-
-## Review the source files
-
-Let's take a look at the source files for the app. These are located in
-`$WORKSPACE/android/`.
-
-The key files and directories are:
-
-<table class="table table-condensed table-striped">
-<thead>
-<tr>
-<td>Name</td>
-<td>Location</td>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>Manifest file</td>
-<td><code>src/main/java/com/google/bazel/example/android/AndroidManifest.xml</code></td>
-</tr>
-<tr>
-<td>Activity source file</td>
-<td><code>src/main/java/com/google/bazel/example/android/activities/MainActivity.java</code></td>
-</tr>
-<tr>
-<td>Resource file directory</td>
-<td><code>src/main/java/com/google/bazel/example/android/res/</code></td>
-</tr>
-</tbody>
-</table>
-
-Note that you're just looking at these files now to become familiar with the
-structure of the app. You don't have to edit any of the source files to complete
-this tutorial.
+> **Optional:** This is not required by this tutorial, but if you want to compile
+> native code into your Android app, you also need to download the [Android
+> NDK](https://developer.android.com/ndk/downloads/index.html) and tell Bazel
+> where to find it by adding the following line to your `WORKSPACE` file:
+> 
+> ```python
+> android_ndk_repository(name = "androidndk")
+> ```
+> 
+> Similar to `android_sdk_repository`, the path to the Android NDK is inferred
+> from the `ANDROID_NDK_HOME` environment variable by default. The path can also
+> be explicitly specified with a `path` attribute on `android_ndk_repository`.
+> 
+> For more information, read [Using the Android Native Development Kit with
+> Bazel](https://docs.bazel.build/versions/master/android-ndk.html).
+
+`api_level` is the version of the Android API that the SDK (and the NDK) will
+target (for example, 23 for Android 6.0 and 25 for Android 7.1). If not
+explicitly set, `api_level` will default to the highest available API level for
+`android_sdk_repository` and `android_ndk_repository`.
+
+It's not necessary to set the API levels to the same value for the SDK and NDK.
+[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
 
-A [`BUILD` file](../build-ref.html#BUILD_files) is a text file that describes
-the relationship between a set of build outputs -- for example, compiled
-software libraries or executables -- and their dependencies. These dependencies
-may be source files in your workspace or other build outputs. `BUILD` files are
-written in the Bazel *build language*.
+A [`BUILD` file](../build-ref.html#BUILD_files) describes the relationship
+between a set of build outputs, like compiled Android resources from `aapt` or
+class files from `javac`, and their dependencies. These dependencies may be
+source files (Java, C++) in your workspace or other build outputs. `BUILD` files
+are written in a language called **Starlark**.
 
 `BUILD` files are part of a concept in Bazel known as the *package hierarchy*.
 The package hierarchy is a logical structure that overlays the directory
 structure in your workspace. Each [package](../build-ref.html#packages) is a
 directory (and its subdirectories) that contains a related set of source files
 and a `BUILD` file. The package also includes any subdirectories, excluding
-those that contain their own `BUILD` file. The *package name* is the name of the
-directory where the `BUILD` file is located.
-
-Note that this package hierarchy is distinct from, but coexists with, the Java
-package hierarchy for your Android app.
+those that contain their own `BUILD` file. The *package name* is the path to the
+`BUILD` file relative to the `WORKSPACE`.
 
-For the simple Android app in this tutorial, we'll consider all the source files
-in `$WORKSPACE/android/` to comprise a single Bazel package. A more complex
-project may have many nested packages.
+Note that Bazel's package hierarchy is conceptually different from the Java
+package hierarchy of your Android App directory where the `BUILD` file is
+located. , although the directories may be organized identically.
 
-At a command-line prompt, open your new `BUILD` file for editing:
-
-```bash
-vi $WORKSPACE/android/BUILD
-```
+For the simple Android app in this tutorial, we'll make all the source files in
+`src/main/` to comprise a single Bazel package. A more complex project may have
+many nested packages.
 
 ### Add an android_library rule
 
-A `BUILD` file contains several different types of instructions for Bazel. The
+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
 Bazel how to build an intermediate or final software output from a set of source
 files or other dependencies.
 
 Bazel provides two build rules, `android_library` and `android_binary`, that you
 can use to build an Android app. For this tutorial, you'll first use the
-[`android_library`](../be/android.html#android_library) rule to tell
-Bazel how to build an
-[Android library module](http://developer.android.com/tools/projects/index.html#LibraryProjects)
+[`android_library`](../be/android.html#android_library) rule to tell Bazel to
+build an [Android library
+module](http://developer.android.com/tools/projects/index.html#LibraryProjects)
 from the app source code and resource files. Then you'll use the
 `android_binary` rule to tell it how to build the Android application package.
 
-Add the following to your `BUILD` file:
+Create a new `BUILD` file in the `src/main/java/com/example/bazel` directory,
+and declare a new `android_library` target:
+
+`src/main/java/com/example/bazel/BUILD`:
 
 ```python
+package(
+    default_visibility = ["//src:__subpackages__"],
+)
+
 android_library(
-  name = "activities",
-  srcs = glob(["src/main/java/com/google/bazel/example/android/activities/*.java"]),
-  custom_package = "com.google.bazel.example.android.activities",
-  manifest = "src/main/java/com/google/bazel/example/android/activities/AndroidManifest.xml",
-  resource_files = glob(["src/main/java/com/google/bazel/example/android/activities/res/**"]),
+    name = "greeter_activity",
+    srcs = [
+        "Greeter.java",
+        "MainActivity.java",
+    ],
+    manifest = "AndroidManifest.xml",
+    resource_files = glob(["res/**"]),
 )
 ```
 
-As you can see, the `android_library` build rule contains a set of attributes
-that specify the information that Bazel needs to build a library module from the
-source files. Note also that the name of the rule is `activities`. You'll
-reference the rule using this name as a dependency in the `android_binary` rule.
+The `android_library` build rule contains a set of attributes that specify the
+information that Bazel needs to build a library module from the source files.
+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
 
 The [`android_binary`](../be/android.html#android_binary) rule builds
 the Android application package (`.apk` file) for your app.
 
-Add the following to your build file:
+Create a new `BUILD` file in the `src/main/` directory,
+and declare a new `android_binary` target:
+
+`src/main/BUILD`:
 
 ```python
 android_binary(
-    name = "android",
-    custom_package = "com.google.bazel.example.android",
-    manifest = "src/main/java/com/google/bazel/example/android/AndroidManifest.xml",
-    resource_files = glob(["src/main/java/com/google/bazel/example/android/res/**"]),
-    deps = [":activities"],
+    name = "app",
+    manifest = "AndroidManifest.xml",
+    deps = ["//src/main/java/com/example/bazel:greeter_activity"],
 )
 ```
 
-Here, the `deps` attribute references the output of the `activities` rule you
-added to the `BUILD` file above. This means that, when Bazel builds the output
-of this rule, it checks first to see if the output of the `activities` library
-rule has been built and is up-to-date. If not, it builds it and then uses that
-output to build the application package file.
+Here, the `deps` attribute references the output of the `greeter_activity` rule
+you added to the `BUILD` file above. This means that, when Bazel builds the
+output of this rule, it checks first to see if the output of the
+`greeter_activity` library rule has been built and is up-to-date. If not, it
+builds it and then uses that output to build the application package file.
 
-Now, save and close the file. You can compare your `BUILD` file to the
-[completed example](https://github.com/bazelbuild/examples/blob/master/tutorial/android/BUILD)
-in the `master` branch of the GitHub repo.
+Now, save and close the file. 
 
 ## Build the app
 
-You use the
-[`bazel`](../user-manual.html) command-line tool to run builds, execute
-unit tests and perform other operations in Bazel. This tool is located in the
-`output` subdirectory of the location where you installed Bazel. During
-[installation](../install.md), you probably added this location to your
-path.
-
-Before you build the sample app, make sure that your current working directory
-is inside your Bazel workspace:
+Let's try building the app! Run the following command to build the
+`android_binary` target:
 
 ```bash
-cd $WORKSPACE
+bazel build //src/main:app
 ```
 
-Now, enter the following to build the sample app:
-
-```bash
-bazel build //android:android
-```
+The [`build`](../user-manual.html#build) subcommand instructs Bazel to build the
+target that follows. The target is specified as the name of a build rule inside
+a `BUILD` file, with along with the package path relative to your workspace
+directory. For this example, the target is `app` and the package path is
+`//src/main/`.
 
-The [`build`](../user-manual.html#build) subcommand instructs Bazel to
-build the target that follows. The target is specified as the name of a build
-rule inside a `BUILD` file, with along with the package path relative to
-your workspace directory. Note that you can sometimes omit the package path
-or target name, depending on your current working directory at the command
-line and the name of the target. See [Labels](../build-ref.html#labels) in the
-*Bazel Concepts and Terminology* page for more information about target labels
-and paths.
+Note that you can sometimes omit the package path or target name, depending on
+your current working directory at the command line and the name of the target.
+See [Labels](../build-ref.html#labels) in the *Bazel Concepts and Terminology*
+page for more information about target labels and paths.
 
-Bazel now launches and builds the sample app. During the build process, its
-output will appear similar to the following:
+Bazel will start to build the sample app. During the build process, its output
+will appear similar to the following:
 
 ```bash
+INFO: Analysed target //src/main:app (0 packages loaded, 0 targets configured).
 INFO: Found 1 target...
-Target //android:android up-to-date:
-  bazel-bin/android/android_deploy.jar
-  bazel-bin/android/android_unsigned.apk
-  bazel-bin/android/android.apk
-INFO: Elapsed time: 7.237s, Critical Path: 5.81s
+Target //src/main:app up-to-date:
+  bazel-bin/src/main/app_deploy.jar
+  bazel-bin/src/main/app_unsigned.apk
+  bazel-bin/src/main/app.apk
 ```
 
-## Find the build outputs
+## Locate the build outputs
 
-Bazel stores the outputs of both intermediate and final build operations in
-a set of per-user, per-workspace output directories. These directories are
-symlinked from the following locations:
+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
+from the following locations at the top-level of the project directory, where
+the `WORKSPACE` is:
 
-* `$WORKSPACE/bazel-bin`, which stores binary executables and other runnable
-   build outputs
-* `$WORKSPACE/bazel-genfiles`, which stores intermediary source files that are
-   generated by Bazel rules
-* `$WORKSPACE/bazel-out`, which stores other types of build outputs
+* `bazel-bin`, which stores binary executables and other runnable build outputs
+* `bazel-genfiles`, which stores intermediary source files that are generated by
+   Bazel rules
+* `bazel-out`, which stores other types of build outputs
 
 Bazel stores the Android `.apk` file generated using the `android_binary` rule
-in the `bazel-bin/android/` directory, where the subdirectory name `android` is
+in the `bazel-bin/src/main` directory, where the subdirectory name `src/main` is
 derived from the name of the Bazel package.
 
-At a command prompt, list the contents of this directory and find the
-`android.apk` file:
+At a command prompt, list the contents of this directory and find the `app.apk`
+file:
 
-```bash
-ls $WORKSPACE/bazel-bin/android
-```
+| Linux, macOS             | `ls bazel-bin/src/main`  |
+| Windows (Command Prompt) | `dir bazel-bin\src\main` |
+| Windows (PowerShell)     | `ls bazel-bin\src\main`  |
 
-## Run the app
 
-**NOTE:** The app launches standalone but requires a backend server in order to
-produce output. See the README file in the sample project directory to find out
-how to build the backend server.
+## Run the app
 
 You can now deploy the app to a connected Android device or emulator from the
-command line using the
-[`bazel mobile-install`](../user-manual.html#mobile-install)
-command. This command uses the Android Debug Bridge (`adb`) to communicate with
-the device. You must set up your device to use `adb` following the instructions
-in
-[Android Debug Bridge](http://developer.android.com/tools/help/adb.html) before
-deployment. You can also choose to install the app on the Android emulator
-included in Android Studio. Make sure the emulator is running before executing
-the command below.
+command line using the [`bazel
+mobile-install`](../user-manual.html#mobile-install) command. This command uses
+the Android Debug Bridge (`adb`) to communicate with the device. You must set up
+your device to use `adb` following the instructions in [Android Debug
+Bridge](http://developer.android.com/tools/help/adb.html) before deployment. You
+can also choose to install the app on the Android emulator included in Android
+Studio. Make sure the emulator is running before executing the command below.
 
 Enter the following:
 
 ```bash
-bazel mobile-install //android:android
+bazel mobile-install //src/main:app
 ```
 
+Next, find and launch the "Bazel Tutorial App". You should see this screen:
+
+<img src="/assets/android_tutorial_before.png" alt="screenshot of tutorial app" width="500">
+
+**Congrats! You have just installed your first Bazel-built Android app.**
+
 Note that the `mobile-install` subcommand also supports the
-[`--incremental`](../user-manual.html#mobile-install)
-flag that can be used to deploy only those parts of the app that have changed
-since the last deployment.
+[`--incremental`](../user-manual.html#mobile-install) flag that can be used to
+deploy only those parts of the app that have changed since the last deployment.
+
+It also supports the `--start_app` flag to start the app immediately upon
+installing it.
 
 ## Review your work
 
@@ -398,15 +381,18 @@ you:
     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
+    external dependencies, like the Android SDK
 *   Created a `BUILD` file
 *   Ran Bazel to build the app
 *   Deployed and ran the app on an Android emulator and device
 
-The built app is located in the `$WORKSPACE/bazel-bin` directory.
+## Further reading 
+
+You now know the basics of building an Android project with Bazel. Here are some
+other pages to check out:
+
+* More information on [mobile-install](mobile-install.md)
+* Testing your app with [Android instrumentation tests](android-instrumentation-test.md)
+* Integrating C and C++ code into your Android app with the [NDK](android-ndk.md)
 
-Note that 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.
+Happy building!


Test patch: