Gradle Java Plugin
External
Internal
TODEPLETE
Overview
The Java plugin adds Java compilation, testing and packaging capabilities to a project. It also serves as the basis for many of the other JVM language Gradle plugins.
plugins {
id 'java'
}
However, Java Library plugin should be used by default with Java projects instead of Java plugin. Java Library plugin extends the Java plugin, so it offers all the features of the Java plugin, plus a set of additional ones:
The Java plugin instantiates by default two source sets ("main" and "test"). Each of these source sets has an associated compile task: compileJava (which should have been called compileMainJava) for the "main" source set and compileTestJava for the "test" source set. To compile the production and test code:
- put the production source code in 'src/main/java' directory.
- put the test source code under 'src/test/java' directory.
- declare your production compile dependencies in the compileOnly or implementation configurations.
- declare your test compile dependencies in the testCompileOnly or testImplementation configurations.
- Run the compileJava task for the production code and compileTestJava for the tests.
Concepts
Source Set
A source set is a logical grouping of source files and resources, typically associated on the base of their purpose: application production code, test code, etc. Each source set contains sources and resources from typically one, but possibly more directories, which are listed as part of the source set. The files that form a source set don't have to be located in the same directory. The source set concept was introduced by the Java plugin, which also instantiates by default two source sets: main and test. They correspond to the conventional directories from "src":
.
└── src
├── main ← source set "main"
│ └── java
│ └── playground
│ └── Sample.java
└── test ← source set "test"
└── java
└── playground
└── SampleTest.java
Aside from the source files and resources, the source set also keeps track of various classpaths, including any dependencies, require the compile or run the code. It does that by maintaining a set of configurations corresponding to the compilation classpath, annotation processor classpath and runtime classpath. Each source set has associated an "<source-set-name>implementation" configuration. In case of the "main" source set, main is omitted and the configuration is named simply "implementation". Also see:
Finally, the source set keeps track of where the compiled class files are placed, as a source set output.
The Java plugin automatically creates compilation tasks for each source set, naming them "compile<source-set-name>Java". In case of the "main" source set, the <source-set-name> is omitted and the task is called "compileJava".
Each source set is internally maintained in the runtime project hierarchy as child of the Java plugin. However, it can be configured via a top-level script blocks:
plugins {
id 'java'
}
sourceSets {
main {
java {
srcDirs = ['src/main/java']
}
}
test {
java {
srcDirs = ['src/test/java']
}
}
}
More details on how to reconfigure existing source sets is available below in the section Source Set Customization.
Resource Files
Java projects typically include resource other than source files, such as property files, that may need processing - for example by replacing tokens within the files - and packaging them within the final JAR. Typical use cases for resource files are images, configuration files, localization data. The Java plugin handles this automatically by creating a dedicated task for each source set, called "process<source-set-name>Resources", or "processResources" for the main source set.
Default Source Sets
The "main" Source Set
The main source set is conventionally associated with all source files found under src/main/java and all resource files from src/main/resources. The sources managed by the main source set are compiled by the compileJava task. The resources are processed by the processResources task. The main source set is associated with the "compileOnly", "runtimeOnly" and "implementation" configurations. The jar task packages the main source set compiled classes and resources.
The "test" Source Set
The "test" source set is conventionally associated with all the source file under src/test/java. The sources managed by the "test" source set are compiled by the compileTestJava task, and the tests are executed by the test task. The resources are processed by the processTestResources task. The test source set is associated with the "testCompileOnly", "testRuntimeOnly" and "testImplementation" configurations.
Custom Source Set
New source sets can be defined, typically for one or both of the following reasons:
- The source code should be keep separate from the existing source sets for aesthetics and manageability.
- The source code requires a different, unique compilation or runtime classpaths.
- The generated code should be handled differently than the code from main and test source set.
Java Toolchain
The toolchain options protect against problems with the project being built with different Java versions.
TODO: https://docs.gradle.org/current/userguide/toolchains.html.
Tasks
buildDependents
buildNeeded
classes
clean
compileJava
The "compileJava" task compiles the sources managed by the "main" source set. The task is backed by the JavaCompile type.
To change compiler options, configure the task as follows:
compileJava {
options.incremental = true
options.fork = true
options.failOnError = false
}
For more details, see:
compileTestJava
The "compileTestJava" task compiles the sources managed by the "test" source set. The task is backed by the JavaCompile type, and can be used to change compilation options for test compilation. The syntax is similar to the one shown above, just applied inside the "compileTestJava" script block.
jar
Assembles the JAR file from the classes produced by the "main" source set source files and "main" source set resources. It produces a single JAR conventionally named <project>-<version>.jar. Depends on the classes task. The task is backed by the Jar type. Configuration details in:
Note that Java Library plugin integrates the "jar" task with the standard lifecycle task assemble.
javadoc
Generates Javadoc for the "main" source set classes.
processResources
The "processResources" task processes the resources managed by the main source set. The task is an implementation of the Copy type. For more details see:
processTestResources
The "processTestResources" task processes the resources managed by the test source set. The task is an implementation of the Copy type. For more details see:
test
The "test" task runs all the tests from the "test" source set (src/test/java). Note that Java Library plugin integrates the "test" task with the standard lifecycle task check.
testClasses
Task Inherited
assemble
build
check
Java Plugin Predefined Task Types
JavaCompile
JavaCompile exposed as "compileJava" task
Jar
JavaExec
Customization
Various aspects related to Java compilation are set in the "java" script block:
java {
toolchain {
languageVersion = JavaLanguageVersion.of(11)
}
}
Use a Specific Java Version
By default, Gradle will compile Java code to the language level of the JVM running Gradle. Since version 8, the Java compiler can be configured to produce bytecode for an older Java version, while making sure the code does not use any APIs from a more recent version.
This can be changed with the usage of Java toolchains.
java {
toolchain {
languageVersion = JavaLanguageVersion.of(11)
}
}
The level can be changed at task level:
compileJava {
options.release = 11
}
The legacy way to configure this is to use "sourceCompatibility" and "targetCompatibility" at the top level of build.gradle file:
sourceCompatibility = 15
targetCompatibility = 11
sourceCompatibility defines the language version of the source code.
targetCompatibility defines the minimum JVM version the code should be run on (the version of the bytecode the compiler generates).
If the toolchain is used, that makes it illegal to use sourceCompatibility and targetCompatibility.
Compiler Options Customization
Compiler options can be configured in the compileJava and compileTestJava tasks, as shown above.
Source Set Customization
Custom Source Directories
The source directories for both main and test source sets can be reconfigured as follows (the example only shows main, test is similar):
sourceSets {
main {
java {
srcDirs = ['src/somethingelse/java']
}
}
}
To add directories, use this syntax:
sourceSets {
main {
java {
srcDir 'src/somethingelse/java'
}
}
}
It is equivalent with:
sourceSets {
main {
java {
srcDirs = ['src/main/java', 'src/somethingelse/java']
}
}
}