Normalize usage of "workspace", "workspace directory" and "build root" in documentation. Replaces instances of "build root" with "workspace directory" as appropriate. Makes the following changes: - /docs/build-ref.html: Adds definition of workspace - /docs/external.md: Replaces "build root" terminology with "workspace" - /docs/getting-started.md: Adds link to workspace definition - /docs/bazel-user-manual.html: Adds link to workspace definition -- MOS_MIGRATED_REVID=101885966
diff --git a/site/docs/bazel-user-manual.html b/site/docs/bazel-user-manual.html index 2822299..b0359ab 100644 --- a/site/docs/bazel-user-manual.html +++ b/site/docs/bazel-user-manual.html
@@ -143,7 +143,7 @@ <p> To run Bazel, go to - your base workspace directory + your base <a href="/docs/build-ref.html#workspaces">workspace</a> directory or any of its subdirectories and type <code>bazel</code>. </p>
diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html index 1d84912..36c687c 100644 --- a/site/docs/build-ref.html +++ b/site/docs/build-ref.html
@@ -139,7 +139,8 @@ <ul> <li><a href="#intro">Introduction</a></li> - <li><a href="#packages_targets">Packages and Targets</a> + + <li><a href="#packages_targets">Workspace, Packages and Targets</a> <ul> <li><a href="#packages">Packages</a></li> <li><a href="#targets">Targets</a></li> @@ -168,26 +169,32 @@ <h2 id="intro">Introduction</h2> -<p>Bazel can build and test software from source - code stored in any source tree that is organized as described - in this document. This source tree descends from a single top-level - directory and contains a nested hierarchy of packages, each of which contain - source files and metadata that specifies what software targets, for - example, compiled executables or libraries, can be built from the source. +<p>Bazel builds software from source code organized in a directory called + a workspace. Source files in the workspace are organized in a nested + hierarchy of packages, where each package is a directory that contains a set + of related source files and a BUILD file. The BUILD file specifies what + software outputs can be built from the source. </p> -<h2 id="packages_targets">Packages and Targets</h2> +<h2 id="packages_targets">Workspace, Packages and Targets</h2> +<h3 id="workspaces">Workspace</h3> +<p>A <em>workspace</em> is a directory on your filesystem that contains the + source files for the software you want to build, as well as symbolic links + to directories that contain the build outputs. Each workspace directory has + a text file named <code>WORKSPACE</code> which may be empty, or may contain + references to <a href="/docs/external.html">external dependencies</a> + required to build the outputs. +</p> <h3 id="packages">Packages</h3> - <p> - The primary unit of code organization in the source tree is + The primary unit of code organization a workspace is the <i>package</i>. A package is collection of related files and a specification of the dependencies among them. </p> <p> A package is defined as a directory containing a file named <code>BUILD</code>, residing beneath the top-level directory in the - source tree. A package includes all files in its directory, plus all + workspace. A package includes all files in its directory, plus all subdirectories beneath it, except those which themselves contain a BUILD file. </p>
diff --git a/site/docs/external.md b/site/docs/external.md index e11f49f..34ffe1b 100644 --- a/site/docs/external.md +++ b/site/docs/external.md
@@ -5,15 +5,16 @@ # Working with external dependencies Bazel is designed to have absolutely everything needed for a build, from source -code to libraries to compilers, under one directory (the build root). This is -impractical for some version control systems and goes against how many existing -projects are structured. Thus, Bazel has a system for pulling in dependencies -from outside of the build root. +code to libraries to compilers, under one directory (the workspace directory). +This is impractical for some version control systems and goes against how many +existing projects are structured. Thus, Bazel has a system for pulling in +dependencies from outside of the workspace. -External dependencies can be specified in a `WORKSPACE` file in the build root. -This `WORKSPACE` file uses the same Python-like syntax of BUILD files, but -allows a different set of rules. See the full list of rules that are allowed in -the [Workspace](/docs/build-encyclopedia.html) list of rules in the Build +External dependencies can be specified in a `WORKSPACE` file in the +[workspace directory](/docs/build-ref.html#workspaces). This `WORKSPACE` file +uses the same Python-like syntax of BUILD files, but allows a different set of +rules. See the full list of rules that are allowed in the +[Workspace](/docs/build-encyclopedia.html#workspace) list of rules in the Build Encyclopedia. ## Fetching dependencies @@ -25,7 +26,7 @@ <a name="transitive-dependencies"></a> ## Transitive dependencies -Bazel only reads dependencies listed in your build root's `WORKSPACE` file. This +Bazel only reads dependencies listed in your `WORKSPACE` file. This means that if your project (`A`) depends on another project (`B`) which list a dependency on project `C` in its `WORKSPACE` file, you'll have to add both `B` and `C` to your project's `WORKSPACE` file. This can balloon the `WORKSPACE`
diff --git a/site/docs/getting-started.md b/site/docs/getting-started.md index 9615dc1..479a533 100644 --- a/site/docs/getting-started.md +++ b/site/docs/getting-started.md
@@ -23,12 +23,13 @@ ## Using a workspace -A *workspace* 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 an -empty file called `WORKSPACE` in the top-level directory. This file marks the -directory as the workspace root. +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 +[external dependencies](/docs/external.html) required to build the outputs. One workspace can be shared among multiple projects if desired. To get started, we'll focus on a simple example with one project. @@ -39,8 +40,8 @@ ## Sanity Check: Building an Example -To make sure everything is set up correctly in your build root, build one of the -examples from the `examples/` directory. +To make sure that you have installed Bazel correctly, build one of the examples +from the `examples/` directory. {% highlight bash %} $ cd ~/gitroot/my-project @@ -104,7 +105,7 @@ commands to make a fake project for this example: {% highlight bash %} -$ # If you're not already there, move to your build root directory. +$ # 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