Generate the command-line reference from bazel help.

--
Change-Id: I277f81472520b7f490cb178bb14c9618553cc4b2
Reviewed-on: https://bazel-review.googlesource.com/#/c/3880/
MOS_MIGRATED_REVID=125657323

6 files changed, 230 insertions, 2 deletions

diff --git a/site/BUILD b/site/BUILD
index d1107bc6c8..4cf080de3e 100644
--- a/site/BUILD
+++ b/site/BUILD
@@ -1,7 +1,11 @@
 load("@bazel_tools//tools/build_defs/pkg:pkg.bzl", "pkg_tar")
 
 exports_files(
-    ["docs/bazel-user-manual.html"],
+    [
+        "docs/bazel-user-manual.html",
+        "command-line-reference-prefix.html",
+        "command-line-reference-suffix.html",
+    ],
 )
 
 filegroup(
@@ -18,6 +22,8 @@ filegroup(
             "BUILD",
             "jekyll-tree.sh",
             "*.swp",
+            "command-line-reference-prefix.html",
+            "command-line-reference-suffix.html",
         ],
     ),
 )
@@ -91,13 +97,15 @@ genrule(
         ":skylark-rule-docs",
         "//src/main/java/com/google/devtools/build/lib:gen_buildencyclopedia",
         "//src/main/java/com/google/devtools/build/lib:gen_skylarklibrary",
+        "//src/main/java/com/google/devtools/build/lib:gen_command-line-reference",
     ],
     outs = ["jekyll-tree.tar"],
     cmd = ("$(location jekyll-tree.sh) $@ " +
            "$(location :jekyll-base) " +
            "$(location :skylark-rule-docs) " +
            "$(location //src/main/java/com/google/devtools/build/lib:gen_buildencyclopedia) " +
-           "$(location //src/main/java/com/google/devtools/build/lib:gen_skylarklibrary)"),
+           "$(location //src/main/java/com/google/devtools/build/lib:gen_skylarklibrary) " +
+           "$(location //src/main/java/com/google/devtools/build/lib:gen_command-line-reference)"),
     tools = [
         "jekyll-tree.sh",
     ],
diff --git a/site/command-line-reference-prefix.html b/site/command-line-reference-prefix.html
new file mode 100644
index 0000000000..ff0e03537a
--- /dev/null
+++ b/site/command-line-reference-prefix.html
@@ -0,0 +1,187 @@
+---
+layout: documentation
+title: Command-Line Reference
+---
+
+<h1>Command-Line Reference</h1>
+
+<pre>
+blaze [&lt;startup options&gt;] &lt;command&gt; [&lt;args&gt;]
+</pre>
+
+or
+
+<pre>
+blaze [&lt;startup options&gt;] &lt;command&gt; [&lt;args&gt;] -- [&lt;target patterns&gt;]
+</pre>
+
+<h2>Option Syntax</h2>
+
+<p>
+Options can be passed to Blaze in different ways. Options that require a value
+can be passed with either an equals sign or a space:
+<pre>
+--&lt;option&gt;=&lt;value&gt;
+--&lt;option&gt; &lt;value&gt;
+</pre>
+Some options have a single character short form; in that case, the short form
+has to be passed with a single dash and a space.
+<pre>
+-&lt;short_form&gt; &lt;value&gt;
+</pre>
+</p>
+
+<p>
+Boolean options can be enabled as follows:
+<pre>
+--&lt;option&gt;
+--&lt;option&gt;=[true|yes|1]
+</pre>
+
+and disabled as follows:
+<pre>
+--no&lt;option&gt;
+--no_&lt;option&gt;
+--&lt;option&gt;=[false|no|0]
+</pre>
+</p>
+
+<p>
+Tristate options are usually set to automatic by default, and can be
+force-enabled as follows:
+<pre>
+--&lt;option&gt;=[true|yes|1]
+</pre>
+or force-disabled as follows:
+<pre>
+--no&lt;option&gt;
+--no_&lt;option&gt;
+--&lt;option&gt;=[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,
+Blaze 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 Blaze 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, Blaze 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 Blaze 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 Blaze from
+interpreting it as an option, e.g.:
+<pre>
+blaze build -- foo/... -foo/contrib/...
+</pre>
+Note that Blaze 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/command-line-reference-suffix.html b/site/command-line-reference-suffix.html
new file mode 100644
index 0000000000..c8fdda10ff
--- /dev/null
+++ b/site/command-line-reference-suffix.html
@@ -0,0 +1,4 @@
+
+<br/><br/><br/><br/>
+
+
diff --git a/site/jekyll-tree.sh b/site/jekyll-tree.sh
index e274f496e7..7b31a21c0b 100755
--- a/site/jekyll-tree.sh
+++ b/site/jekyll-tree.sh
@@ -24,6 +24,8 @@ shift
 readonly BE_ZIP=${PWD}/$1
 shift
 readonly SL_ZIP=${PWD}/$1
+shift
+readonly CLR_HTML=${PWD}/$1
 
 # Create temporary directory that is removed when this script exits.
 readonly TMP=$(mktemp -d "${TMPDIR:-/tmp}/tmp.XXXXXXXX")
@@ -104,6 +106,7 @@ function main {
   unpack_build_encyclopedia
   unpack_skylark_library
   unpack_skylark_rule_docs
+  cp ${CLR_HTML} ${OUT_DIR}/docs
   process_docs
   package_output
 }
diff --git a/src/BUILD b/src/BUILD
index 443eba13b5..b1434fef2e 100644
--- a/src/BUILD
+++ b/src/BUILD
@@ -211,6 +211,7 @@ genrule(
     visibility = [
         "//scripts:__pkg__",  # For bash completion generation
         "//scripts/packages:__pkg__",  # For installer generation
+        "//src/java:__subpackages__",  # For command line reference generation
         "//src/test:__subpackages__",  # For integration tests
     ],
 ) for suffix in [
diff --git a/src/main/java/com/google/devtools/build/lib/BUILD b/src/main/java/com/google/devtools/build/lib/BUILD
index dfca261826..b92df36247 100644
--- a/src/main/java/com/google/devtools/build/lib/BUILD
+++ b/src/main/java/com/google/devtools/build/lib/BUILD
@@ -968,6 +968,31 @@ genrule(
     ],
 )
 
+genrule(
+    name = "gen_command-line-reference",
+    srcs = [
+        "//site:command-line-reference-prefix.html",
+        "//site:command-line-reference-suffix.html",
+    ],
+    outs = ["command-line-reference.html"],
+    cmd = (
+        "cat $(location //site:command-line-reference-prefix.html) > $@ && " +
+        "TMP=`mktemp -d /tmp/tmp.XXXXXXXXXX` && " +
+        "mkdir $${TMP}/_embedded_binaries/ && " +
+        "$(location :bazel/BazelServer) " +
+        "--jvm_flag=-Dio.bazel.UnixFileSystem=0 --batch " +
+        "--install_base=$${TMP} --output_base=$${TMP}/output/ " +
+        "help everything-as-html >> $@ 2>/dev/null && " +
+        "cat $(location //site:command-line-reference-suffix.html) >> $@"
+    ),
+    tools = [
+        ":bazel/BazelServer",
+    ],
+    visibility = [
+        "//site:__pkg__",
+    ],
+)
+
 # The skylark repository classes are passed as parameter of the Skylark documentation generator.
 SKYLARK_REPOSITORY_CLASSES = [
     "com.google.devtools.build.lib.bazel.repository.skylark.SkylarkExecutionResult",