site/docs/build-ref.html: add "repository" to the concepts page
Explain that code is organised in repositories; while there, also
explain the boundaries of the main workspace. Mention how repositories
are named inside a label.
Fixes
Improves on
@@ -15,6 +15,7 @@ title: Concepts and Terminology
<li><a href="#packages_targets">Workspace, Packages and Targets</a>
<ul>
<li><a href="#workspace">Workspace</a></li>
+ <li><a href="#repositories">Repositories</a></li>
<li><a href="#packages">Packages</a></li>
<li><a href="#targets">Targets</a></li>
<li><a href="#labels">Labels</a></li>
@@ -54,13 +55,33 @@ title: Concepts and Terminology
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="external.html">external dependencies</a>
- required to build the outputs. See also the <a
- href="be/workspace.html">Workspace Rules</a> section in the Build
- Encyclopedia.
-</p>
+ required to build the outputs.</p>
+
+<p>Directories containing a file called
+ <code>WORKSPACE</code> are considered the root of a workspace.
+ Therefore, Bazel ignores any directory trees in a workspace rooted
+ at a subdirectory containing a <code>WORKSPACE</code> file (as they form
+ another workspace).</p>
+
+<h3 id="repositories">Repositories</h3>
+<p>Code is organized in <em>repositories</em>. The directory containing
+ the <code>WORKSPACE</code> file is the root of the main repository, also
+ called <code>@</code>. Other, (external) repositories
+ are defined in the <code>WORKSPACE</code> file using workspace rules.
+
+<p>The workspace rules bundled with Bazel are documented in the
+ <a href="be/workspace.html">Workspace Rules</a> section in the Build
+ Encyclopedia and the documentation on
+ <a href="repo/index.html">embeded Starlark repository rules</a>.</p>
+
+<p>As external repositories are repositories themselves, they ofen contain
+ a <code>WORKSPACE</code> file as well. However, these additional
+ <code>WORKSPACE</code> files are ignored by Bazel. In particular,
+ repositories depended upon transitively are not added automatically.</p>
+
<h3 id="packages">Packages</h3>
<p>
- The primary unit of code organization in a workspace is
+ The primary unit of code organization in a repository is
the <i>package</i>. A package is a collection of related files and a
specification of the dependencies among them.
</p>
@@ -169,11 +190,16 @@ src/my/app/tests/test.cc
looks like this:
</p>
+
<pre>
-//my/app/main:app_binary
+@myrepo//my/app/main:app_binary
</pre>
<p>
+ In the typical case that a label refers to the same repository it occurs
+ in, the repository name may be left out. So, inside <code>@myrepo</code>
+ this label is usually written as
+</p>
Each label has two parts, a package name (<code>my/app/main</code>)
and a target name (<code>app_binary</code>). Every label uniquely
