Make README be a table of contents to our docs.

Move installation instructions to docs/install.md -- MOS_MIGRATED_REVID=88559019
lgscofield · Mar 16, 2015 · 7923a48 · 7923a48
1 parent 4862756
commit 7923a48
Show file tree

Hide file tree

Showing 2 changed files with 100 additions and 81 deletions.
diff --git a/README.md b/README.md
@@ -1,7 +1,3 @@
-*Bazel is very much a work in progress. We'd love if you tried it out, but there
-are many rough edges. Please feel free to
-[give us feedback](https://groups.google.com/forum/#!forum/bazel-discuss)!*
-
 # Bazel
 
 *{Fast, Correct} - Choose two*
@@ -11,84 +7,21 @@ It executes as few build steps as possible by tracking dependencies and outputs,
 controls the build environment to keep builds hermetic, and uses its
 knowledge of dependencies to parallelize builds.
 
-This README file contains instructions for building and running Bazel.
-
-## System Requirements
-
-Supported platforms:
-
-* Ubuntu Linux
-* Mac OS X
-
-Java:
-
-* Java JDK 8 or later
-
-## Getting Bazel
-
-1. Clone the Bazel repo from GitHub:
-
-        $ cd $HOME
-        $ git clone https://github.com/google/bazel/
-
-## Building Bazel
-
-### Building Bazel on Ubuntu
-
-To build Bazel on Ubuntu:
-
-1. Install required package:
-
-        $ sudo apt-get install libarchive-dev openjdk-8-jdk
-
-2. Build Bazel:
-
-        $ cd bazel
-        $ ./compile.sh
-
-### Building Bazel on OS X (experimental)
-
-Using Bazel on Mac OS X requires:
-
-* Xcode and Xcode command line tools
-* MacPorts or Homebrew for installing required packages
-* A JDK 8 installed
-
-To build Bazel on Mac OS X:
-
-1. Install required packages:
-
-        $ port install protobuf-cpp libarchive
-
-   or
-
-        $ brew install protobuf libarchive
-
-2. Build Bazel:
-
-        $ cd bazel
-        $ ./compile.sh
-
-## Running Bazel
-
-The Bazel executable is located at `<bazel_home>/output/bazel`.
-
-You must run Bazel from within a _workspace directory_. Bazel provides a default
-workspace directory with sample `BUILD` files and source code in
-`<bazel_home>/base_workspace`. The default workspace contains files and
-directories that must be present in order for Bazel to work. If you want to
-build from source outside the default workspace directory, copy the entire
-`base_workspace` directory to the new location before adding your `BUILD` and
-source files.
-
-Build a sample Java application:
+* Find more background in our [FAQ](docs/FAQ.md)
 
-        $ cp -R $HOME/bazel/base_workspace $HOME/my_workspace
-        $ cd $HOME/my_workspace
-        $ $HOME/bazel/output/bazel build //examples/java-native/src/main/java/com/example/myproject:hello-world
+* Start using Bazel:
 
-The build output is located in `$HOME/my_workspace/bazel-bin/examples/java-native/src/main/java/com/example/myproject/`.
+  * How to [install Bazel](docs/install.md)
+  * How to [get started using Bazel](docs/getting-started.md)
+  * How to [use the query command](docs/bazel-query-v2.html)
+  * How to [extend Bazel](docs/skylark/index.md)
+  * TODO(bazel-team): link to the build encyclopedia.
+  * TODO(bazel-team): link to the user-manual
+  * TODO(bazel-team): link to the test encyclopedia?
 
-Run the sample application:
+* About the Bazel project:
 
-    $ $HOME/my_workspace/bazel-bin/examples/java-native/src/main/java/com/example/myproject/hello-world
+  * How to [contribute to Bazel](docs/contributing.md)
+  * Our [governance plan](docs/governance.md)
+  * Future plans are in the [roadmap](docs/roadmap.md)
+  * For each feature, which level of [support](docs/support.md) to expect.
diff --git a/docs/install.md b/docs/install.md
@@ -0,0 +1,86 @@
+# Compiling Bazel
+
+This file contains instructions for building and running Bazel.
+
+## System Requirements
+
+Supported platforms:
+
+* Ubuntu Linux
+* Mac OS X
+
+Java:
+
+* Java JDK 8 or later
+
+## Getting Bazel
+
+1. Clone the Bazel repo from GitHub:
+
+        $ cd $HOME
+        $ git clone https://github.com/google/bazel/
+
+## Building Bazel
+
+### Building Bazel on Ubuntu
+
+To build Bazel on Ubuntu:
+
+1. Install required package:
+
+        $ sudo apt-get install libarchive-dev openjdk-8-jdk
+
+2. Build Bazel:
+
+        $ cd bazel
+        $ ./compile.sh
+
+### Building Bazel on OS X
+
+Using Bazel on Mac OS X requires:
+
+* Xcode and Xcode command line tools
+* MacPorts or Homebrew for installing required packages
+* A JDK 8 installed
+
+To build Bazel on Mac OS X:
+
+
+1. Install required packages:
+
+        $ port install protobuf-cpp libarchive
+
+   or
+
+        $ brew install protobuf libarchive
+
+2. Build Bazel:
+
+        $ cd bazel
+        $ ./compile.sh
+
+## Running Bazel
+
+The Bazel executable is located at `<bazel_home>/output/bazel`.
+
+You must run Bazel from within a _workspace directory_. Bazel provides a default
+workspace directory with sample `BUILD` files and source code in
+`<bazel_home>/base_workspace`. The default workspace contains files and
+directories that must be present in order for Bazel to work. If you want to
+build from source outside the default workspace directory, copy the entire
+`base_workspace` directory to the new location before adding your `BUILD` and
+source files.
+
+Build a sample Java application:
+
+        $ cp -R $HOME/bazel/base_workspace $HOME/my_workspace
+        $ cd $HOME/my_workspace
+        $ $HOME/bazel/output/bazel build //examples/java-native/src/main/java/com/example/myproject:hello-world
+
+The build output is located in `$HOME/my_workspace/bazel-bin/examples/java-native/src/main/java/com/example/myproject/`.
+
+Run the sample application:
+
+    $ $HOME/my_workspace/bazel-bin/examples/java-native/src/main/java/com/example/myproject/hello-world
+
+For more information, see [Getting started](getting-started.md).