Describe the tool `generate_workspace` in a separate topic. Update instructions for generating a WORKSPACE file.

PiperOrigin-RevId: 160673799

3 files changed, 110 insertions, 66 deletions

diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index 77e46b431d..e31fa3d7b8 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -80,6 +80,7 @@ nav: docs
               <li><a href="/versions/{{ site.version }}/query-how-to.html">Query How-To</a></li>
               <li><a href="/versions/{{ site.version }}/mobile-install.html">mobile-install (Android)</a></li>
               <li><a href="/versions/{{ site.version }}/external.html">External Dependencies</a></li>
+              <li><a href="/versions/{{ site.version }}/external.html">Generate External Dependencies from Maven</a></li>
               <li><a href="/versions/{{ site.version }}/command-line-reference.html">Command-line Reference</a></li>
               <li><a href="/versions/{{ site.version }}/output_directories.html">Output Directories</a></li>
               <li><a href="/versions/{{ site.version }}/windows.html">Bazel on Windows</a></li>
diff --git a/site/docs/external.md b/site/docs/external.md
index b997191a87..93e92d7eb1 100644
--- a/site/docs/external.md
+++ b/site/docs/external.md
@@ -123,72 +123,8 @@ and `C` to your project's `WORKSPACE` file. This requirement can balloon the
 `WORKSPACE` file size, but hopefully limits the chances of having one library
 include `C` at version 1.0 and another include `C` at 2.0.
 
-## Generate a `WORKSPACE` file
-
-Bazel provides a tool to help generate these expansive `WORKSPACE` files, called
-`generate_workspace`. This tool is not included with the binary installer, so
-you'll need to clone the [GitHub repo](https://github.com/bazelbuild/bazel) to
-use it. We recommend using the tag corresponding to your current version of
-bazel, which you can check by running `bazel version`.
-
-`cd` to the GitHub clone, `git checkout` the appropriate tag, and run the
-following to build the tool and see usage:
-
-```
-bazel run //src/tools/generate_workspace
-```
-
-Note that you need run this command from your Bazel source folder even if you
-build your binary from source.
-
-You can specify directories containing Bazel projects (i.e., directories
-containing a `WORKSPACE` file), Maven projects (i.e., directories containing a
-`pom.xml` file), or Maven artifact coordinates directly. For example:
-
-```bash
-$ bazel run //src/tools/generate_workspace -- \
->    --maven_project=/path/to/my/project \
->    --bazel_project=/path/to/skunkworks \
->    --bazel_project=/path/to/teleporter/project \
->    --artifact=groupId:artifactId:version \
->    --artifact=groupId:artifactId:version
-Wrote:
-/tmp/1437415510621-0/2015-07-20-14-05-10.WORKSPACE
-/tmp/1437415510621-0/2015-07-20-14-05-10.BUILD
-```
-
-The `WORKSPACE` file will contain the transitive dependencies of the given
-projects and artifacts.
-
-If you specify multiple Bazel projects, Maven projects, or artifacts, they will
-all be combined into one `WORKSPACE` file (e.g., if the Bazel project depends on
-junit and the Maven project also depends on junit, junit will only appear once
-as a dependency in the output).
-
-You may wish to curate the generated `WORKSPACE` file to ensure it is using the
-correct version of each dependency. If several different versions of an artifact
-are requested (by different libraries that depend on it), then
-`generate_workspace` chooses a version and annotates the `maven_jar` with the
-other versions requested, for example:
-
-```python
-# org.springframework:spring:2.5.6
-# javax.mail:mail:1.4
-# httpunit:httpunit:1.6 wanted version 1.0.2
-# org.springframework:spring-support:2.0.2 wanted version 1.0.2
-# org.slf4j:nlog4j:1.2.24 wanted version 1.0.2
-maven_jar(
-    name = "javax_activation_activation",
-    artifact = "javax.activation:activation:1.1",
-)
-```
-
-The example above indicates that `org.springframework:spring:2.5.6`,
-`javax.mail:mail:1.4`, `httpunit:httpunit:1.6`,
-`org.springframework:spring-support:2.0.2`, and `org.slf4j:nlog4j:1.2.24`
-all depend on javax.activation. However, two of these libraries wanted
-version 1.1 and three of them wanted 1.0.2. The `WORKSPACE` file is using
-version 1.1, but that might not be the right version to use.
+Large `WORKSPACE` files can be generated using the tool `generate_workspace`.
+For details, see [Generate a WORKSPACE file](/docs/generate-workspace.html).
 
 ## Caching of external dependencies
 
