The Java Plugin

Table of Contents

Usage
Project layout
Source sets
Tasks
Dependency management
Convention properties
Javadoc
Clean
Resources
CompileJava
Test
Jar

The Java plugin adds Java compilation along with testing and bundling capabilities to a project. It serves as the basis for many of the other Gradle plugins.

Usage

To use the Java plugin, include the following in your build script:

Example: Using the Java plugin

build.gradle

apply plugin: 'java'

Project layout

The Java plugin assumes the project layout shown below. None of these directories need to exist or have anything in them. The Java plugin will compile whatever it finds, and handles anything which is missing.

Java plugin - default project layout

Directory Meaning

src/main/java

Production Java source

src/main/resources

Production resources

src/test/java

Test Java source

src/test/resources

Test resources

src/sourceSet/java

Java source for the given source set

src/sourceSet/resources

Resources for the given source set

Changing the project layout

You configure the project layout by configuring the appropriate source set. This is discussed in more detail in the following sections. Here is a brief example which changes the main Java and resource source directories.

Example: Custom Java source layout

build.gradle

sourceSets {
    main {
        java {
            srcDirs = ['src/java']
        }
        resources {
            srcDirs = ['src/resources']
        }
    }
}

Source sets

The plugin adds the following source sets:

main

Contains the production source code of the project, which is compiled and assembled into a JAR.

test

Contains your test source code, which is compiled and executed using JUnit or TestNG. These are typically unit tests, but you can include any test in this source set as long as they all share the same compilation and runtime classpaths.

Source set properties

The following table lists some of the important properties of a source set. You can find more details in the API documentation for SourceSet.

(read-only) String name

The name of the source set, used to identify it. Default value: Not null

(read-only) SourceSetOutput output

The output files of the source set, containing its compiled classes and resources. Default value: Not null

FileCollection output.classesDirs

The directories to generate the classes of this source set into. Default value: Not null

File output.resourcesDir

The directory to generate the resources of this source set into. Default value: buildDir/resources/name

FileCollection compileClasspath

The classpath to use when compiling the source files of this source set. Default value: sourceSetCompileClasspath configuration.

FileCollection annotationProcessorPath

The processor path to use when compiling the source files of this source set. Default value: sourceSetAnnotationProcessor configuration.

FileCollection runtimeClasspath

The classpath to use when executing the classes of this source set. Default value: output + sourceSetRuntimeClasspath configuration.

(read-only) SourceDirectorySet java

The Java source files of this source set. Contains only .java files found in the Java source directories, and excludes all other files. Default value: Not null

Set<File> java.srcDirs

The source directories containing the Java source files of this source set. Default value: [projectDir/src/name/java]. Can set using anything described in the section called “Understanding implicit conversion to file collections”.

File java.outputDir

The directory to generate compiled Java sources into. Default value: buildDir/classes/java/sourceSetName. Can set using anything described in the section called “File paths in depth”.

(read-only) SourceDirectorySet resources

The resources of this source set. Contains only resources, and excludes any .java files found in the resource source directories. Other plugins, such as the Groovy plugin, exclude additional types of files from this collection. Default value: Not null

Set<File> resources.srcDirs

The source directories containing the resources of this source set. Default value: [projectDir/src/name/resources]. Can set using anything described in the section called “Understanding implicit conversion to file collections”.

(read-only) SourceDirectorySet allJava

All .java files of this source set. Some plugins, such as the Groovy plugin, add additional Java source files to this collection. Default value: java

(read-only) SourceDirectorySet allSource

All source files of this source set. This include all resource files and all Java source files. Some plugins, such as the Groovy plugin, add additional source files to this collection. Default value: resources + java

Defining new source sets

See the integration test example in the Testing in Java & JVM projects chapter.

Some other simple source set examples

Adding a JAR containing the classes of a source set:

Example: Assembling a JAR for a source set

build.gradle

