Update getting started instructions with .bazelrc strategy

--
MOS_MIGRATED_REVID=90418845

7 files changed, 28 insertions, 78 deletions

diff --git a/base_workspace/WORKSPACE b/base_workspace/WORKSPACE
deleted file mode 100644
index e69de29bb2..0000000000
--- a/base_workspace/WORKSPACE
+++ /dev/null
diff --git a/compile.sh b/compile.sh
index f7718ac6f4..39de894aa5 100755
--- a/compile.sh
+++ b/compile.sh
@@ -118,11 +118,6 @@ EOF
   esac
 }
 
-# Create symlinks so we can use tools and examples from the base_workspace.
-rm -f base_workspace/tools && ln -s "$(pwd)/tools" base_workspace/tools
-rm -f base_workspace/third_party && ln -s "$(pwd)/third_party" base_workspace/third_party
-rm -f base_workspace/examples && ln -s "$(pwd)/examples" base_workspace/examples
-
 case "${PLATFORM}" in
 linux)
   # Sorry, no static linking on linux for now.
@@ -477,4 +472,18 @@ create_deploy_jar "precomp_xcodegen_deploy" "com.google.devtools.build.xcode.xco
 
 cp -f output/actoolzip/precomp_actoolzip_deploy.jar output/ibtoolzip/precomp_ibtoolzip_deploy.jar output/momczip/precomp_momczip_deploy.jar output/bundlemerge/precomp_bundlemerge_deploy.jar output/plmerge/precomp_plmerge_deploy.jar output/xcodegen/precomp_xcodegen_deploy.jar tools/objc/
 
+# Create a bazelrc file with this directory in the package path.
+package_path="build --package_path %workspace%:$(pwd)"
+if [ ! -f $HOME/.bazelrc ]; then
+  log "Creating a .bazelrc pointing to this directory"
+  cat > $HOME/.bazelrc <<EOF
+$package_path
+EOF
+else
+  warning="You already have a .bazelrc. please modify it to add $(pwd) "
+  warning="$warning to your build package path."
+  old_line=$(fgrep "build --package_path " ~/.bazelrc) || true
+  [[ $package_path != $old_line ]] && log "$warning"
+fi
+
 log "Build successful! Binary is here: ${PWD}/output/bazel"
diff --git a/examples/java-skylark/README.md b/examples/java-skylark/README.md
index 970a859f54..b50c8ec677 100644
--- a/examples/java-skylark/README.md
+++ b/examples/java-skylark/README.md
@@ -1,7 +1,6 @@
 Skylark Java Examples
 =====================
 
-Use the native Java rules (see the examples in
-_base_workspace/examples/java-native_) for building Java, not these. These
-files are examples of how Skylark rules can be used (see
-_tools/build_rules/java_rules_skylark.bzl_ for the rule definitions).
+Use the native Java rules (see the examples in _examples/java-native_) for
+building Java, not these. These files are examples of how Skylark rules can be
+used (see _tools/build_rules/java_rules_skylark.bzl_ for the rule definitions).
diff --git a/site/FAQ.md b/site/FAQ.md
index b424a5f950..1146b5841d 100644
--- a/site/FAQ.md
+++ b/site/FAQ.md
@@ -242,8 +242,8 @@ How can I start using Bazel?
 See our [getting started document](docs/getting-started.html).
 
 
-Why do I need to have a tools/ directory in my source tree?
-----------------------------------------------------
+Why do I need to have a tools/ directory in my package path?
+------------------------------------------------------------
 
 Your project never works in isolation. Typically, it builds with a
 certain version of the JDK/C++ compiler, with a certain test driver
@@ -259,9 +259,9 @@ the configuration data for this (where is the JDK, where is the C++
 compiler?) still needs to be somewhere, and that place is also the
 `tools/` directory.
 
-Bazel comes with a `base_workspace/` directory, containing a minimal set
-of configuration files, suitable for running toolchains from standard
-system directories, e.g., `/usr/bin/`.
+Bazel's `compile.sh` script builds a minimal set of configuration files,
+suitable for running toolchains from standard system directories, e.g.,
+`/usr/bin/`.
 
 
 Doesn't Docker solve the reproducibility problems?
