Remove duplicate documentation about Target Pattern syntax
The documentation appeared in both:
https://docs.bazel.build/versions/master/guide.html#target-patterns
and:
https://docs.bazel.build/versions/master/command-line-reference.html#target-pattern-syntax
I've taken mostly the section from command-line-reference, and moved it to the User Guide.
RELNOTES: None.
PiperOrigin-RevId: 217785381
diff --git a/site/command-line-reference-prefix.html b/site/command-line-reference-prefix.html
index 38e1460..59f2b79 100644
--- a/site/command-line-reference-prefix.html
+++ b/site/command-line-reference-prefix.html
@@ -14,6 +14,9 @@
bazel [<startup options>] <command> [<args>] -- [<target patterns>]
</pre>
+See the <a href="guide.html#target-patterns">User's Guide</a> for the
+target patterns syntax.
+
<h2>Option Syntax</h2>
<p>
@@ -56,126 +59,3 @@
--<option>=[false|no|0]
</pre>
</p>
-
-<h2>Target Pattern Syntax</h2>
-
-<p>
-A target pattern refers to a single or more targets, which are source files,
-output files, or rules specified in BUILD files. In addition to plain labels,
-Bazel also supports working-directory-relative labels, recursive patterns, and
-target subtraction.
-</p>
-
-<p>
-All target patterns starting with '//' are resolved relative to the current
-workspace.
-<table>
-<tr>
- <td><code>//foo/bar:wiz</code></td>
- <td>Just the single target '//foo/bar:wiz'.</td>
-</tr>
-<tr>
- <td><code>//foo/bar</code></td>
- <td>Equivalent to '//foo/bar:bar'.</td>
-</tr>
-<tr>
- <td><code>//foo/bar:all</code></td>
- <td>All rules in the package 'foo/bar'.</td>
-</tr>
-<tr>
- <td><code>//foo/...</code></td>
- <td>All rules in all packages beneath the directory 'foo'.</td>
-</tr>
-<tr>
- <td><code>//foo/...:all</code></td>
- <td>All rules in all packages beneath the directory 'foo'.</td>
-</tr>
-<tr>
- <td><code>//foo/...:*</code></td>
- <td>All targets (rules and files) in all packages beneath the directory 'foo'.</td>
-</tr>
-<tr>
- <td><code>//foo/...:all-targets</code></td>
- <td>All targets (rules and files) in all packages beneath the directory 'foo'.</td>
-</tr>
-</table>
-</p>
-
-<p>
-Targets with <code>tags=["manual"]</code> are not included in wildcard
-target patterns (<code>...</code>, <code>:*</code>, <code>:all</code>, etc).
-Specify such test targets with explicit labels on the command line if
-you want Bazel to build/test them.
-</p>
-
-<p>
-Target patterns which do not begin with '//' are resolved relative to the
-current <em>working directory</em>. These examples assume a working directory of
-'foo':
-<table>
-<tr>
- <td><code>:foo</code></td>
- <td>Equivalent to '//foo:foo'.</td>
-</tr>
-<tr>
- <td><code>bar:wiz</code></td>
- <td>Equivalent to '//foo/bar:wiz'.</td>
-</tr>
-<tr>
- <td><code>bar/wiz</code></td>
- <td>Equivalent to:
- '//foo/bar/wiz:wiz' if foo/bar/wiz is a package,
- '//foo/bar:wiz' if foo/bar is a package,
- '//foo:bar/wiz' otherwise.
- </td>
-</tr>
-<tr>
- <td><code>bar:all</code></td>
- <td>Equivalent to '//foo/bar:all'.</td>
-</tr>
-<tr>
- <td><code>:all</code></td>
- <td>Equivalent to '//foo:all'.</td>
-</tr>
-<tr>
- <td><code>...:all</code></td>
- <td>Equivalent to '//foo/...:all'.</td>
-</tr>
-<tr>
- <td><code>...</code></td>
- <td>Equivalent to '//foo/...:all'.</td>
-</tr>
-<tr>
- <td><code>bar/...:all</code></td>
- <td>Equivalent to '//foo/bar/...:all'.</td>
-</tr>
-</table>
-</p>
-
-<p>
-By default, directory symlinks are followed for recursive target patterns,
-except those that point to under the output base, such as the convenience
-symlinks that are created in the root directory of the workspace.
-</p>
-
-<p>
-In addition, Bazel does not follow symlinks when evaluating recursive target
-patterns in any directory that contains a file named as follows:
-<pre>
-DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN
-</pre>
-</p>
-
-<p>
-Target patterns may be preceded by a single dash ('<code>-</code>'), in which
-case Bazel subtracts them from the set of targets accumulated by preceding
-patterns. Note that this means <em>order matters</em>. In order to pass negative
-target patterns, you need to use '--' as an argument to prevent Bazel from
-interpreting it as an option, e.g.:
-<pre>
-bazel build -- foo/... -foo/contrib/...
-</pre>
-Note that Bazel may still build targets matched by a negative target pattern due
-to dependencies, and may also load the corresponding BUILD files, even if the
-targets are never built.
-</p>
diff --git a/site/docs/guide.html b/site/docs/guide.html
index 8132d5f..e10cea4 100644
--- a/site/docs/guide.html
+++ b/site/docs/guide.html
@@ -8,7 +8,7 @@
<p>
To run Bazel, go to
- your base <a href="build-ref.html#workspaces">workspace</a> directory
+ your base <a href="build-ref.html#workspace">workspace</a> directory
or any of its subdirectories and type <code>bazel</code>.
</p>
@@ -138,95 +138,11 @@
<h3 id='target-patterns'>Specifying targets to build</h3>
<p>
Bazel allows a number of ways to specify the targets to be built.
- Collectively, these are known as <i>target patterns</i>.
- The on-line help displays a summary of supported patterns:
+ Collectively, these are known as <i>target patterns</i>. This syntax is
+ used in commands like <code>build</code>, <code>test</code>,
+ or <code>query</code>.
</p>
-<pre>
-% bazel help target-syntax
-Target pattern syntax
-=====================
-
-The BUILD file label syntax is used to specify a single target. Target
-patterns generalize this syntax to sets of targets, and also support
-working-directory-relative forms, recursion, subtraction and filtering.
-Examples:
-
-Specifying a single target:
-
- //foo/bar:wiz The single target '//foo/bar:wiz'.
- foo/bar/wiz Equivalent to:
- '//foo/bar/wiz:wiz' if foo/bar/wiz is a package,
- '//foo/bar:wiz' if foo/bar is a package,
- '//foo:bar/wiz' otherwise.
- //foo/bar Equivalent to '//foo/bar:bar'.
-
-Specifying all rules in a package:
-
- //foo/bar:all Matches all rules in package 'foo/bar'.
-
-Specifying all rules recursively beneath a package:
-
- //foo/...:all Matches all rules in all packages beneath directory 'foo'.
- //foo/... (ditto)
-
- By default, directory symlinks are followed when performing this recursive traversal, except
- those that point to under the output base (for example, the convenience symlinks that are created
- in the root directory of the workspace) But we understand that your workspace may intentionally
- contain directories with unusual symlink structures that you don't want consumed. As such, if a
- directory has a file named
- 'DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN' then symlinks
- in that directory won't be followed when evaluating recursive target patterns.
-
-Working-directory relative forms: (assume cwd = 'workspace/foo')
-
- Target patterns which do not begin with '//' are taken relative to
- the working directory. Patterns which begin with '//' are always
- absolute.
-
- ...:all Equivalent to '//foo/...:all'.
- ... (ditto)
-
- bar/...:all Equivalent to '//foo/bar/...:all'.
- bar/... (ditto)
-
- bar:wiz Equivalent to '//foo/bar:wiz'.
- :foo Equivalent to '//foo:foo'.
-
- bar Equivalent to '//foo/bar:bar'.
- foo/bar Equivalent to '//foo/foo/bar:bar'.
-
- bar:all Equivalent to '//foo/bar:all'.
- :all Equivalent to '//foo:all'.
-
-Summary of target wildcards:
-
- :all, Match all rules in the specified packages.
- :*, :all-targets Match all targets (rules and files) in the specified
- packages, including ones not built by default, such
- as _deploy.jar files.
-
-Subtractive patterns:
-
- Target patterns may be preceded by '-', meaning they should be
- subtracted from the set of targets accumulated by preceding
- patterns. (Note that this means order matters.) For example:
-
- % bazel build -- foo/... -foo/contrib/...
-
- builds everything in 'foo', except 'contrib'. In case a target not
- under 'contrib' depends on something under 'contrib' though, in order to
- build the former bazel has to build the latter too. As usual, the '--' is
- required to prevent '-f' from being interpreted as an option.
-
- When running the test command, test suite expansion is applied to each target
- pattern in sequence as the set of targets is evaluated. This means that
- individual tests from a test suite can be excluded by a later target pattern.
- It also means that an exclusion target pattern which matches a test suite will
- exclude all tests which that test suite references. (Targets that would be
- matched by the list of target patterns without any test suite expansion are
- also built unless --build_tests_only is set.)
-</pre>
<p>
Whereas <a href="build-ref.html#labels">labels</a> are used
to specify individual targets, e.g. for declaring dependencies in
@@ -236,6 +152,100 @@
any valid label is also a valid target pattern, identifying a set of
exactly one target.
</p>
+
+<p>
+All target patterns starting with '//' are resolved relative to the current
+workspace.
+<table>
+<tr>
+ <td><code>//foo/bar:wiz</code></td>
+ <td>Just the single target '//foo/bar:wiz'.</td>
+</tr>
+<tr>
+ <td><code>//foo/bar</code></td>
+ <td>Equivalent to '//foo/bar:bar'.</td>
+</tr>
+<tr>
+ <td><code>//foo/bar:all</code></td>
+ <td>All rules in the package 'foo/bar'.</td>
+</tr>
+<tr>
+ <td><code>//foo/...</code></td>
+ <td>All rules in all packages beneath the directory 'foo'.</td>
+</tr>
+<tr>
+ <td><code>//foo/...:all</code></td>
+ <td>All rules in all packages beneath the directory 'foo'.</td>
+</tr>
+<tr>
+ <td><code>//foo/...:*</code></td>
+ <td>All targets (rules and files) in all packages beneath the directory 'foo'.</td>
+</tr>
+<tr>
+ <td><code>//foo/...:all-targets</code></td>
+ <td>All targets (rules and files) in all packages beneath the directory 'foo'.</td>
+</tr>
+</table>
+</p>
+
+<p>
+Target patterns which do not begin with '//' are resolved relative to the
+current <em>working directory</em>. These examples assume a working directory of
+'foo':
+<table>
+<tr>
+ <td><code>:foo</code></td>
+ <td>Equivalent to '//foo:foo'.</td>
+</tr>
+<tr>
+ <td><code>bar:wiz</code></td>
+ <td>Equivalent to '//foo/bar:wiz'.</td>
+</tr>
+<tr>
+ <td><code>bar/wiz</code></td>
+ <td>Equivalent to:
+ '//foo/bar/wiz:wiz' if foo/bar/wiz is a package,
+ '//foo/bar:wiz' if foo/bar is a package,
+ '//foo:bar/wiz' otherwise.
+ </td>
+</tr>
+<tr>
+ <td><code>bar:all</code></td>
+ <td>Equivalent to '//foo/bar:all'.</td>
+</tr>
+<tr>
+ <td><code>:all</code></td>
+ <td>Equivalent to '//foo:all'.</td>
+</tr>
+<tr>
+ <td><code>...:all</code></td>
+ <td>Equivalent to '//foo/...:all'.</td>
+</tr>
+<tr>
+ <td><code>...</code></td>
+ <td>Equivalent to '//foo/...:all'.</td>
+</tr>
+<tr>
+ <td><code>bar/...:all</code></td>
+ <td>Equivalent to '//foo/bar/...:all'.</td>
+</tr>
+</table>
+</p>
+
+<p>
+By default, directory symlinks are followed for recursive target patterns,
+except those that point to under the output base, such as the convenience
+symlinks that are created in the root directory of the workspace.
+</p>
+
+<p>
+In addition, Bazel does not follow symlinks when evaluating recursive target
+patterns in any directory that contains a file named as follows:
+<pre>
+DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN
+</pre>
+</p>
+
<p>
<code>foo/...</code> is a wildcard over <em>packages</em>,
indicating all packages recursively beneath