task intTestJar(type: Jar) {
    from sourceSets.intTest.output
}

Generating Javadoc for a source set:

Example: Generating the Javadoc for a source set

build.gradle

task intTestJavadoc(type: Javadoc) {
    source sourceSets.intTest.allJava
}

Adding a test suite to run the tests in a source set:

Example: Running tests in a source set

build.gradle

task intTest(type: Test) {
    testClassesDirs = sourceSets.intTest.output.classesDirs
    classpath = sourceSets.intTest.runtimeClasspath
}

Tasks

The Java plugin adds a number of tasks to your project, as shown below.

compileJava(type: JavaCompile)

Compiles production Java source files using javac. Depends on all tasks which produce the compile classpath. This includes the jar task for project dependencies included in the compile configuration.

processResources(type: Copy)

Copies production resources into the production resources directory.

classes(type: Task)

Assembles the production classes and resources directories.

compileTestJava(type: JavaCompile)

Compiles test Java source files using javac. Depends on compile, plus all tasks which produce the test compile classpath.

processTestResources(type: Copy)

Copies test resources into the test resources directory.

testClasses(type: Task)

Assembles the test classes and resources directories. Depends on compileTestJava task and processTestResources task. Some plugins add additional test compilation tasks.

jar(type: Jar)

Assembles the JAR file. Depends on compile.

javadoc(type: Javadoc)

Generates API documentation for the production Java source, using Javadoc. Depends on compile.

test(type: Test)

Runs the unit tests using JUnit or TestNG. Depends on compile, compileTest, plus all tasks which produce the test runtime classpath.

uploadArchives(type: Upload)

Uploads artifacts in the archives configuration, including the JAR file. Depends on the tasks which produce the artifacts in the archives configuration, including jar.

clean(type: Delete)

Deletes the project build directory.

cleanTaskName(type: Delete)

Deletes files created by specified task. cleanJar will delete the JAR file created by the jar task, and cleanTest will delete the test results created by the test task.

For each source set you add to the project, the Java plugin adds the following compilation tasks:

SourceSet Tasks

compileSourceSetJava(type: JavaCompile)

Compiles the given source set’s Java source files using javac. Depends on all tasks which produce the source set’s compile classpath.

processSourceSetResources(type: Copy)

Copies the given source set’s resources into the resources directory.

sourceSetClasses(type: Task)

Assembles the given source set’s classes and resources directories. Depends on the compileSourceSetJava task and the processSourceSetResources task. Some plugins add additional compilation tasks for the source set.

Lifecycle Tasks

The Java plugin also adds a number of tasks which form a lifecycle for the project:

assemble(type: Task)

Assembles all the archives in the project. Depends on all archive tasks in the project, including jar. Some plugins add additional archive tasks to the project.

check(type: Task)

Performs all verification tasks in the project. Depends on all verification tasks in the project, including test. Some plugins add additional verification tasks to the project.

build(type: Task)

Performs a full build of the project. Depends on check and assemble.

buildNeeded(type: Task)

Performs a full build of the project and all projects it depends on. Depends on build and buildNeeded tasks in all project lib dependencies of the testRuntime configuration.

buildDependents(type: Task)

Performs a full build of the project and all projects which depend on it. Depends on build and buildDependents tasks in all projects with a project lib dependency on this project in a testRuntime configuration.

buildConfigName(type: Task)

Assembles the artifacts in the specified configuration. The task is added by the Base plugin which is implicitly applied by the Java plugin. Depends on the tasks which produce the artifacts in configuration ConfigName.

uploadConfigName(type: Upload)

Assembles and uploads the artifacts in the specified configuration. The task is added by the Base plugin which is implicitly applied by the Java plugin. Depends on the tasks which uploads the artifacts in configuration ConfigName.

The following diagram shows the relationships between these tasks.

Figure: Java plugin - tasks

Java plugin - tasks

Dependency management

