diff options
author | 2016-12-21 02:22:35 +0000 | |
---|---|---|
committer | 2016-12-21 09:49:07 +0000 | |
commit | 9a9120802a2274804ee324c3c7d83b0c087f246e (patch) | |
tree | a38a3b4e358692ef412ccb84243ae7d763071a32 | |
parent | c83a701038abe6cb1a6f6ff63fa24982515105e5 (diff) |
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 |