Restructure site/ directory into docs/ which only contains Bazel documentation.
The new docs/ directory in the bazel source tree will only contain the Bazel
docs site, which is hosted at docs.bazel.build. This change deletes the
marketing site and blog, which have been migrated to the bazel-website and
bazel-blog GitHub repositories respectively.
This change also updates the serve-docs.sh and ci/build.sh under scripts/ in
preparation for publishing the docs site.
Note that to help make reviews more manageable, this change is limited to
moving files to their new locations. Here are the follow-up changes:
* Update all links in docs to remove versions/master in paths and to add
correct bazel.build subdomain when linking to pages on the marketing site
or the blog.
* Set up versioned directories on GCS bucket and add tooling for versioning
docs
This change is also coordinated with
https://bazel-review.googlesource.com/c/11568/ to have the PublishSite job
publish to docs.bazel.build rather than www.bazel.build.
Issue #2397
RELNOTES: None
PiperOrigin-RevId: 157612651
diff --git a/site/docs/tutorial/android-app.md b/site/docs/tutorial/android-app.md
index ea52e3e..f31736b 100644
--- a/site/docs/tutorial/android-app.md
+++ b/site/docs/tutorial/android-app.md
@@ -1,4 +1,295 @@
---
-layout: redirect
-redirect: docs/tutorial/android-app.html
+layout: documentation
+title: Tutorial - Build an Android App
---
+
+# Tutorial - Build an Android App
+
+The sample Android app in this tutorial is a very simple application that makes
+an HTTP connection to the [backend server](backend-server.md) and displays the
+resulting response.
+
+Here, you'll do the following:
+
+* Review the source files for the app
+* Update the `WORKSPACE` file
+* Create a `BUILD` file
+* Run the build
+* Find the build outputs
+* Run the app
+
+## 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.
+
+## Update the WORKSPACE file
+
+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.
+
+Add the following lines to your `WORKSPACE` file:
+
+```python
+android_sdk_repository(
+ name = "androidsdk",
+ # Replace with your installed Android SDK API level
+ api_level = 25
+)
+```
+
+This will use the Android SDK specified referenced by the `ANDROID_HOME`
+environment variable, and automatically detect the latest build tools
+version installed within that location.
+
+Alternatively, you can explicitly specify the location of the Android
+SDK and build tools version to use by including the `path` and
+`build_tools_version` attributes:
+
+```python
+android_sdk_repository(
+ name = "androidsdk",
+ path = "/path/to/Android/sdk",
+ api_level = 25,
+ build_tools_version = "25.0.1"
+)
+```
+
+**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:
+
+```python
+android_ndk_repository(
+ name = "androidndk",
+ # Replace with the Android NDK API level
+ api_level = 21
+)
+```
+
+`api_level` is the version of the Android API the SDK and the NDK target
+(for example, 19 for Android K and 21 for Android L). 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`.
+
+## Create a BUILD file
+
+A [`BUILD` file](/docs/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*.
+
+`BUILD` files are part of 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](/docs/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.
+
+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.
+
+At a command-line prompt, open your new `BUILD` file for editing:
+
+```bash
+vi $WORKSPACE/android/BUILD
+```
+
+### Add an android_library rule
+
+A `BUILD` file contains several different types of instructions for Bazel. The
+most important type is the [build rule](/docs/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`](/docs/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)
+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:
+
+```python
+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/**"]),
+)
+```
+
+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.
+
+### Add an android_binary rule
+
+The [`android_binary`](/docs/be/android.html#android_binary) rule builds
+the Android application package (`.apk` file) for your app.
+
+Add the following to your build file:
+
+```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"],
+)
+```
+
+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.
+
+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.
+
+## Run the build
+
+You use the
+[`bazel`](/docs/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](/docs/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:
+
+```bash
+cd $WORKSPACE
+```
+
+Now, enter the following to build the sample app:
+
+```bash
+bazel build //android:android
+```
+
+The [`build`](/docs/bazel-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](/docs/build-ref.html#labels) in
+*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:
+
+```bash
+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
+```
+
+## Find 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:
+
+* `$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 stores the Android `.apk` file generated using the `android_binary` rule
+in the `bazel-bin/android/` directory, where the subdirectory name `android` 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:
+
+```bash
+ls $WORKSPACE/bazel-bin/android
+```
+
+## 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`](http://bazel.build/docs/bazel-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.
+
+Enter the following:
+
+```bash
+bazel mobile-install //android:android
+```
+
+Note that the `mobile-install` subcommand also supports the
+[`--incremental`](http://bazel.build/docs/bazel-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.
+
+## What's next
+
+Now that you've built a sample app for Android, it's time to do the same for
+the [iOS app](ios-app.md).
diff --git a/site/docs/tutorial/app.md b/site/docs/tutorial/app.md
index d3c2872..b3b274c 100644
--- a/site/docs/tutorial/app.md
+++ b/site/docs/tutorial/app.md
@@ -1,4 +1,45 @@
---
-layout: redirect
-redirect: docs/tutorial/app.html
+layout: documentation
+title: Build Mobile Application
---
+
+# Build Mobile Application
+
+You can use Bazel to build a variety of software outputs, including
+Linux and macOS (OS X) applications written in Java, C++ and Objective-C. You can
+also use Bazel to build software for other platforms or written in other
+languages.
+
+This tutorial shows how to use Bazel to build the following:
+
+* An Android app
+* An iOS app
+* A mobile backend server running on App Engine
+
+In this tutorial, you'll learn how to:
+
+* Set up a Bazel workspace and create a `WORKSPACE` file
+* Create `BUILD` files that contain the instructions used by Bazel to build
+ the software
+* Run builds using the Bazel command line tool
+
+## Requirements
+
+You can follow the steps in this tutorial on either a Linux or Mac OS X system.
+However, you can only build the iOS app if you are running Bazel on OS X. If
+you are using Linux, you can skip the iOS instructions and still complete
+the rest of the tutorial steps.
+
+## Sample project
+
+You don't have to write your own mobile apps and backend server to use this
+tutorial. Instead, you'll use a sample project hosted on GitHub. The sample
+project is hosted at the following location:
+
+[https://github.com/bazelbuild/examples/](https://github.com/bazelbuild/examples/)
+
+You'll grab the sample project files in the next step in this tutorial.
+
+## What's next
+
+Let's start off by [setting up](environment.md) the tutorial environment.
diff --git a/site/docs/tutorial/backend-server.md b/site/docs/tutorial/backend-server.md
index 150f915..00c61ac 100644
--- a/site/docs/tutorial/backend-server.md
+++ b/site/docs/tutorial/backend-server.md
@@ -1,4 +1,237 @@
---
-layout: redirect
-redirect: docs/tutorial/backend-server.html
+layout: documentation
+title: Tutorial - Build the Backend Server
---
+
+# Tutorial - Build the Backend Server
+
+The backend server is a simple web application that runs on Google App Engine
+and responds to incoming HTTP requests from the sample Android and iOS apps.
+
+Here, you'll do the following:
+
+* Review the source files for the app
+* Update the `WORKSPACE` file
+* Create a `BUILD` file
+* Run the build
+* Find the build outputs
+* Run the application on a local development server
+* Deploy to Google App Engine
+
+Bazel provides a set of [App Engine build rules](https://github.com/bazelbuild/rules_appengine)
+written using the [Skylark](/docs/skylark/index.html) framework. You'll use
+these in the steps below to build the application.
+
+## Review the source files
+
+The source files for the backend server are located in `$WORKSPACE/backend/`.
+
+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>Source file directory</td>
+<td><code>src/main/java/com/google/bazel/example/app/</code></td>
+</tr>
+<tr>
+<td>Web application metadata directory</td>
+<td><code>webapp/WEB-INF/</code></td>
+</tr>
+</tbody>
+</table>
+
+## Update the WORKSPACE file
+
+As with the Android app, you must add references to
+[external dependencies](http://bazel.build/docs/external.html) to your `WORKSPACE`
+file. For the backend server, these are references to the App Engine SDK,
+the Java Servlet SDK and other libraries needed to build the App Engine
+applications.
+
+### Add the App Engine rule
+
+When you built the Android app, you added a reference to the location on your
+filesystem where you downloaded and installed the Android SDK. For the
+backend server, however, you'll give Bazel instructions for downloading the
+required App Engine SDK package from a remote server. This is optional. You
+can also download and install the SDK manually on your filesystem and reference
+it from that location as described in the
+[App Engine rule documentation](https://github.com/bazelbuild/rules_appengine).
+
+Add the following to your `WORKSPACE` file:
+
+```python
+http_archive(
+ name = "io_bazel_rules_appengine",
+ sha256 = "f4fb98f31248fca5822a9aec37dc362105e57bc28e17c5611a8b99f1d94b37a4",
+ strip_prefix = "rules_appengine-0.0.6",
+ url = "https://github.com/bazelbuild/rules_appengine/archive/0.0.6.tar.gz",
+)
+load("@io_bazel_rules_appengine//appengine:appengine.bzl", "appengine_repositories")
+appengine_repositories()
+```
+
+[`http_archive`](/docs/be/workspace.html#http_archive) downloads the
+AppEngine rules from a GitHub archive. We could also have used
+[`git_repository`](/docs/be/workspace.html#git_repository) to fetch the rules
+directly from the Git repository.
+Then the next two lines use the `appengine_repositories` function defined in
+these rules to download the libraries and SDK needed to build AppEngine
+applications.
+
+Now, save and close the file. You can compare your `WORKSPACE` file to the
+[completed example](https://github.com/bazelbuild/examples//blob/master/tutorial/WORKSPACE)
+in the `master` branch of the GitHub repo.
+
+## Create a BUILD file
+
+Now that you have set up the external dependencies, you can go ahead and create
+the `BUILD` file for the backend server, as you did previously for the sample
+Android and iOS apps.
+
+Open your new `BUILD` file for editing:
+
+```bash
+vi $WORKSPACE/backend/BUILD
+```
+
+### Add a java_binary rule
+
+Add the following to your `BUILD` file:
+
+```python
+java_binary(
+ name = "app",
+ srcs = glob(["src/main/java/**/*.java"]),
+ main_class = "does.not.exist",
+ deps = [
+ "@io_bazel_rules_appengine//appengine:javax.servlet.api",
+ ],
+)
+```
+
+The [`java_binary`](/docs/be/java.html#java_binary) tells Bazel
+how to build a Java `.jar` library for your application, plus a wrapper shell
+script that launches the application code from the specified main class. Here,
+we're using this rule instead of the
+[`java_library`](/docs/be/java.html#java_library) because we need
+the `.jar` file to contain all the dependencies required to build the final
+App Engine `.war` file. For this reason, we specify a bogus class name
+for the `main_class` attribute.
+
+### Add an appengine_war rule
+
+Add the following to your `BUILD` file:
+
+```python
+load("@io_bazel_rules_appengine//appengine:appengine.bzl", "appengine_war")
+
+appengine_war(
+ name = "backend",
+ data = [":webapp"],
+ data_path = "/backend/webapp",
+ jars = [":app_deploy.jar"],
+)
+
+filegroup(
+ name = "webapp",
+ srcs = glob(["webapp/**/*"]),
+)
+```
+
+The [`appengine_war`](/docs/be/appengine.html#appengine_war)
+rule builds the final App Engine `war` file from the library `.jar` file and web
+application metadata files in the `webapp` directory.
+
+Save and close the file. Again, the
+[completed example](https://github.com/google/bazel-examples/blob/master/tutorial/backend/BUILD)
+is in the `master` branch of the GitHub repo.
+
+## Run the build
+
+Make sure that your current working directory is inside your Bazel workspace:
+
+```bash
+cd $WORKSPACE
+```
+
+Now, enter the following to build the sample app:
+
+```bash
+bazel build //backend:backend
+```
+
+Bazel now launches and builds the sample app. During the build process, its
+output will appear similar to the following:
+
+```bash
+INFO: Found 1 target...
+Target //backend:backend up-to-date:
+ bazel-bin/backend/backend.war
+ bazel-bin/backend/backend.deploy
+ bazel-bin/backend/backend
+INFO: Elapsed time: 56.867s, Critical Path: 2.72s
+```
+
+## Find the build outputs
+
+The `.war` file and other outputs are located in the
+`$WORKSPACE/bazel-bin/backend` directory.
+
+In particular, the `appengine_war` rule generates scripts that you can use to
+run your backend locally or deploy it to Google App Engine:
+
+## Run the application on a local development server
+
+Here, you'll start a local App Engine development server in your environment and
+run your application on it.
+
+To run the application, enter the following:
+
+```bash
+bazel-bin/backend/backend --port=12345
+```
+
+Your application will be available at `http://localhost:12345`
+
+## Deploy to Google App Engine
+
+You can also deploy the application to the live App Engine serving
+environment on Google Cloud Platform. For this scenario, you must first create
+a new Cloud Platform project and App Engine application using the Google Cloud
+Platform Console.
+Follow [this link](https://console.cloud.google.com/projectselector/appengine/create?lang=java&st=true)
+to perform these actions.
+
+Build the target that allows to deploy to App Engine:
+
+```bash
+bazel build --java_toolchain=@io_bazel_rules_appengine//appengine:jdk7 //backend:backend.deploy
+```
+
+Then, to deploy the application, enter the following:
+
+```bash
+bazel-bin/backend/backend.deploy <project-id>
+```
+
+The deployment script prompts you to authorize access to Google Cloud Platform.
+After you have authorized access the first time, you can deploy the application
+using the `bazel` command and the following rule target:
+
+```bash
+bazel run //backend:backend.deploy <project-id>
+```
+
+Your application URL will be `http://<project-id>.appspot.com`.
+
+## What's next
+
+Now let's [review](review.md) the tutorial steps.
diff --git a/site/docs/tutorial/cpp.md b/site/docs/tutorial/cpp.md
index 6ec737f..2336201 100644
--- a/site/docs/tutorial/cpp.md
+++ b/site/docs/tutorial/cpp.md
@@ -1,4 +1,395 @@
---
-layout: redirect
-redirect: docs/tutorial/cpp.html
+layout: documentation
+title: Build C++
---
+
+Build C++
+=========
+
+You can use Bazel to build your C++ application. In this tutorial you'll learn how to:
+
+* Build your first C++ target
+* Use external libraries
+* Write and run C++ tests
+* Use precompiled libraries
+
+## Setting up your workspace
+
+Suppose that you have an existing project in a directory, say,
+`~/gitroot/my-project/`. Create an empty file at
+`~/gitroot/my-project/WORKSPACE` to show Bazel where your project's root is.
+We are going to create a small hello world project with the following directory structure:
+{% highlight bash %}
+└── my-project
+ ├── lib
+ │ ├── BUILD
+ │ ├── hello-greet.cc
+ │ └── hello-greet.h
+ ├── main
+ │ ├── BUILD
+ │ ├── hello-time.cc
+ │ ├── hello-time.h
+ │ └── hello-world.cc
+ └── WORKSPACE
+{% endhighlight %}
+
+## Creating source files
+
+Using the following commands to create the necessary source files:
+{% highlight bash %}
+# If you're not already there, move to your workspace directory.
+cd ~/gitroot/my-project
+mkdir ./main
+cat > main/hello-world.cc <<'EOF'
+
+#include "lib/hello-greet.h"
+#include "main/hello-time.h"
+#include <iostream>
+#include <string>
+
+int main(int argc, char** argv) {
+ std::string who = "world";
+ if (argc > 1) {
+ who = argv[1];
+ }
+ std::cout << get_greet(who) <<std::endl;
+ print_localtime();
+ return 0;
+}
+EOF
+
+cat > main/hello-time.h <<'EOF'
+
+#ifndef MAIN_HELLO_TIME_H_
+#define MAIN_HELLO_TIME_H_
+
+void print_localtime();
+
+#endif
+EOF
+
+cat > main/hello-time.cc <<'EOF'
+
+#include "main/hello-time.h"
+#include <ctime>
+#include <iostream>
+
+void print_localtime() {
+ std::time_t result = std::time(nullptr);
+ std::cout << std::asctime(std::localtime(&result));
+}
+EOF
+
+mkdir ./lib
+cat > lib/hello-greet.h <<'EOF'
+
+#ifndef LIB_HELLO_GREET_H_
+#define LIB_HELLO_GREET_H_
+
+#include <string>
+
+std::string get_greet(const std::string &thing);
+
+#endif
+EOF
+
+cat > lib/hello-greet.cc <<'EOF'
+
+#include "lib/hello-greet.h"
+#include <string>
+
+std::string get_greet(const std::string& who) {
+ return "Hello " + who;
+}
+EOF
+{% endhighlight %}
+
+## Adding BUILD files
+
+As you can see from the source code, `main/hello-world.cc` needs to include both `lib/hello-greet.h` and `main/hello-time.h`.
+First we create `lib/BUILD` for hello-greet.cc:
+
+{% highlight python %}
+cc_library(
+ name = "hello-greet",
+ srcs = ["hello-greet.cc"],
+ hdrs = ["hello-greet.h"],
+ visibility = ["//main:__pkg__"],
+)
+{% endhighlight %}
+
+Note that `visibility = ["//main:__pkg__"]` indicates `hello-greet` is visible from `main/BUILD`.
+Then we'd create the following `main/BUILD` file:
+
+{% highlight python %}
+cc_library(
+ name = "hello-time",
+ srcs = ["hello-time.cc"],
+ hdrs = ["hello-time.h"],
+)
+
+cc_binary(
+ name = "hello-world",
+ srcs = ["hello-world.cc"],
+ deps = [
+ ":hello-time",
+ "//lib:hello-greet",
+ ],
+)
+{% endhighlight %}
+
+Note when depending on a target in the same package, we can just use `:hello-time`.
+When the target is in other package, a full path from root should be used, like `//lib:hello-greet`.
+
+Now you are ready to build your hello world C++ binary:
+
+{% highlight bash %}
+bazel build main:hello-world
+{% endhighlight %}
+
+This produces the following output:
+
+{% highlight bash %}
+INFO: Found 1 target...
+Target //main:hello-world up-to-date:
+ bazel-bin/main/hello-world
+INFO: Elapsed time: 2.869s, Critical Path: 1.00s
+{% endhighlight %}
+
+{% highlight bash %}
+./bazel-bin/main/hello-world
+{% endhighlight %}
+
+This produces the following output:
+
+{% highlight bash %}
+Hello world
+Thu Jun 23 18:51:46 2016
+{% endhighlight %}
+
+{% highlight bash %}
+./bazel-bin/main/hello-world Bazel
+{% endhighlight %}
+
+This produces the following output:
+
+{% highlight bash %}
+Hello Bazel
+Thu Jun 23 18:52:10 2016
+{% endhighlight %}
+
+Congratulations, you've just built your first Bazel target!
+
+## Transitive includes
+
+If a file includes a header, then the file's rule should depend on that header's
+library. Conversely, only direct dependencies need to be specified as
+dependencies. For example, suppose `sandwich.h` includes `bread.h` and
+`bread.h` includes `flour.h`. `sandwich.h` doesn't include `flour.h` (who wants
+flour in their sandwich?), so the BUILD file would look like:
+
+```python
+cc_library(
+ name = "sandwich",
+ srcs = ["sandwich.cc"],
+ hdrs = ["sandwich.h"],
+ deps = [":bread"],
+)
+
+cc_library(
+ name = "bread",
+ srcs = ["bread.cc"],
+ hdrs = ["bread.h"],
+ deps = [":flour"],
+)
+
+cc_library(
+ name = "flour",
+ srcs = ["flour.cc"],
+ hdrs = ["flour.h"],
+)
+```
+
+Here, the `sandwich` library depends on the `bread` library, which depends
+on the `flour` library.
+
+## Adding include paths
+
+Sometimes you cannot (or do not want to) base include paths at the workspace
+root. Existing libraries might already have a include directory that doesn't
+match its path in your workspace. For example, suppose you have the following
+directory structure:
+
+```
+└── my-project
+ ├── third_party
+ │ └── some_lib
+ │ ├── BUILD
+ │ ├── include
+ │ │ └── some_lib.h
+ │ └── some_lib.cc
+ └── WORKSPACE
+```
+
+Bazel will expect `some_lib.h` to be included as
+`third_party/some_lib/include/some_lib.h`, but suppose `some_lib.cc` includes
+`"include/some_lib.h"`. To make that include path valid,
+`third_party/some_lib/BUILD` will need to specify that the `some_lib/`
+directory is an include directory:
+
+```python
+cc_library(
+ name = "some_lib",
+ srcs = ["some_lib.cc"],
+ hdrs = ["some_lib.h"],
+ copts = ["-Ithird_party/some_lib"],
+)
+```
+
+This is especially useful for external dependencies, as their header files
+must otherwise be included with an `external/[repository-name]/` prefix.
+
+## Including external libraries
+
+Suppose you are using [Google Test](https://github.com/google/googletest). You
+can use one of the `new_` repository functions in the `WORKSPACE` file to
+download Google Test and make it available in your repository:
+
+```python
+new_http_archive(
+ name = "gtest",
+ url = "https://github.com/google/googletest/archive/release-1.7.0.zip",
+ sha256 = "b58cb7547a28b2c718d1e38aee18a3659c9e3ff52440297e965f5edffe34b6d0",
+ build_file = "gtest.BUILD",
+)
+```
+
+Then create `gtest.BUILD`, a BUILD file to use to compile Google Test.
+Google Test has several "special" requirements that make its `cc_library` rule
+more complicated:
+
+* `googletest-release-1.7.0/src/gtest-all.cc` `#include`s all of the other files in
+ `googletest-release-1.7.0/src/`, so we need to exclude it from the compile or we'll get
+ link errors for duplicate symbols.
+* It uses header files that are relative to the `googletest-release-1.7.0/include/` directory
+ (`"gtest/gtest.h"`), so we must add that directory to the include paths.
+* It needs to link in pthread, so we add that as a `linkopt`.
+
+The final rule looks like this:
+
+```python
+cc_library(
+ name = "main",
+ srcs = glob(
+ ["googletest-release-1.7.0/src/*.cc"],
+ exclude = ["googletest-release-1.7.0/src/gtest-all.cc"]
+ ),
+ hdrs = glob([
+ "googletest-release-1.7.0/include/**/*.h",
+ "googletest-release-1.7.0/src/*.h"
+ ]),
+ copts = [
+ "-Iexternal/gtest/googletest-release-1.7.0/include"
+ ],
+ linkopts = ["-pthread"],
+ visibility = ["//visibility:public"],
+)
+```
+
+This is somewhat messy: everything is prefixed with googletest-release-1.7.0 as a byproduct
+of the archive's structure. You can make `new_http_archive` strip this prefix by
+adding the `strip_prefix` attribute:
+
+```python
+new_http_archive(
+ name = "gtest",
+ url = "https://github.com/google/googletest/archive/release-1.7.0.zip",
+ sha256 = "b58cb7547a28b2c718d1e38aee18a3659c9e3ff52440297e965f5edffe34b6d0",
+ build_file = "gtest.BUILD",
+ strip_prefix = "googletest-release-1.7.0",
+)
+```
+
+Then `gtest.BUILD` would look like this:
+
+```python
+cc_library(
+ name = "main",
+ srcs = glob(
+ ["src/*.cc"],
+ exclude = ["src/gtest-all.cc"]
+ ),
+ hdrs = glob([
+ "include/**/*.h",
+ "src/*.h"
+ ]),
+ copts = ["-Iexternal/gtest/include"],
+ linkopts = ["-pthread"],
+ visibility = ["//visibility:public"],
+)
+```
+
+Now `cc_` rules can depend on `@gtest//:main`.
+
+## Writing and running C++ tests
+
+For example, we could create a test `./test/hello-test.cc` such as:
+
+```cpp
+#include "gtest/gtest.h"
+#include "lib/hello-greet.h"
+
+TEST(HelloTest, GetGreet) {
+ EXPECT_EQ(get_greet("Bazel"), "Hello Bazel");
+}
+```
+
+Then create `./test/BUILD` file for your tests:
+
+```python
+cc_test(
+ name = "hello-test",
+ srcs = ["hello-test.cc"],
+ copts = ["-Iexternal/gtest/include"],
+ deps = [
+ "@gtest//:main",
+ "//lib:hello-greet",
+ ],
+)
+```
+
+Note in order to make `hello-greet` visible to `hello-test`, we have to add `"//test:__pkg__",` to `visibility` attribute in `./lib/BUILD`.
+
+Now you can use `bazel test` to run the test.
+
+{% highlight bash %}
+bazel test test:hello-test
+{% endhighlight %}
+
+This produces the following output:
+
+{% highlight bash %}
+INFO: Found 1 test target...
+Target //test:hello-test up-to-date:
+ bazel-bin/test/hello-test
+INFO: Elapsed time: 4.497s, Critical Path: 2.53s
+//test:hello-test PASSED in 0.3s
+
+Executed 1 out of 1 tests: 1 test passes.
+{% endhighlight %}
+
+
+## Adding dependencies on precompiled libraries
+
+If you want to use a library that you only have a compiled version of (e.g.,
+headers and a .so) wrap it in a `cc_library` rule:
+
+```python
+cc_library(
+ name = "mylib",
+ srcs = ["mylib.so"],
+ hdrs = ["mylib.h"],
+)
+```
+
+Then other C++ targets in your workspace can depend on this rule.
diff --git a/site/docs/tutorial/environment.md b/site/docs/tutorial/environment.md
index 8ce35d6..68548df 100644
--- a/site/docs/tutorial/environment.md
+++ b/site/docs/tutorial/environment.md
@@ -1,4 +1,91 @@
---
-layout: redirect
-redirect: docs/tutorial/environment.html
+layout: documentation
+title: Tutorial - Set Up Your Environment
---
+
+# Tutorial - Set Up Your Environment
+
+The first step in this tutorial is to set up your environment.
+
+Here, you'll do the following:
+
+* Install Bazel
+* Install Android Studio and the Android SDK
+* Install Xcode (macOS (OS X) only)
+* Get the sample project from the GitHub repo
+
+## Install Bazel
+
+Follow the [installation instructions](/docs/install.md) to install Bazel and
+its dependencies.
+
+## Install the Android SDK tools
+
+Do the following:
+
+1. Download and install the
+ [Android SDK Tools](https://developer.android.com/sdk/index.html#Other).
+
+2. Run the Android SDK Manager and install the following packages:
+
+ <table class="table table-condensed table-striped">
+ <thead>
+ <tr>
+ <td>Package</td>
+ <td>SDK directory</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Android SDK Platform Tools</td>
+ <td><code>platform-tools</code></td>
+ </tr>
+ <tr>
+ <td>Android SDK Build Tools</td>
+ <td><code>build-tools</code></td>
+ </tr>
+ <tr>
+ <td>Android SDK Platform</td>
+ <td><code>platform</code></td>
+ </tr>
+ </tbody>
+ </table>
+
+ The SDK Manager is an executable named `android` located in the `tools`
+ directory.
+
+## Install Xcode (OS X only)
+
+If you are following the steps in this tutorial on Mac OS X, download and
+install [Xcode](https://developer.apple.com/xcode/downloads/). The Xcode
+download contains the iOS libraries, Objective-C compiler other tools
+required by Bazel to build the iOS app.
+
+## Get the sample project
+
+You also need to get the sample project for the tutorial from GitHub:
+
+[https://github.com/bazelbuild/examples/](https://github.com/bazelbuild/examples/)
+
+The GitHub 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.
+
+Enter the following at the command line to get the files in the `source-only`
+branch:
+
+```bash
+cd $HOME
+git clone -b source-only https://github.com/bazelbuild/examples
+```
+
+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`.
+
+## What's next
+
+Now that you have set up your environment, you can
+[set up a Bazel workspace](workspace.md).
diff --git a/site/docs/tutorial/index.md b/site/docs/tutorial/index.md
deleted file mode 100644
index 3d2efad..0000000
--- a/site/docs/tutorial/index.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-layout: redirect
-redirect: docs/tutorial/app.html
----
\ No newline at end of file
diff --git a/site/docs/tutorial/ios-app.md b/site/docs/tutorial/ios-app.md
index e77b369..abf49d2 100644
--- a/site/docs/tutorial/ios-app.md
+++ b/site/docs/tutorial/ios-app.md
@@ -1,4 +1,207 @@
---
-layout: redirect
-redirect: docs/tutorial/ios-app.html
+layout: documentation
+title: Tutorial - Build an iOS App
---
+
+# Tutorial - Build an iOS App
+
+Like the [Android app](android-app.md) you built in the previous step, the iOS
+app is a simple mobile app that communicates with the
+[backend server](backend-server.md).
+
+Here, you'll do the following:
+
+* Review the source files for the app
+* Create a `BUILD` file
+* Build the app for the simulator
+* Find the build outputs
+* Run/Debug the app on the simulator
+* Build the app for a device
+* Install the app on a device
+
+Note that, unlike with the Android app, you don't have to modify your
+`WORKSPACE` file to add iOS-specific external dependencies.
+
+If you're following the steps in this tutorial on macOS (OS X), you can go ahead
+and build the sample iOS app as described below. If you are on Linux, skip ahead
+to the [next step](backend-server.md).
+
+## Review the source files
+
+Let's take a look at the source files for the app. These are located in
+`$WORKSPACE/ios-app/UrlGet`. Again, 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.
+
+## Create a BUILD file
+
+At a command-line prompt, open your new `BUILD` file for editing:
+
+```bash
+vi $WORKSPACE/ios-app/BUILD
+```
+
+## Add an objc_library rule
+
+Bazel provides several build rules that you can use to build an app for the
+iOS platform. For this tutorial, you'll first use the
+[`objc_library`](/docs/be/objective-c.html#objc_library) rule to tell Bazel
+how to build an
+[static library](https://developer.apple.com/library/ios/technotes/iOSStaticLibraries/Introduction.html)
+from the app source code and Xib files. Then you'll use the
+`objc_binary` rule to tell it how to bundle the iOS application. (Note that
+this is a minimal use case of the Objective-C rules in Bazel. For example, you
+have to use the `ios_application` rule to build multi-architecture iOS
+apps.)
+
+Add the following to your `BUILD` file:
+
+```python
+objc_library(
+ name = "UrlGetClasses",
+ srcs = [
+ "UrlGet/AppDelegate.m",
+ "UrlGet/UrlGetViewController.m",
+ ],
+ hdrs = glob(["UrlGet/*.h"]),
+ xibs = ["UrlGet/UrlGetViewController.xib"],
+)
+```
+
+Note the name of the rule, `UrlGetClasses`.
+
+## Add an objc_binary rule
+
+The [`objc_binary`](/docs/be/objective-c.html#objc_binary) rule creates a
+binary to be bundled in the application.
+
+Add the following to your `BUILD` file:
+
+```python
+objc_binary(
+ name = "ios-app-binary",
+ srcs = [
+ "UrlGet/main.m",
+ ],
+ deps = [
+ ":UrlGetClasses",
+ ],
+)
+
+```
+Note how the `deps` attribute references the output of the
+`UrlGetClasses` rule you added to the `BUILD` file above.
+
+## Add an ios_application rule
+
+The [`ios_application`](/docs/be/objective-c.html#ios_application) rule
+creates the bundled `.ipa` archive file for the application and also generates
+an Xcode project file.
+
+Add the following to your `BUILD` file:
+
+```python
+ios_application(
+ name = "ios-app",
+ binary = ":ios-app-binary",
+ infoplist = "UrlGet/UrlGet-Info.plist",
+)
+```
+
+Now, save and close the file. You can compare your `BUILD` file to the
+[completed example](https://github.com/bazelbuild/examples/blob/master/tutorial/ios-app/BUILD)
+in the `master` branch of the GitHub repo.
+
+## Build the app for the simulator
+
+Make sure that your current working directory is inside your Bazel workspace:
+
+```bash
+cd $WORKSPACE
+```
+
+Now, enter the following to build the sample app:
+
+```bash
+bazel build //ios-app:ios-app
+```
+
+Bazel now launches and builds the sample app. During the build process, its
+output will appear similar to the following:
+
+```bash
+INFO: Found 1 target...
+Target //ios-app:ios-app up-to-date:
+ bazel-bin/ios-app/ios-app.ipa
+ bazel-bin/ios-app/ios-app.xcodeproj/project.pbxproj
+INFO: Elapsed time: 3.765s, Critical Path: 3.44s
+```
+
+## Find the build outputs
+
+The `.ipa` file and other outputs are located in the
+`$WORKSPACE/bazel-bin/ios-app` directory.
+
+## Run/Debug the app on the simulator
+
+You can now run the app from Xcode using the iOS Simulator. To run the app,
+open the project directory `$WORKSPACE/bazel-bin/ios-app/ios-app.xcodeproj` in
+Xcode, choose an iOS Simulator as the runtime scheme and then click the **Run**
+button.
+
+**Note:** If you change anything about the project file set in Xcode (for
+example, if you add or remove a file, or add or change a dependency), you must
+rebuild the app using Bazel and then re-open the project.
+
+## Build the app for a device
+
+You need to set up bazel so that it can find the appropriate provisioning
+profile for the device you want to build for. To set up the "default"
+provisioning profile for all bazel builds:
+
+ 1. Go to [Apple Profiles](https://developer.apple.com/account/ios/profile/profileList.action)
+ and download the appropriate provisioning profile for your device.
+ If this is confusing, please refer to [Apple's documentation](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingProfiles/MaintainingProfiles.html).
+ 1. Move your profile into `$WORKSPACE/tools/objc`.
+ 1. Optional - You may want to add your profile to your `.gitignore`.
+ 1. Edit `$WORKSPACE/tools/objc/BUILD` and add:
+
+ ```python
+ filegroup(
+ name = "default_provisioning_profile",
+ srcs = ["<NAME OF YOUR PROFILE>.mobileprovision"],
+ )
+ ```
+
+Now you should be able to build the app for your device:
+
+```bash
+bazel build //ios-app:ios-app --ios_multi_cpus=armv7,arm64
+```
+
+This will build the app "fat". If you would prefer just to build for
+your specific device architecture you can designate a single architecture.
+
+If you would like to select a specific Xcode version you can do so
+with the `--xcode_version=7.2` option. If for some reason you need to specify
+a specific SDK version you can use the `--ios_sdk_version=9.2` option, but the
+`--xcode_version` should be sufficient in most circumstances.
+
+If you would like to specify a minimum version of iOS to run against, you can
+do so with the `--ios_minimum_os=7.0` option.
+
+## Install the app on a device
+
+The easiest way to install the app on the device is to launch Xcode and use the
+`Windows > Devices` command. Select your plugged in device from the list on the
+left, and then add the app by clicking on the "plus" sign under installed apps
+and selecting the `.ipa` that you built.
+
+If your app does not launch, please make sure that your device was on your
+provisioning profile. The `View Device Logs` button on the `Devices` screen in
+Xcode may provide other information as to what has gone wrong.
+
+## What's next
+
+The next step is to build a [backend server](backend-server.md) for the two
+mobile apps you built in this tutorial.
diff --git a/site/docs/tutorial/java.md b/site/docs/tutorial/java.md
index aeeac54..a916aeb 100644
--- a/site/docs/tutorial/java.md
+++ b/site/docs/tutorial/java.md
@@ -1,4 +1,576 @@
---
-layout: redirect
-redirect: docs/tutorial/java.html
+layout: documentation
+title: Introduction to Bazel
---
+
+Introduction to Bazel: Build Java
+==========
+
+This tutorial is an introduction for anyone getting started with Bazel. It
+focuses on the concepts, setup, and use of Bazel using a Java sample project.
+
+Estimated time: 30 min
+
+## What you will learn
+
+In this tutorial you'll learn how to:
+
+* Build a target from source files
+* Produce a visual representation of the dependency graph
+* Break a monolithic binary into smaller libraries
+* Use multiple Bazel packages
+* Control the visibility of a target between packages
+* Use labels to reference a target
+* Deploy your target
+
+## Before you begin
+
+* [Install Bazel](/docs/install.md)
+
+## Create the sample Java project
+
+The first step in this tutorial is to create a small Java project. Even though
+the project is in Java, this tutorial will focus on concepts that are helpful
+for using Bazel in any language.
+
+1. Create the directory `~/my-project/`
+
+2. Move to this directory:
+
+ ```
+ cd ~/my-project
+ ```
+
+3. Create the following directories under `my-project`:
+
+ ```
+ mkdir -p src/main/java/com/example
+ ```
+
+ Note that path uses conventions specific to Java programs. Programs written
+ in other languages may have a different workspace path and directory
+ structure.
+
+4. In the directory you created, add a file called `Greeting.java` with the
+ following contents:
+
+ ```java
+ package com.example;
+
+ public class Greeting {
+ public static void sayHi() {
+ System.out.println("Hi!");
+ }
+ }
+ ```
+
+5. Add a second file `ProjectRunner.java` with the following contents:
+
+ ```java
+ package com.example;
+
+ public class ProjectRunner {
+ public static void main(String args[]) {
+ Greeting.sayHi();
+ }
+ }
+ ```
+
+You’ve now created a small Java project. It contains one file that will be
+compiled into a library, and another which will be an executable that uses the
+library.
+
+The rest of this tutorial focuses on setting up and using Bazel to build these
+source files.
+
+## Build with Bazel
+
+### Set up the workspace
+
+Workspaces are directories that contain 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.
+
+To define the workspace, create an empty text file at the root of the project
+and name it `WORKSPACE`. You now have: `~/my-project/WORKSPACE`.
+
+This directory and its subdirectories are now part of the same workspace. When
+Bazel builds an output, all inputs and dependencies must be in the same
+workspace. Anything in different workspaces are independent of each other,
+though there are ways to link workspaces that are beyond the scope of this
+introduction tutorial.
+
+If you also do the [C++ tutorial](/docs/tutorial/cpp.md), you’ll notice it uses
+the same workspace. Bazel can understand multiple targets in multiple languages
+in a single workspace.
+
+### Create a BUILD file
+
+Bazel looks for files named `BUILD` which describe how to build the project.
+
+1. In the `~/my-project` directory, create a file and name it BUILD. This BUILD
+ file is a sibling of the WORKSPACE file.
+
+ In the BUILD file, you use a declarative language similar to Python to
+ create instances of Bazel rules. These instances are called *rule targets*.
+ In Bazel, *targets* are either files or rule targets and they are the
+ elements in a workspace that you can ask Bazel to build.
+
+ For this project, you’ll use the built-in rule `java_binary`. Bazel's
+ built-in rules are all documented in the
+ [Build Encyclopedia](/docs/be/overview.html). You can also create your own
+ rules using the [Bazel rule extension framework](/docs/skylark/concepts.md).
+
+2. Add this text to the BUILD file:
+
+ ```
+ java_binary(
+ name = "my-runner",
+ srcs = glob(["src/main/java/com/example/*.java"]),
+ main_class = "com.example.ProjectRunner",
+ )
+ ```
+As you can see, the text in the BUILD file doesn’t describe what Bazel does
+when it executes this rule target. The rule’s implementation handles the
+complexity of how it works (such as the compiler used).
+
+You can treat the rule as a black box, focusing on what inputs it needs, and
+the outputs it produces. This rule builds a Java archive ("jar file") as well
+as a wrapper shell script with the same name as the rule target.
+
+When you’re writing your own BUILD file, go to the
+[Build Encyclopedia](/docs/be/overview.html) for a description of what a rule
+does and for its list of possible attributes you can define. For example,
+here’s the entry for the [java_binary](/docs/be/java.html#java_binary) rule in
+the Build Encyclopedia. The Build Encyclopedia has information about all of the
+rules that are compiled into Bazel.
+
+Let’s take a look at the rule target that you added to the BUILD file.
+
+Each rule instantiation in the BUILD file creates one rule target. Here, you’ve
+instantiated the rule `java_binary`, creating the target `my-runner`.
+
+Different rules will require different attributes, though all must include a
+“name” attribute. You use these attributes to explicitly list all of the
+target’s dependencies and options. In the target above:
+
+* `my-runner` is the name of the rule target created
+
+* `glob(["src/main/java/com/example/*.java"])` includes every file in that
+ directory that ends with .java (see the Build Encyclopedia for more
+ information about [globbing](/docs/be/functions.html#glob))
+
+* `"com.example.ProjectRunner"` specifies the class that contains the main
+ method.
+
+### Build with Bazel
+
+Now you’re ready to build the Java binary. To do so, you’ll use the command
+`bazel build` with the target label `//:my-runner`. You reference targets by
+using their label. Label syntax is described later in this tutorial.
+
+1. Build my-runner by using this command:
+
+ ```
+ bazel build //:my-runner
+ ```
+
+ You’ll see output similar to:
+
+ ```
+ INFO: Found 1 target...
+ Target //:my-runner up-to-date:
+ bazel-bin/my-runner.jar
+ bazel-bin/my-runner
+ INFO: Elapsed time: 1.021s, Critical Path: 0.83s
+ ```
+
+2. Now execute the file by using this command:
+
+ ```
+ bazel-bin/my-runner
+ ```
+
+Congratulations, you've built your first Bazel target!
+
+Let’s take a look at what you built. In `~/my-project`, Bazel created the
+directory `bazel-bin` as well as other directories to store information about
+the build. Open this directory to look at the files created during the build
+process. These output directories keep the outputs separate from your source
+tree.
+
+### Review the dependency graph
+
+Bazel requires build dependencies to be explicitly declared in BUILD
+files. The build will fail if dependencies are missing, so when a build works
+the declared dependencies are accurate. With this explicit information about
+dependencies, Bazel creates a build graph and uses it to accurately perform
+incremental builds. Our small Java project isn’t too exciting, but let’s check
+out its build graph.
+
+The command `bazel query` retrieves information about the graph and the
+relationships between targets. Let’s use it to produce a visual representation
+of the build graph.
+
+1. From the root of the workspace (`my-project`), produce a text description
+ of the graph by using the command:
+
+ ```
+ bazel query --noimplicit_deps 'deps(//:my-runner)' --output graph
+ ```
+
+2. Then, paste the output into Graphviz
+ ([http://www.webgraphviz.com/](http://www.webgraphviz.com/)) to see the
+ visual representation.
+
+ The graph for the target my-runner will look like this:
+
+ 
+
+You can see that `my-runner` depends on the two source files in your Java
+project.
+
+You have now set up the workspace and BUILD file, and used Bazel to build your
+project. You have also created a visual representation of the build graph to
+see the structure of your build.
+
+## Refine your Bazel build
+
+### Add dependencies
+
+Creating one rule target to build your entire project may be sufficient for
+small projects. As projects get larger it's important to break up the build
+into self-contained libraries that can be assembled into a final product.
+Self-contained libraries mean that everything doesn't need to be rebuilt after
+small changes and that Bazel can parallelize more of the build steps. These
+self-contained libraries also encourages good code hygiene.
+
+To break up a project, create a separate rule target for the each subcomponent
+and then add the subcomponents as dependencies. For the project in this
+tutorial, create a rule target to compile the library, and make the executable
+depend on it.
+
+1. Replace the text in the BUILD file with the text below:
+
+ ```
+ java_binary(
+ name = "my-runner",
+ srcs = ["src/main/java/com/example/ProjectRunner.java"],
+ main_class = "com.example.ProjectRunner",
+ deps = [":greeter"],
+ )
+
+ java_library(
+ name = "greeter",
+ srcs = ["src/main/java/com/example/Greeting.java"],
+ )
+ ```
+
+The new `deps` attribute in `java_binary` tells Bazel that the `greeter` library
+will be needed to compile the binary. Rules for many languages support the
+`deps` attribute, though the exact semantics of the attribute will vary based
+on the language and the type of target. The rule
+[java_library](/docs/be/java.html#java_library) compiles sources into
+a .jar file. Remember to go to the [Build Encyclopedia](/docs/be/overview.html)
+for details about specific rules.
+
+This BUILD file builds the same files as before, but in a different way: now
+Bazel will first build the `greeter` library and then build `my-runner`.
+
+2. Try building //:my-runner using the command:
+
+ ```
+ bazel build //:my-runner
+ ```
+
+ You’ll see output similar to:
+
+ ```
+ INFO: Found 1 target...
+ Target //:my-runner up-to-date:
+ bazel-bin/my-runner.jar
+ bazel-bin/my-runner
+ INFO: Elapsed time: 2.454s, Critical Path: 1.58s
+ ```
+
+ 3. Execute the file by using this command::
+
+ ```
+ bazel-bin/my-runner
+ ```
+
+If you now edit `ProjectRunner.java` and rebuild `my-runner`, the source file
+`Greeting.java` will not be recompiled. When the BUILD file had only the one
+target, both source files would be recompiled after any change.
+
+Looking at the dependency graph, you can see that `my-runner` depends on the
+same inputs as it did before, but the structure of the build is different.
+
+The original dependency graph for `my-runner` looked link this:
+
+
+
+The dependency graph for `my-runner` after adding a dependency looks like this:
+
+
+
+### Use multiple packages
+
+For larger projects, you will often be dealing with several directories in your
+workspace. You can organize your build process by adding a BUILD file to the
+top directory of source files that you want to organize together. A directory
+containing a BUILD file is called a package.
+
+Note that Bazel and Java both have the concept of a package. These are
+unrelated to each other, though both are related to the structure of the
+directories.
+
+Let’s build the java project using multiple packages.
+
+1. First, let’s make the Java project a bit more complex.
+
+ 1. Add the following directory and file:
+
+ ```
+ mkdir -p src/main/java/com/example/cmdline
+ ```
+ 2. In the directory cmdline, add the file Runner.java with the following
+ contents:
+
+ ```java
+ package com.example.cmdline;
+
+ import com.example.Greeting;
+
+ public class Runner {
+ public static void main(String args[]) {
+ Greeting.sayHi();
+ }
+ }
+ ```
+
+ Now you have a slightly larger Java project that you can organize with
+ multiple packages.
+
+2. In the directory `src/main/java/com/example/cmdline`, add an empty text
+ file and name it BUILD. The structure of the Java project is now:
+
+ ```
+ ├── BUILD
+ ├── src
+ │ └── main
+ │ └── java
+ │ └── com
+ │ └── example
+ │ ├── cmdline
+ │ │ ├── BUILD
+ │ │ └── Runner.java
+ │ ├── Greeting.java
+ │ └── ProjectRunner.java
+ └── WORKSPACE
+ ```
+
+ Each directory in the workspace can be part of only one package. The
+ workspace now has two BUILD files, and so has two packages:
+
+ 1. The directory `my-project` and its subdirectories (but not including
+ subdirectories with their own BUILD file, such as `cmdline`), and
+
+ 2. The directory `cmdline` and any subdirectories.
+
+3. In the new BUILD file, add the following text:
+
+ ```
+ java_binary(
+ name = "runner",
+ srcs = ["Runner.java"],
+ main_class = "com.example.cmdline.Runner",
+ deps = ["//:greeter"]
+ )
+ ```
+
+ The file `Runner.java` depends on `com.example.Greeting`. In the BUILD file
+ this dependency is shown by listing the rule target `greeter` (with the
+ label `//:greeter`).
+
+ Below is what the dependency graph for runner will look like. You can see
+ how `//:greeter` gives the dependency on `Greeting.java`.
+
+ 
+
+
+4. However, if you try to build runner right now you'll get a permissions
+ error. You can see the permission error by trying to build the target using
+ the command:
+
+ ```
+ bazel build //src/main/java/com/example/cmdline:runner
+ ```
+
+ By default, rule targets are private, which means that they can only be
+ depended on by targets in the same BUILD file. This privacy prevents
+ libraries that are implementation details from leaking into public APIs,
+ but it also means that you must explicitly allow `runner` to depend on
+ `//:greeter`.
+
+
+5. Make a rule target visible to rule targets in other BUILD files by adding
+ a `visibility` attribute. To make the `greeter` rule target in
+ `~/my-project/BUILD` visible to any rule target in the new package, add the
+ following visibility attribute:
+
+ ```
+ java_library(
+ name = "greeter",
+ srcs = ["src/main/java/com/example/Greeting.java"],
+ visibility = ["//src/main/java/com/example/cmdline:__pkg__"],
+ )
+ ```
+
+ The target `//:greeter` is now visible to any target in the
+ `//src/main/java/com/example/cmdline` package.
+
+ See the Build Encyclopedia for more
+ [visibility options](/docs/be/common-definitions.html#common.visibility).
+
+
+6. Now you can build the runner binary by using the command:
+
+ ```
+ bazel build //src/main/java/com/example/cmdline:runner
+ ```
+
+ You’ll see output similar to:
+
+ ```
+ INFO: Found 1 target...
+ Target //src/main/java/com/example/cmdline:runner up-to-date:
+ bazel-bin/src/main/java/com/example/cmdline/runner.jar
+ bazel-bin/src/main/java/com/example/cmdline/runner
+ INFO: Elapsed time: 1.576s, Critical Path: 0.81s
+ ```
+
+
+7. Execute the file by using this command:
+
+ ```
+ bazel-bin/src/main/java/com/example/cmdline/runner
+ ```
+
+You’ve now refined your build so that it is broken down into smaller
+self-contained libraries, and so that the explicit dependencies are more
+granular. You’ve also built the Java project using multiple packages.
+
+## Use labels to reference targets
+
+In the BUILD files and in the command line, you have been using target labels
+to reference targets. The label’s syntax is: `//path/to/package:target-name`,
+where “`//`” is the workspace’s root, and “`:`” separates the package name and
+the target name. If the target is a rule target and so defined in a BUILD file,
+“`path/to/package`” would be the path of the BUILD file itself. “`Target-name`”
+would be the same as the “`name`” attribute in the target in the BUILD file.
+
+The first BUILD file you created in this tutorial is in the same directory as
+the WORKSPACE file. When referencing rule targets defined in that file, nothing
+is needed for the path to the package because the workspace root and the package
+root are the same directory. Here are the labels of the two targets defined
+in that first BUILD file:
+
+```
+//:my-runner
+//:greeter
+```
+
+The second BUILD file has a longer path from the workspace root to the package
+root. The label for the target in that BUILD file is:
+
+```
+//src/main/java/com/example/cmdline:runner
+```
+
+Target labels can be shortened in a variety of ways. Within a BUILD file, if
+you’re referencing a target from the same package, you can write the label
+starting at “`:`”. For example, the rule target `greeter` can always be written
+as `//:greeter`, and in the BUILD file where it’s defined, it can also be
+written as `:greeter`. This shortened label in a BUILD file makes it immediately
+clear which targets are in the current package.
+
+A rule target’s name will always be defined by its name attribute. A target’s
+name is a bit more complex when it’s in a directory other than the root
+of the package. In that case, the target’s label is:
+`//path/to/package:path/to/file/file_name`.
+
+## Package a Java target for deployment
+
+To understand what you’ve built and what else can be built with Bazel, you need
+to understand the capabilities of the rules used in your BUILD files. Always go
+to the [Build Encyclopedia](/docs/be/overview.html) for this information.
+
+Let’s look at packaging a Java target for deployment, which requires you to
+know the capabilities of the rule `java_binary`.
+
+You’re able to run the Java binaries you created in this tutorial, but you
+can’t simply run it on a server, because it relies on the greeting library jar
+to actually run. "Packaging an artifact so it can be run reliably outside the
+development environment involves bundling it with all of its runtime
+dependencies. Let's see now what’s needed to package the binaries.
+
+The rule [java_binary](/docs/be/java.html#java_binary) produces a Java archive
+(“jar file”) and a wrapper shell script. The file `<target-name>_deploy.jar`
+is suitable for deployment, but it’s only built by this rule if explicitly
+requested. Let’s investigate.
+
+1. Look at the contents of the output `runner.jar` by using this command:
+
+ ```
+ jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar
+ ```
+
+ You’ll see output similar to:
+
+ ```
+ META-INF/
+ META-INF/MANIFEST.MF
+ com/
+ com/example/
+ com/example/cmdline/
+ com/example/cmdline/Runner.class
+ ```
+
+ You can see that `runner.jar` contains `Runner.class`, but not its
+ dependency `Greeting.class`. The `runner` script that Bazel generates adds
+ the greeter jar to the classpath, so running this program works locally. It
+ will not work if you want to copy `runner.jar` to another machine and use
+ it as a standalone binary.
+
+
+2. The rule `java_binary` allows you to build a self-contained binary that can
+ be deployed. To create this binary, build `runner_deploy.jar` (or, more
+ generally, `<target-name>_deploy.jar`) by using this command:
+
+ ```
+ bazel build //src/main/java/com/example/cmdline:runner_deploy.jar
+ ```
+
+ You’ll see output similar to:
+
+ ```
+ INFO: Found 1 target...
+ Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date:
+ bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar
+ INFO: Elapsed time: 1.700s, Critical Path: 0.23s
+ ```
+
+ The file runner_deploy.jar will contain all of its dependencies, and so can
+ be used as a standalone binary.
+
+You’ve now created a Java target that you can distribute and deploy. To do so,
+you had to be aware of what outputs the Bazel Java rule `java_binary` is able to
+produce.
+
+## Further topics
+
+* Try the tutorial [Build C++](/docs/tutorial/cpp.md).
+* Try the tutorial [Build Mobile Application](/docs/tutorial/app.md).
+
diff --git a/site/docs/tutorial/review.md b/site/docs/tutorial/review.md
index 16557f7..62d4501 100644
--- a/site/docs/tutorial/review.md
+++ b/site/docs/tutorial/review.md
@@ -1,4 +1,29 @@
---
-layout: redirect
-redirect: docs/tutorial/review.html
+layout: documentation
+title: Tutorial - Review
---
+
+# Tutorial - Review
+
+In this tutorial, you used Bazel to build an [Android app](android-app.md),
+an [iOS app](ios-app.md) and a [backend server](backend-server.md) that runs on
+Google App Engine.
+
+To build these software outputs, you:
+
+* Set up a Bazel [workspace](workspace.md) that contained the source code
+ for the components and a `WORKSPACE` that identifies the top level of the
+ workspace directory
+* Created a `BUILD` file for each component
+* Updated the `WORKSPACE` file to contain references to the required
+ external dependencies
+* Ran Bazel to build the software components
+
+The built mobile apps and backend server application files are located in the
+`$WORKSPACE/bazel-bin` directory.
+
+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.
diff --git a/site/docs/tutorial/workspace.md b/site/docs/tutorial/workspace.md
index 76a2a7c..eee1b1a 100644
--- a/site/docs/tutorial/workspace.md
+++ b/site/docs/tutorial/workspace.md
@@ -1,4 +1,53 @@
---
-layout: redirect
-redirect: docs/tutorial/workspace.html
+layout: documentation
+title: Tutorial - Set Up a Workspace
---
+
+# Tutorial - Set Up a Workspace
+
+A [workspace](/docs/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.
+
+A workspace directory can be located anywhere on your filesystem. 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.
+
+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 common conventions for Android apps, iOS apps and App
+Engine applications.
+
+For your convenience, set the `$WORKSPACE` environment variable now to refer to
+your workspace directory. At the command line, enter:
+
+```bash
+export WORKSPACE=$HOME/examples/tutorial
+```
+
+## Create a WORKSPACE file
+
+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](/docs/external.html) required to build the
+software.
+
+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.
+
+Enter the following at the command line:
+
+```bash
+touch $WORKSPACE/WORKSPACE
+```
+
+This creates the empty `WORKSPACE` file.
+
+## What's next
+
+Now that you've set up your workspace, you can
+[build the Android app](android-app.md).