The Java plugin adds a number of dependency configurations to your project, as shown below. It assigns those configurations to tasks such as compileJava and test.

Dependency configurations

To find information on the api configuration, please consult the Java Library Plugin reference documentation and the Dependency Management Tutorial.

compile(Deprecated)

Compile time dependencies. Superseded by implementation.

implementation extends compile

Implementation only dependencies.

compileOnly

Compile time only dependencies, not used at runtime.

compileClasspath extends compile, compileOnly, implementation

Compile classpath, used when compiling source. Used by task compileJava.

annotationProcessor

Annotation processors used during compilation.

runtime(Deprecated) extends compile

Runtime dependencies. Superseded by runtimeOnly.

runtimeOnly

Runtime only dependencies.

runtimeClasspath extends runtimeOnly, runtime, implementation

Runtime classpath contains elements of the implementation, as well as runtime only elements.

testCompile(Deprecated) extends compile

Additional dependencies for compiling tests. Superseded by testImplementation.

testImplementation extends testCompile, implementation

Implementation only dependencies for tests.

testCompileOnly

Additional dependencies only for compiling tests, not used at runtime.

testCompileClasspath extends testCompile, testCompileOnly, testImplementation

Test compile classpath, used when compiling test sources. Used by task compileTestJava.

testRuntime(Deprecated) extends runtime, testCompile

Additional dependencies for running tests only. Used by task test. Superseded by testRuntimeOnly.

testRuntimeOnly extends runtimeOnly

Runtime only dependencies for running tests. Used by task test.

testRuntimeClasspath extends testRuntimeOnly, testRuntime, testImplementation

Runtime classpath for running tests.

archives

Artifacts (e.g. jars) produced by this project. Used by tasks uploadArchives.

default extends runtime

The default configuration used by a project dependency on this project. Contains the artifacts and dependencies required by this project at runtime.

Figure: Java plugin - dependency configurations

Java plugin - dependency configurations

For each source set you add to the project, the Java plugins adds the following dependency configurations:

SourceSet dependency configurations

sourceSetCompile(Deprecated)

Compile time dependencies for the given source set. Superseded by sourceSetImplementation.

sourceSetImplementation extends sourceSetCompile

Compile time dependencies for the given source set. Used by sourceSetCompileClasspath, sourceSetRuntimeClasspath.

sourceSetCompileOnly

Compile time only dependencies for the given source set, not used at runtime.

sourceSetCompileClasspath extends compileSourceSetJava

Compile classpath, used when compiling source. Used by sourceSetCompile, sourceSetCompileOnly, sourceSetImplementation.

sourceSetAnnotationProcessor

Annotation processors used during compilation of this source set.

sourceSetRuntime(Deprecated)

Runtime dependencies for the given source set. Used by sourceSetCompile. Superseded by sourceSetRuntimeOnly.

sourceSetRuntimeOnly

Runtime only dependencies for the given source set.

sourceSetRuntimeClasspath extends sourceSetRuntimeOnly, sourceSetRuntime, sourceSetImplementation

Runtime classpath contains elements of the implementation, as well as runtime only elements.

Convention properties

The Java plugin adds a number of convention properties to the project, shown below. You can use these properties in your build script as though they were properties of the project object.

Directory properties

String reporting.baseDir

The name of the directory to generate reports into, relative to the build directory. Default value: reports

(read-only) File reportsDir

The directory to generate reports into. Default value: buildDir/reporting.baseDir

String testResultsDirName

The name of the directory to generate test result .xml files into, relative to the build directory. Default value: test-results

(read-only) File testResultsDir

The directory to generate test result .xml files into. Default value: buildDir/testResultsDirName

String testReportDirName

The name of the directory to generate the test report into, relative to the reports directory. Default value: tests

(read-only) File testReportDir

The directory to generate the test report into. Default value: reportsDir/testReportDirName

String libsDirName