diff --git a/site/docs/generate-workspace.md b/site/docs/generate-workspace.md
new file mode 100644
index 0000000000..5f8a1be9ae
--- /dev/null
+++ b/site/docs/generate-workspace.md
@@ -0,0 +1,107 @@
+---
+layout: documentation
+title: Generate external dependencies for a Java project
+---
+
+# Generate external dependencies from Maven projects
+
+The tool `generate_workspace` helps automate the process of writing
+the `WORKSPACE` file for a Java project. This tool is
+helpful when the list of external dependencies is long, such as when working
+with [external transitive dependnecies](/docs/external.html#external-packages).
+
+The `generate_workspace` tool will generate:
+
+*   a `generate_workspace.bzl` file which includes:
+    *   the `generated_maven_jars` macro that will contain the transitive
+        dependencies, and
+    *   the `generated_java_libraries` macro that will contain a library
+        for each maven_jar.
+
+## Install `generate_workspace`
+
+Bazel's binary installer does not include `generate_workspace`. To be able to
+use this tool:
+
+1.  Clone Bazel's migration tooling repo:
+
+    ```
+    git clone https://github.com/bazelbuild/migration-tooling.git
+    ```
+
+2.  Run the following to build the `generate_workspace` tool and see usage:
+
+    ```
+    bazel run //generate_workspace
+    ```
+
+## Generate a list of external dependencies
+
+1.  Run the `generate_workspace` tool.
+
+    When you run the tool, you can specify Maven projects (that is,
+    directories containing a `pom.xml` file), or Maven artifact coordinates
+    directly. For example:
+
+    ```bash
+    $ bazel run //generate_workspace -- \
+    >    --maven_project=/path/to/my/project \
+    >    --artifact=groupId:artifactId:version \
+    >    --artifact=groupId:artifactId:version
+    Wrote:
+    /tmp/1437415510621-0/2015-07-20-14-05-10.WORKSPACE
+    /tmp/1437415510621-0/2015-07-20-14-05-10.BUILD
+    ```
+
+2.  The tool creates one outputs, a `generate_workspace.bzl` file that contains
+    two macros:
+
+    1.  The `generated_maven_jars` macro that will contain the transitive
+        dependencies of the given projects and artifacts.
+
+        If you specify multiple Maven projects or artifacts,
+        they will all be combined into one `WORKSPACE` file. For example, if
+        an artifact depends on junit and the Maven project also depends
+        on junit, then junit will only appear once as a dependency in the
+        output.
+
+    2.  The `generated_java_libraries` macro will contain a library
+        for each maven_jar.
+
+3.  Copy the `generate_workspace.bzl` file to your workspace, and add the
+    following to your WORKSPACE file:
+
+    ```
+    load("//:generate_workspace.bzl", "generated_maven_jars")
+    generated_maven_jars()
+    ```
+
+    You can now access any of the jars in `generate_workspace.bzl`.
+
+4.  Ensure `generate_workspace.bzl` lists the correct version of each
+    dependency.
+
+    If several different versions of an artifact are requested (by
+    different libraries that depend on it), then `generate_workspace` chooses
+    a version and annotates the `maven_jar` with the other versions requested.
+
+    Here's an example of the contents of `generate_workspace.bzl`:
+
+    ```python
+    # org.springframework:spring:2.5.6
+    # javax.mail:mail:1.4
+    # httpunit:httpunit:1.6 wanted version 1.0.2
+    # org.springframework:spring-support:2.0.2 wanted version 1.0.2
+    # org.slf4j:nlog4j:1.2.24 wanted version 1.0.2
+    native.maven_jar(
+        name = "javax_activation_activation",
+        artifact = "javax.activation:activation:1.1",
+    )
+    ```
+
+    The example above indicates that `org.springframework:spring:2.5.6`,
+    `javax.mail:mail:1.4`, `httpunit:httpunit:1.6`,
+    `org.springframework:spring-support:2.0.2`, and `org.slf4j:nlog4j:1.2.24`
+    all depend on javax.activation. However, two of these libraries wanted
+    version 1.1 and three of them wanted 1.0.2. The `WORKSPACE` file is using
+    version 1.1, but that might not be the right version to use.