Rules
java_binary
View rule sourcejava_binary(name, deps, srcs, data, resources, args, classpath_resources, compatible_with, create_executable, deploy_env, deploy_manifest_lines, deprecation, distribs, env, exec_compatible_with, exec_properties, features, javacopts, jvm_flags, launcher, licenses, main_class, output_licenses, plugins, resource_jars, resource_strip_prefix, restricted_to, runtime_deps, stamp, tags, target_compatible_with, testonly, toolchains, use_launcher, use_testrunner, visibility)
Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule.
The wrapper shell script uses a classpath that includes, among other things, a jar file for each
library on which the binary depends. When running the wrapper shell script, any nonempty
JAVABIN
environment variable will take precedence over the version specified via
Bazel's --java_runtime_version
flag.
The wrapper script accepts several unique flags. Refer to
//src/main/java/com/google/devtools/build/lib/bazel/rules/java/java_stub_template.txt
for a list of configurable flags and environment variables accepted by the wrapper.
Implicit output targets
name.jar
: A Java archive, containing the class files and other resources corresponding to the binary's direct dependencies.name-src.jar
: An archive containing the sources ("source jar").name_deploy.jar
: A Java archive suitable for deployment (only built if explicitly requested).Building the
<name>_deploy.jar
target for your rule creates a self-contained jar file with a manifest that allows it to be run with thejava -jar
command or with the wrapper script's--singlejar
option. Using the wrapper script is preferred tojava -jar
because it also passes the JVM flags and the options to load native libraries.The deploy jar contains all the classes that would be found by a classloader that searched the classpath from the binary's wrapper script from beginning to end. It also contains the native libraries needed for dependencies. These are automatically loaded into the JVM at runtime.
If your target specifies a launcher 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.
name_deploy-src.jar
: An archive containing the sources collected from the transitive closure of the target. These will match the classes in thedeploy.jar
except where jars have no matching source jar.
A deps
attribute is not allowed in a java_binary
rule without
srcs
; such a rule requires a
main_class
provided by
runtime_deps
.
The following code snippet illustrates a common mistake:
java_binary( name = "DontDoThis", srcs = [ ..., "GeneratedJavaFile.java", # a generated .java file ], deps = [":generating_rule"], # rule that generates that file )
Do this instead:
java_binary( name = "DoThisInstead", srcs = [ ..., ":generating_rule", ], )
Arguments
Attributes | |
---|---|
name |
Name; required A unique name for this target. It is good practice to use the name of the source file that is the main entry point of the application (minus the extension). For example, if your entry point is called Main.java , then your name could be Main .
|
deps
|
List of labels; default is deps at
Typical attributes defined by
most build rules.
|
srcs
|
List of labels; default is
Source files of type
Source files of type
Rules: if the rule (typically
This argument is almost always required, except if a
|
resources
|
List of labels; default is
If resources are specified, they will be bundled in the jar along with the usual
Resources may be source files or generated files. |
classpath_resources
|
List of labels; default is
A list of resources that must be located at the root of the java tree. This attribute's
only purpose is to support third-party libraries that require that their resources be
found on the classpath as exactly |
create_executable
|
Boolean; nonconfigurable; default is java_single_jar instead.
|
deploy_env
|
List of labels; default is java_binary targets which represent the deployment
environment for this binary.
Set this attribute when building a plugin which will be loaded by another
java_binary .Setting this attribute excludes all dependencies from the runtime classpath (and the deploy jar) of this binary that are shared between this binary and the targets specified in deploy_env .
|
deploy_manifest_lines
|
List of strings; default is META-INF/manifest.mf file generated for the
*_deploy.jar target. The contents of this attribute are not subject
to "Make variable" substitution.
|
javacopts
|
List of strings; default is These compiler options are passed to javac after the global compiler options. |
jvm_flags
|
List of strings; default is 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 Note that this attribute has no effect on |
launcher
|
Label; default is bin/java program included with the JDK.
The target must be a cc_binary . Any cc_binary that
implements the
Java Invocation API can be specified as a value for this attribute.
By default, Bazel will use the normal JDK launcher (bin/java or java.exe). The related Note that your native (C++, SWIG, JNI) dependencies will be built differently depending on whether you are using the JDK launcher or another launcher:
When using any launcher other than the default JDK launcher, the format
of the |
main_class
|
String; default is main() method to use as entry point.
If a rule uses this option, it does not need a srcs=[...] list.
Thus, with this attribute one can make an executable from a Java library that already
contains one or more main() methods.
The value of this attribute is a class name, not a source file. The class must be
available at runtime: it may be compiled by this rule (from |
plugins
|
List of labels; default is java_plugin specified in this attribute will be run whenever this rule
is built. A library may also inherit plugins from dependencies that use
exported_plugins . Resources
generated by the plugin will be included in the resulting jar of this rule.
|
resource_jars
|
List of labels; default is |
resource_strip_prefix
|
String; default is
If specified, this path prefix is stripped from every file in the |
runtime_deps
|
List of labels; default is deps , these will appear on the runtime classpath, but unlike
them, not on the compile-time classpath. Dependencies needed only at runtime should be
listed here. Dependency-analysis tools should ignore targets that appear in both
runtime_deps and deps .
|
stamp
|
Integer; default is
Stamped binaries are not rebuilt unless their dependencies change. |
use_launcher
|
Boolean; default is If this attribute is set to false, the
launcher attribute and the related
|
use_testrunner
|
Boolean; default is com.google.testing.junit.runner.BazelTestRunner ) class as the
main entry point for a Java program, and provide the test class
to the test runner as a value of bazel.test_suite
system property.
You can use this to override the default
behavior, which is to use test runner for
java_test rules,
and not use it for java_binary rules. It is unlikely
you will want to do this. One use is for AllTest
rules that are invoked by another rule (to set up a database
before running the tests, for example). The AllTest
rule must be declared as a java_binary , but should
still use the test runner as its main entry point.
The name of a test runner class can be overridden with main_class attribute.
|
java_lite_proto_library
View rule sourcejava_lite_proto_library(name, deps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)
java_lite_proto_library
generates Java code from .proto
files.
deps
must point to proto_library
rules.
Example:
java_library(
name = "lib",
runtime_deps = [":foo"],
)
java_lite_proto_library(
name = "foo",
deps = [":bar"],
)
proto_library(
name = "bar",
)
Arguments
Attributes | |
---|---|
name |
Name; required A unique name for this target. |
deps
|
List of labels; default is proto_library
rules to generate Java code for.
|
java_proto_library
View rule sourcejava_proto_library(name, deps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)
java_proto_library
generates Java code from .proto
files.
deps
must point to proto_library
rules.
Example:
java_library(
name = "lib",
runtime_deps = [":foo_java_proto"],
)
java_proto_library(
name = "foo_java_proto",
deps = [":foo_proto"],
)
proto_library(
name = "foo_proto",
)
Arguments
Attributes | |
---|---|
name |
Name; required A unique name for this target. |
deps
|
List of labels; default is proto_library
rules to generate Java code for.
|