The name of the directory to generate libraries into, relative to the build directory. Default value: libs

(read-only) File libsDir

The directory to generate libraries into. Default value: buildDir/libsDirName

String distsDirName

The name of the directory to generate distributions into, relative to the build directory. Default value: distributions

(read-only) File distsDir

The directory to generate distributions into. Default value: buildDir/distsDirName

String docsDirName: :_The name of the directory to generate documentation into, relative to the build directory._ Default value: docs

(read-only) File docsDir

The directory to generate documentation into. Default value: buildDir/docsDirName

String dependencyCacheDirName

The name of the directory to use to cache source dependency information, relative to the build directory. Default value: dependency-cache

Other convention properties

(read-only) SourceSetContainer sourceSets

Contains the project’s source sets. Default value: Not null SourceSetContainer

JavaVersion sourceCompatibility

Java version compatibility to use when compiling Java source. Default value: version of the current JVM in use JavaVersion. Can also set using a String or a Number, e.g. '1.5' or 1.5.

JavaVersion targetCompatibility

Java version to generate classes for. Default value: sourceCompatibility. Can also set using a String or Number, e.g. '1.5' or 1.5.

String archivesBaseName

The basename to use for archives, such as JAR or ZIP files. Default value: projectName

Manifest manifest

The manifest to include in all JAR files. Default value: an empty manifest.

These properties are provided by convention objects of type JavaPluginConvention, and BasePluginConvention.

Javadoc

The javadoc task is an instance of Javadoc. It supports the core Javadoc options and the options of the standard doclet described in the reference documentation of the Javadoc executable. For a complete list of supported Javadoc options consult the API documentation of the following classes: CoreJavadocOptions and StandardJavadocDocletOptions.

Javadoc properties

FileCollection classpath

Default value: sourceSets.main.output + sourceSets.main.compileClasspath

FileTree source

Default value: sourceSets.main.allJava. Can set using anything described in the section called “Understanding implicit conversion to file collections”.

File destinationDir

Default value: docsDir/javadoc

String title

Default value: The name and version of the project

Clean

The clean task is an instance of Delete. It simply removes the directory denoted by its dir property.

Clean properties

File dir

Default value: buildDir

Resources

The Java plugin uses the Copy task for resource handling. It adds an instance for each source set in the project. You can find out more about the copy task in the section called “File copying in depth”.

ProcessResources properties

Object srcDirs

Default value: sourceSet.resources. Can set using anything described in the section called “Understanding implicit conversion to file collections”.

File destinationDir

Default value: sourceSet.output.resourcesDir. Can set using anything described in the section called “File paths in depth”.

CompileJava

The Java plugin adds a JavaCompile instance for each source set in the project. Some of the most common configuration options are shown below.

Compile properties

FileCollection classpath

Default value: sourceSet.compileClasspath

FileTree source

Default value: sourceSet.java. Can set using anything described in the section called “Understanding implicit conversion to file collections”.

File destinationDir

Default value: sourceSet.java.outputDir

By default, the Java compiler runs in the Gradle process. Setting options.fork to true causes compilation to occur in a separate process. In the case of the Ant javac task, this means that a new process will be forked for each compile task, which can slow down compilation. Conversely, Gradle’s direct compiler integration (see above) will reuse the same compiler process as much as possible. In both cases, all fork options specified with options.forkOptions will be honored.

Incremental Java compilation

Starting with Gradle 2.1, it is possible to compile Java incrementally. See the JavaCompile task for information on how to enable it.

Main goals for incremental compilations are:

  • Avoid wasting time compiling source classes that don’t have to be compiled. This means faster builds, especially when a change to a source class or a jar does not incur recompilation of many source classes that depend on the changed input.

  • Change as few output classes as possible. Classes that don’t need to be recompiled remain unchanged in the output directory. An example scenario when this is really useful is using JRebel - the fewer output classes are changed the quicker the JVM can use refreshed classes.

