Update the Bazel docs for java_binary and java_test to give more information on how the "launcher" attribute affects builds.

--
PiperOrigin-RevId: 142619261
MOS_MIGRATED_REVID=142619261

3 files changed, 54 insertions, 26 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaBinaryRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaBinaryRule.java
index d414fa1494..2f758816f3 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaBinaryRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaBinaryRule.java
@@ -64,6 +64,13 @@ public final class BazelJavaBinaryRule implements RuleDefinition {
               contains the native libraries needed for dependencies. These are automatically loaded
               into the JVM at runtime.
             </p>
+            <p>If your target specifies a <a href="#java_binary.launcher">launcher</a>
+              attribute, then instead of being a normal JAR file, the _deploy.jar will be a
+              native binary. This will contain the launcher plus any native (C++) dependencies of
+              your rule, all linked into a static binary. The actual jar file's bytes will be
+              appended to that native binary, creating a single binary blob containing both the
+              executable and the Java code. You can execute the resulting jar file directly
+              like you would execute any native binary.</p>
           </li>
           <li><code><var>name</var>_deploy-src.jar</code>: An archive containing the sources
             collected from the transitive closure of the target. These will match the classes in the
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaRuleClasses.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaRuleClasses.java
index ed6db9521d..d17e3dffd4 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaRuleClasses.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaRuleClasses.java
@@ -307,15 +307,18 @@ public class BazelJavaRuleClasses {
           Subject to <a href="#location">$(location)</a> and
           <a href="make-variables.html">"Make variable"</a> substitution, and
           <a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>.
-          <p>
-            The wrapper script for a Java binary includes a <code>CLASSPATH</code> definition (to
-            find all the dependent jars) and invokes the right Java interpreter. The command line
-            generated by the wrapper script includes the name of the main class followed by a
-            <code>"$@"</code> so you can pass along other arguments after the classname.  However,
-            arguments intended for parsing by the JVM must be specified <i>before</i> the classname
-            on the command line. The contents of <code>jvm_flags</code> are added to the wrapper
-            script before the classname is listed.
-          </p>
+
+          <p>The wrapper script for a Java binary includes a CLASSPATH definition
+          (to find all the dependent jars) and invokes the right Java interpreter.
+          The command line generated by the wrapper script includes the name of
+          the main class followed by a <code>"$@"</code> so you can pass along other
+          arguments after the classname.  However, arguments intended for parsing
+          by the JVM must be specified <i>before</i> the classname on the command
+          line.  The contents of <code>jvm_flags</code> are added to the wrapper
+          script before the classname is listed.</p>
+
+          <p>Note that this attribute has <em>no effect</em> on <code>*_deploy.jar</code>
+          outputs.</p>
           <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
           .add(attr("jvm_flags", STRING_LIST))
           /* <!-- #BLAZE_RULE($base_java_binary).ATTRIBUTE(use_testrunner) -->
@@ -394,26 +397,42 @@ public class BazelJavaRuleClasses {
           // TODO(bazel-team): describe how to access this data at runtime
           .add(attr("stamp", TRISTATE).value(TriState.AUTO))
           /* <!-- #BLAZE_RULE($base_java_binary).ATTRIBUTE(launcher) -->
-          If specified, the target will be used to launch the Java Virtual Machine in
-          the wrapper shell script. The target must be a <code>cc_binary</code>.
-          Any <code>cc_binary</code> that implements the
+          Specify a binary that will be used to run your Java program instead of the
+          normal <code>bin/java</code> program included with the JDK.
+          The target must be a <code>cc_binary</code>. Any <code>cc_binary</code> that
+          implements the
           <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html">
-          Java Invocation API</a> can be a launcher target.
+          Java Invocation API</a> can be specified as a value for this attribute.
+
+          <p>The special value <code>//tools/jdk:no_launcher</code>
+          indicates that you want to use the normal JDK launcher (bin/java or java.exe)
+          as the value for this attribute. This is the default.</p>
 
           <p>The related <a href="../blaze-user-manual.html#flag--java_launcher"><code>
           --java_launcher</code></a> Bazel flag affects only those
           <code>java_binary</code> and <code>java_test</code> targets that have
-          <i>not</i> specified a <code>launcher</code> attribute. For those targets
-          that must always be run with the JDK's "java" launcher, set their
-          <code>launcher</code> attribute to the special opt-out label
-          <code>//third_party/java/jdk:jdk_launcher</code>.</p>
-
-          <p>If you build a deploy jar and specify a launcher target through either
-          this <code>launcher</code> attribute or <code>--java_launcher</code> Bazel
-          flag, then the deploy jar will be a single file that is both (a) a .jar
-          file that contains the appropriate classes, and (b) the executable
-          specified by the launcher target. (This does not apply to the opt-out
-          label.)</p>
+          <i>not</i> specified a <code>launcher</code> attribute.</p>
+
+          <p>Note that your native (C++, SWIG, JNI) dependencies will be built differently
+          depending on whether you are using the JDK launcher or another launcher:</p>
+
+          <ul>
+            <li>If you are using the normal JDK launcher (the default), native dependencies are
+            built as a shared library named <code>{name}_nativedeps.so</code>, where
+            <code>{name}</code> is the <code>name</code> attribute of this java_binary rule.
+            Unused code is <em>not</em> removed by the linker in this configuration.</li>
+
+            <li>If you are using any other launcher, native (C++) dependencies are statically
+            linked into a binary named <code>{name}_nativedeps</code>, where <code>{name}</code>
+            is the <code>name</code> attribute of this java_binary rule. In this case,
+            the linker will remove any code it thinks is unused from the resulting binary,
+            which means any C++ code accessed only via JNI may not be linked in unless
+            that <code>cc_library</code> target specifies <code>alwayslink = 1</code>.</li>
+          </ul>
+
+          <p>When using any launcher other than the default JDK launcher, the format
+          of the <code>*_deploy.jar</code> output changes. See the main
+          <a href="#java_binary">java_binary</a> docs for details.</p>
           <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
           .add(
               attr("launcher", LABEL)
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaTestRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaTestRule.java
index dfc26a6019..aa228d3007 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaTestRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaTestRule.java
@@ -44,8 +44,10 @@ public final class BazelJavaTestRule implements RuleDefinition {
     /* <!-- #BLAZE_RULE(java_test).IMPLICIT_OUTPUTS -->
     <ul>
       <li><code><var>name</var>.jar</code>: A Java archive.</li>
-      <li><code><var>name</var>_deploy.jar</code>: A Java archive suitable for deployment. (Only
-        built if explicitly requested.)</li>
+      <li><code><var>name</var>_deploy.jar</code>: A Java archive suitable
+        for deployment. (Only built if explicitly requested.) See the description of the
+        <code><var>name</var>_deploy.jar</code> output from
+        <a href="#java_binary">java_binary</a> for more details.</li>
     </ul>
     <!-- #END_BLAZE_RULE.IMPLICIT_OUTPUTS --> */
     return builder