diff --git a/site/docs/getting-started.md b/site/docs/getting-started.md
index 23632974f2..f0e8bf1869 100644
--- a/site/docs/getting-started.md
+++ b/site/docs/getting-started.md
@@ -5,17 +5,12 @@ layout: default
 Getting Started with Bazel
 ==========================
 
-Prerequisites
--------------
-
-Be sure you have installed all of the prerequisites for your platform, as
-outlined in the [installation instructions](install.html).
-
 Setup
 -----
 
 To use Bazel, first clone the [Github repo](https://github.com/google/bazel)
-and build Bazel:
+and build Bazel (follow the instructions in the [README](install.html) to install
+prerequisites):
 
 ```bash
 $ git clone https://github.com/google/bazel.git
@@ -24,9 +19,6 @@ $ ./compile.sh
 ```
 
 `./compile.sh` creates the `bazel` executable in `output/bazel`.
-It also pre-populates a `base_workspace/` subdirectory with the tools
-Bazel needs to do builds, which you can copy and use as a starting
-point for new workspaces.
 
 _**Note:** Bazel may support a binary installation at a later time._
 
@@ -45,31 +37,8 @@ One workspace can be shared among multiple projects, if desired.  To get
 started, we'll focus on a simple example with one project.
 
 Suppose that you have an existing project in a directory, say,
-`~/gitroot/my-project/`. Copy `base_workspace/` (produced
-by `compile.sh`) and all of its contents to wherever you'd like your
-build root and then move `my-project/` to be a subdirectory of
-`base_workspace/`:
-
-```bash
-$ cp -R ~/gitroot/bazel/base_workspace ~/gitroot
-$ mv ~/gitroot/my-project ~/gitroot/base_workspace
-```
-
-At this point, you should have the following directory structure:
-
-```
-base_workspace/
-  examples/
-  my-project/
-  tools/
-  third_party/
-  WORKSPACE
-```
-
-You can rename `base_workspace/` to something more descriptive, if you prefer.
-The `tools/` and `third_party/` directories can be symbolically linked into the
-workspace, or they can be copied in whole, but must be named `tools/` and
-`third_party/` respectively.
+`~/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
 ---------------------------------
@@ -78,7 +47,7 @@ To make sure everything is set up correctly in your build root, build one of the
 examples from the `examples/` directory.
 
 ```bash
-$ cd ~/gitroot/base_workspace
+$ cd ~/gitroot/my-project
 $ bazel build examples/java-native/src/main/java/com/example/myproject:hello-world
 Extracting Bazel installation...
 ...........
diff --git a/site/docs/install.md b/site/docs/install.md
index ac93ad5cc5..f954e6cfcb 100644
--- a/site/docs/install.md
+++ b/site/docs/install.md
@@ -134,30 +134,4 @@ $ export PATH="$PATH:$HOME/bazel/output/bazel"
 
 You can also add this command to your `~/.bashrc` file.
 
-You must run the Bazel from within a directory that is properly configured for
-use with the application. We call this directory a _workspace directory_.
-Bazel provides a default workspace directory with sample `BUILD` files and
-source code at `base_workspace` in the Bazel home directory. This directory
-contains files and subdirectories 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.
-
-To run Bazel and build a sample Java application:
-
-```
-$ cp -R $HOME/bazel/base_workspace $HOME/my_workspace
-$ cd $HOME/my_workspace
-$ 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/`.
-
-To 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).
diff --git a/site/docs/windows.md b/site/docs/windows.md
index 8e2d74072d..6c05a9e956 100644
--- a/site/docs/windows.md
+++ b/site/docs/windows.md
@@ -62,5 +62,4 @@ Third, you need to set some Bazel options. It's easiest to put them into your
 
 This should be enough to run Bazel:
 
-    cd base_workspace &&
-    ../output/bazel build //cpp:hello-world
+    ./output/bazel build //examples/cpp:hello-world