The incremental compilation at a high level:

  • The stale class detection favors reliability over speed. The algorithm uses bytecode analysis and deals gracefully with compiler optimizations (inlining of non-private constants), transitive class dependencies, etc. Example: When a class with a public constant changes, we eagerly compile classes that use the same constants to avoid problems with constants inlined by the compiler.

  • To make incremental compilation fast, we cache class analysis results and jar snapshots. The initial incremental compilation can be slower due to the cold caches.

Known issues

  • If a compile task fails due to a compile error, it will do a full compilation again the next time it is invoked.

  • Because of type erasure, the incremental compiler is not able to recognize when a type is only used in a type parameter, and never actually used in the code. For example, imagine that you have the following code: List<? extends A> list = Lists.newArrayList(); but that no member of A is in practice used in the code, then changes to A will not trigger recompilation of the class. In practice, this should very rarely be an issue.

Incremental annotation processing

Starting with Gradle 4.7, the incremental compiler also supports incremental annotation processing. Annotation processors need to opt in to this feature, otherwise they will trigger a full recompilation.

As a user you can see which annotation processors are triggering full recompilations in the --info log. Incremental annotation processing will be deactivated if a custom executable or javaHome is configured on the compile task.

Making an annotation processor incremental

Gradle supports incremental compilation for two common categories of annotation processors: "Isolating" and "Aggregating". As a processor author, please consult the information below to decide which category fits your processor. You can then register it for incremental compilation in its META-INF folder. The format is one line per processor, with the qualified name of the processor and its category separated by a comma.

Example: Registering incremental annotation processors

processor/src/main/resources/META-INF/gradle/incremental.annotation.processors

EntityProcessor,isolating
ServiceRegistryProcessor,aggregating

Processors that don’t fit these categories will result in full recompilation. This includes processors that use java.io instead of the Filer API and processors that need to read or write resource files.

Isolating annotation processors

These look at each annotated element in isolation, creating generated files or validation messages for it. For instance an EntityProcessor could create a <TypeName>Repository for each type annotated with @Entity.

Example: An isolated annotation processor

processor/src/main/java/EntityProcessor.java

Set<? extends Element> entities = roundEnv.getElementsAnnotatedWith(entityAnnotation);
for (Element entity : entities) {
    createRepository((TypeElement) entity);
}

Isolating processors have the following limitations:

  • Can’t read resources

  • Can’t write resources

  • Can’t have any side effects except for using the Filer and Messager APIs

  • Can’t depend on compiler-specific APIs like com.sun.source.util.Trees

  • Must provide exactly one originating element for each file generated with the Filer API

  • Must make all decisions about an element based on information reachable from its AST. For instance it can query the super class, method return types etc, but can’t look at other, unrelated elements.

Gradle will recompile the generated file whenever the source file is affected. If the source file is deleted, the generated file is deleted.

Aggregating annotation processors

These aggregate several source files into one ore more output files or validation messages. For instance, a ServiceRegistryProcessor could create a single ServiceRegistry with one method for each type annotated with @Service

Example: An aggregating annotation processor

processor/src/main/java/ServiceRegistryProcessor.java

JavaFileObject serviceRegistry = filer.createSourceFile("ServiceRegistry");
Writer writer = serviceRegistry.openWriter();
writer.write("public class ServiceRegistry {");
for (Element service : roundEnv.getElementsAnnotatedWith(serviceAnnotation)) {
    addServiceCreationMethod(writer, (TypeElement) service);
}
writer.write("}");
writer.close();

Aggregating processors have the following limitations:

  • Its annotations need to have CLASS or RUNTIME retention

  • Can’t read resources (this may change in the future)

  • Can’t write resources (this may change in the future)

  • Can’t have any side effects except for using the Filer and Messager APIs

  • Can’t depend on compiler-specific APIs like com.sun.source.util.Trees

  • Can’t depend on information only available from source files (See comment on parameter names below)

