Update getting started documentation

--
MOS_MIGRATED_REVID=101955117

1 files changed, 104 insertions, 144 deletions

diff --git a/site/docs/getting-started.md b/site/docs/getting-started.md
index 479a5332bf..18d89bcab4 100644
--- a/site/docs/getting-started.md
+++ b/site/docs/getting-started.md
@@ -6,29 +6,18 @@ layout: documentation
 
 ## Setup
 
-Clone the Bazel [Github repo](https://github.com/google/bazel) and run the
-provided compile script. Make sure that you are running Bazel on a supported
-platform and that you have installed other required software as described in the
-[installation guide](install.html).
-
-{% highlight bash %}
-$ git clone https://github.com/google/bazel.git
-$ cd bazel
-$ ./compile.sh
-{% endhighlight %}
-
-`./compile.sh` creates the `bazel` executable in `output/bazel`.
-
-_**Note:** Bazel may support a binary installation at a later time._
+Use the [installation instructions](/docs/install.html) to install a copy of
+Bazel on your machine.
 
 ## Using a workspace
 
-A [workspace](/docs/build-ref.html#workspaces) is a directory on your filesystem
-that contains source code for the software you want to build, as well symbolic
-links to directories that contain the build outputs (for example, `bazel-bin`
-and `bazel-out`). The location of the workspace directory is not significant,
-but it must contain a file called `WORKSPACE` in the top-level directory. The
-`WORKSPACE` file may be an empty file, or it may contain references to
+All Bazel builds take place in a [_workspace_](/docs/build-ref.html#workspaces),
+a directory on your filesystem that contains source code for the software you
+want to build, as well symbolic links to directories that contain the build
+outputs (for example, `bazel-bin` and `bazel-out`). The location of the
+workspace directory is not significant, but it must contain a file called
+`WORKSPACE` in the top-level directory. The `WORKSPACE` file may be an empty
+file, or it may contain references to
 [external dependencies](/docs/external.html) required to build the outputs.
 
 One workspace can be shared among multiple projects if desired.  To get
@@ -38,77 +27,15 @@ 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.
 
-## Sanity Check: Building an Example
-
-To make sure that you have installed Bazel correctly, build one of the examples
-from the `examples/` directory.
-
-{% highlight bash %}
-$ cd ~/gitroot/my-project
-$ bazel build examples/java-native/src/main/java/com/example/myproject:hello-world
-Extracting Bazel installation...
-...........
-INFO: Found 1 target...
-Target //examples/java-native/src/main/java/com/example/myproject:hello-world up-to-date:
-  bazel-bin/examples/java-native/src/main/java/com/example/myproject/hello-world.jar
-  bazel-bin/examples/java-native/src/main/java/com/example/myproject/hello-world
-INFO: Elapsed time: 3.040s, Critical Path: 1.14s
-$ bazel-bin/examples/java-native/src/main/java/com/example/myproject/hello-world
-Hello world
-{% endhighlight %}
-
-Bazel puts binaries it has built under `bazel-bin/`.  Note that you can
-always look at the `build` command's output to find output file paths.
-
 ## Creating Your Own Build File
 
-Now you can create your own BUILD file and start adding build rules. This
-example assumes that `my-project/` is a Java project.  See the
-[build encyclopedia](build-encyclopedia.html)
-for advice on adding build rules for other languages.
-
-Note that when we ran "bazel build" above, the third argument started with a
-filesystem path ("examples/java"), followed by a colon. When you run
-`bazel build examples/java-native/src/main/java/com/example/myproject:hello-world`,
-Bazel will look for a special file named BUILD in the
-`examples/java-native/src/main/java/com/example/myproject/` subdirectory. This
-BUILD file defines rules about how Bazel should build things in this
-subdirectory.
-
-Thus, to add build rules to my-project, create a file named `BUILD` in the
-`my-project/` directory.  Add the following lines to this BUILD file:
-
-{% highlight python %}
-# ~/gitroot/base_workspace/my-project/BUILD
-java_binary(
-    name = "my-runner",
-    srcs = glob(["**/*.java"]),
-    main_class = "com.example.ProjectRunner",
-)
-{% endhighlight %}
-
-BUILD files are Python-like scripts. BUILD files cannot contain arbitrary
-Python, but each build rule looks like a Python function call and you can use
-"#" to start a single-line comment.
-
-`java_binary` is the type of thing this rule will build.
-`name` is how you'll refer to the rule when you run "bazel build"
-(in the "examples/java:hello-world" build above the `name` was
-"hello-world"). `srcs` lists the Java source files Bazel should
-compile into a Java binary.  `glob(["**/*.java"])` is a handy
-shorthand for "recursively include every file that ends with .java" (see the
-[user manual](bazel-user-manual.html)
-for more information about globbing). Replace `com.example.ProjectRunner` with
-the class that contains the main method.
-
-If you have no actual Java project you're using, you can use the following
-commands to make a fake project for this example:
+Use the following commands to make a small Java project for this example:
 
 {% highlight bash %}
 $ # If you're not already there, move to your workspace directory.
-$ cd ~/gitroot/base_workspace
-$ mkdir -p my-project/java/com/example
-$ cat > my-project/java/com/example/ProjectRunner.java <<EOF
+$ cd ~/gitroot/my-project
+$ mkdir -p src/main/java/com/example
+$ cat > src/main/java/com/example/ProjectRunner.java <<EOF
 package com.example;
 
 public class ProjectRunner {
@@ -117,7 +44,7 @@ public class ProjectRunner {
     }
 }
 EOF
-$ cat > my-project/java/com/example/Greeting.java <<EOF
+$ cat > src/main/java/com/example/Greeting.java <<EOF
 package com.example;
 
 public class Greeting {
@@ -128,20 +55,47 @@ public class Greeting {
 EOF
 {% endhighlight %}
 
-Now build your project:
+Bazel figures out what to build by looking for files named `BUILD` in your
+workspace, so we'll create a `BUILD` file in the `~/gitroot/my-project`
+directory.  Add the following lines to this BUILD file:
+
+{% highlight python %}
+# ~/gitroot/my-project/BUILD
+java_binary(
+    name = "my-runner",
+    srcs = glob(["**/*.java"]),
+    main_class = "com.example.ProjectRunner",
+)
+{% endhighlight %}
+
+BUILD files are Python-like scripts. BUILD files cannot contain arbitrary
+Python, but each build rule looks like a Python function call and you can use
+"#" to start a single-line comment.
+
+`java_binary` is the type of thing this rule will build. `name` is the
+identifier you'll use when you ask bazel to build the binary. `srcs` lists the
+Java source files Bazel should compile into a Java binary.
+`glob(["**/*.java"])` is a handy shorthand for "recursively include every file
+that ends with .java" (see the
+[build encyclopedia](build-encyclopedia.html#glob) for more information about
+globbing). `com.example.ProjectRunner` specifies the class that contains the
+main method.
+
+Now you are ready to build your Java binary:
 
 {% highlight bash %}
-$ bazel build my-project:my-runner
+$ cd ~/gitroot/my-project
+$ bazel build //:my-runner
 INFO: Found 1 target...
-Target //my-project:my-runner up-to-date:
-  bazel-bin/my-project/my-runner.jar
-  bazel-bin/my-project/my-runner
+Target //:my-runner up-to-date:
+  bazel-bin/my-runner.jar
+  bazel-bin/my-runner
 INFO: Elapsed time: 1.021s, Critical Path: 0.83s
-$ bazel-bin/my-project/my-runner
+$ bazel-bin/my-runner
 Hi!
 {% endhighlight %}
 
-Congratulations, you've created your first Bazel BUILD file!
+Congratulations, you've just built your first Bazel target!
 
 ## Adding Dependencies
 
@@ -153,50 +107,52 @@ parallelize more of the build steps.
 
 To break up a project, create separate rules for each subcomponent and then
 make them depend on each other. For the example above, add the following rules
-to the `my-project/BUILD` file:
+to the `BUILD` file:
 
 {% highlight python %}
 java_binary(
     name = "my-other-runner",
-    srcs = ["java/com/example/ProjectRunner.java"],
+    srcs = ["src/main/java/com/example/ProjectRunner.java"],
     main_class = "com.example.ProjectRunner",
     deps = [":greeter"],
 )
 
 java_library(
     name = "greeter",
-    srcs = ["java/com/example/Greeting.java"],
+    srcs = ["src/main/java/com/example/Greeting.java"],
 )
 {% endhighlight %}
 
-Now you can build and run `my-project:my-other-runner`:
+This builds the same files as before, but in a different way: now Bazel will
+build the `greeter` library first and then build `my-other-runner`. Try building
+and running `//:my-other-runner`:
 
 {% highlight bash %}
-$ bazel run my-project:my-other-runner
+$ bazel run //:my-other-runner
 INFO: Found 1 target...
-Target //my-project:my-other-runner up-to-date:
-  bazel-bin/my-project/my-other-runner.jar
-  bazel-bin/my-project/my-other-runner
+Target //:my-other-runner up-to-date:
+  bazel-bin/my-other-runner.jar
+  bazel-bin/my-other-runner
 INFO: Elapsed time: 2.454s, Critical Path: 1.58s
 
-INFO: Running command line: bazel-bin/my-project/my-other-runner
+INFO: Running command line: bazel-bin/my-other-runner
 Hi!
 {% endhighlight %}
 
-If you edit _ProjectRunner.java_ and rebuild `my-other-runner`, only
-`ProjectRunner.java` needs to be rebuilt (<code>greeter</code> is unchanged).
+Now if you edit `ProjectRunner.java` and rebuild `my-other-runner`,
+`Greeting.java` will not need to be recompiled.
 
 ## Using Multiple Packages
 
 For larger projects, you will often be dealing with several directories. You
 can refer to targets defined in other BUILD files using the syntax
-`//package-name:target-name`.  For example, suppose
-`my-project/java/com/example/` has a `cmdline/` subdirectory with the following
+`//path/to/directory:target-name`.  For example, suppose
+`src/main/java/com/example/` has a `cmdline/` subdirectory with the following
 file:
 
 {% highlight bash %}
-$ mkdir my-project/java/com/example/cmdline
-$ cat > my-project/java/com/example/cmdline/Runner.java <<EOF
+$ mkdir src/main/java/com/example/cmdline
+$ cat > src/main/java/com/example/cmdline/Runner.java <<EOF
 package com.example.cmdline;
 
 import com.example.Greeting;
@@ -209,72 +165,73 @@ public class Runner {
 EOF
 {% endhighlight %}
 
-We could add a `BUILD` file at `my-project/java/com/example/cmdline/BUILD`
-that contained the following rule:
+`Runner.java` depends on `com.example.Greeting`, so we could add a `BUILD` file
+at `src/main/java/com/example/cmdline/BUILD` that contained the following rule:
 
 {% highlight python %}
-# ~/gitroot/base_workspace/my-project/java/com/example/cmdline/BUILD
+# ~/gitroot/my-project/src/main/java/com/example/cmdline/BUILD
 java_binary(
     name = "runner",
     srcs = ["Runner.java"],
     main_class = "com.example.cmdline.Runner",
-    deps = ["//my-project:greeter"]
+    deps = ["//:greeter"]
 )
 {% endhighlight %}
 
 However, by default, build rules are _private_. This means that they can only be
 referred to by rules in the same BUILD file. This prevents libraries that are
 implementation details from leaking into public APIs, but it also means that you
-must explicitly allow `runner` to depend on `my-project:greeter`. As is, if we
+must explicitly allow `runner` to depend on `//:greeter`. As is, if we
 build `runner` we'll get a permissions error:
 
 {% highlight bash %}
-$ bazel build my-project/java/com/example/cmdline:runner
-ERROR: /usr/local/google/home/kchodorow/gitroot/base_workspace/my-project/java/com/example/cmdline/BUILD:2:1:
-  Target '//my-project:greeter' is not visible from target '//my-project/java/com/example/cmdline:runner'.
+$ bazel build //src/main/java/com/example/cmdline:runner
+ERROR: /home/user/gitroot/my-project/src/main/java/com/example/cmdline/BUILD:2:1:
+  Target '//:greeter' is not visible from target '//src/main/java/com/example/cmdline:runner'.
   Check the visibility declaration of the former target if you think the dependency is legitimate.
-ERROR: Analysis of target '//my-project/java/com/example/cmdline:runner' failed; build aborted.
+ERROR: Analysis of target '//src/main/java/com/example/cmdline:runner' failed; build aborted.
 INFO: Elapsed time: 0.091s
 {% endhighlight %}
 
 You can make a rule visibile to rules in other BUILD files by adding a
 `visibility = level` attribute.  Change the `greeter` rule in
-_my-project/BUILD_ to be visible to our new rule:
+`~/gitroot/my-project/BUILD` to be visible to our new rule:
 
 {% highlight python %}
 java_library(
     name = "greeter",
-    srcs = ["java/com/example/Greeting.java"],
-    visibility = ["//my-project/java/com/example/cmdline:__pkg__"],
+    srcs = ["src/main/java/com/example/Greeting.java"],
+    visibility = ["//src/main/java/com/example/cmdline:__pkg__"],
 )
 {% endhighlight %}
 
-This makes `//my-project:greeter` visible to any rule in the
-`//my-project/java/com/example/cmdline` package. Now we can build and
-run the binary:
+This makes `//:greeter` visible to any rule in the
+`//src/main/java/com/example/cmdline` package. Now we can build and
+run the `runner` binary:
 
 {% highlight bash %}
-$ bazel run my-project/java/com/example/cmdline:runner
+$ bazel run //src/main/java/com/example/cmdline:runner
 INFO: Found 1 target...
-Target //my-project/java/com/example/cmdline:runner up-to-date:
-  bazel-bin/my-project/java/com/example/cmdline/runner.jar
-  bazel-bin/my-project/java/com/example/cmdline/runner
+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
 
-INFO: Running command line: bazel-bin/my-project/java/com/example/cmdline/runner
+INFO: Running command line: bazel-bin/src/main/java/com/example/cmdline/runner
 Hi!
 {% endhighlight %}
 
-See the [build encyclopedia](build-encyclopedia.html) for more visibility options.
+See the [build encyclopedia](build-encyclopedia.html#common.visibility) for more
+visibility options.
 
 ## Deploying
 
 If you look at the contents of
-_bazel-bin/my-project/java/com/example/cmdline/runner.jar_, you can see that it
+_bazel-bin/src/main/java/com/example/cmdline/runner.jar_, you can see that it
 only contains `Runner.class`, not its dependencies (`Greeting.class`):
 
 {% highlight bash %}
-$ jar tf bazel-bin/my-project/java/com/example/cmdline/runner.jar
+$ jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar
 META-INF/
 META-INF/MANIFEST.MF
 com/
@@ -283,14 +240,17 @@ com/example/cmdline/
 com/example/cmdline/Runner.class
 {% endhighlight %}
 
-To deploy a `runner` binary, we need a self-contained jar. To build this, build
-`runner_deploy.jar` (or, more generally, `<target-name>_deploy.jar`):
+This works for running locally (the `runner` script Bazel generates adds the
+greeter jar to the classpath) but will not work if we want to copy `runner.jar`
+to another machine and use it as a standalone binary. To build a self-contained
+jar that can be deployed, build `runner_deploy.jar` (or, more generally,
+`<target-name>_deploy.jar`):
 
 {% highlight bash %}
-$ bazel build my-project/java/com/example/cmdline:runner_deploy.jar
+$ bazel build //src/main/java/com/example/cmdline:runner_deploy.jar
 INFO: Found 1 target...
-Target //my-project/java/com/example/cmdline:runner_deploy.jar up-to-date:
-  bazel-bin/my-project/java/com/example/cmdline/runner_deploy.jar
+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
 {% endhighlight %}
 
@@ -298,10 +258,10 @@ INFO: Elapsed time: 1.700s, Critical Path: 0.23s
 
 ## Next Steps
 
-You can now create your own targets and compose them.  See the [build
-encyclopedia](build-encyclopedia.html)
-and Bazel
-[user manual](bazel-user-manual.html)
-for more information.
-[Let us know](https://groups.google.com/forum/#!forum/bazel-discuss)
-if you have any questions!
+You can now create your own targets and compose them. Next, check out the
+[tutorial](/docs/tutorial/index.html) to learn how to build a server backend,
+Android app, and iOS app with Bazel. Also see the
+[build encyclopedia](build-encyclopedia.html) and
+[user manual](bazel-user-manual.html) for more information.
+[Let us know](https://groups.google.com/forum/#!forum/bazel-discuss) if you have
+any questions!