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

PiperOrigin-RevId: 160673799

1 files changed, 107 insertions, 0 deletions

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.