Gradle will always reprocess (but not recompile) all annotated files that the processor was registered for. If your aggregating processor requires access to parameter names, you need to instruct users to add the -parameters compiler argument. Gradle will always recompile any files the processor generates.

Compile avoidance

If a dependent project has changed in an ABI-compatible way (only its private API has changed), then Java compilation tasks will be up-to-date. This means that if project A depends on project B and a class in B is changed in an ABI-compatible way (typically, changing only the body of a method), then Gradle won’t recompile A.

Some of the types of changes that do not affect the public API and are ignored:

  • Changing a method body

  • Changing a comment

  • Adding, removing or changing private methods, fields, or inner classes

  • Adding, removing or changing a resource

  • Changing the name of jars or directories in the classpath

  • Renaming a parameter

Compile-avoidance is deactivated if annotation processors are found on the compile classpath, because for annotation processors the implementation details matter. Annotation processors should be declared on the annotation processor path instead. Gradle 5.0 will ignore processors on the compile classpath.

Example: Declaring annotation processors

build.gradle

dependencies {
    // The dagger compiler and its transitive dependencies will only be found on annotation processing classpath
    annotationProcessor 'com.google.dagger:dagger-compiler:2.8'

    // And we still need the Dagger library on the compile classpath itself
    implementation 'com.google.dagger:dagger:2.8'
}

Test

The test task is an instance of Test. It automatically detects and executes all unit tests in the test source set. It also generates a report once test execution is complete. JUnit and TestNG are both supported. Have a look at Test for the complete API.

See the Testing in Java & JVM projects chapter for more details.

Jar

The jar task creates a JAR file containing the class files and resources of the project. The JAR file is declared as an artifact in the archives dependency configuration. This means that the JAR is available in the classpath of a dependent project. If you upload your project into a repository, this JAR is declared as part of the dependency descriptor. You can learn more about how to work with archives in the section called “Archive creation in depth” and artifact configurations in Publishing artifacts.

Manifest

Each jar or war object has a manifest property with a separate instance of Manifest. When the archive is generated, a corresponding MANIFEST.MF file is written into the archive.

Example: Customization of MANIFEST.MF

build.gradle

jar {
    manifest {
        attributes("Implementation-Title": "Gradle",
                   "Implementation-Version": version)
    }
}

You can create stand-alone instances of a Manifest. You can use that for example, to share manifest information between jars.

Example: Creating a manifest object.

build.gradle

ext.sharedManifest = manifest {
    attributes("Implementation-Title": "Gradle",
               "Implementation-Version": version)
}
task fooJar(type: Jar) {
    manifest = project.manifest {
        from sharedManifest
    }
}

You can merge other manifests into any Manifest object. The other manifests might be either described by a file path or, like in the example above, by a reference to another Manifest object.

Example: Separate MANIFEST.MF for a particular archive

build.gradle

task barJar(type: Jar) {
    manifest {
        attributes key1: 'value1'
        from sharedManifest, 'src/config/basemanifest.txt'
        from('src/config/javabasemanifest.txt',
             'src/config/libbasemanifest.txt') {
            eachEntry { details ->
                if (details.baseValue != details.mergeValue) {
                    details.value = baseValue
                }
                if (details.key == 'foo') {
                    details.exclude()
                }
            }
        }
    }
}

Manifests are merged in the order they are declared by the from statement. If the base manifest and the merged manifest both define values for the same key, the merged manifest wins by default. You can fully customize the merge behavior by adding eachEntry actions in which you have access to a ManifestMergeDetails instance for each entry of the resulting manifest. The merge is not immediately triggered by the from statement. It is done lazily, either when generating the jar, or by calling writeTo or effectiveManifest

You can easily write a manifest to disk.

Example: Saving a MANIFEST.MF to disk

build.gradle

jar.manifest.writeTo("$buildDir/mymanifest.mf")