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

compileSourceSetJava —JavaCompile

Depends on: All tasks which contribute to the source set’s compilation classpath

Compiles the given source set’s Java source files using the JDK compiler.

processSourceSetResources —Copy

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

sourceSetClasses —Task

Depends on:compileSourceSetJava,processSourceSetResources

Prepares the given source set’s classes and resources for packaging and execution. Some plugins may add additional compilation tasks for the source set.

The Java plugin attaches some of its tasks to the lifecycle tasks defined by theBase Plugin — which the Java Plugin applies automatically — and it also adds a few other lifecycle tasks:

assemble

Depends on:jar

Aggregate task that assembles all the archives in the project. This task is added by the Base Plugin.

check

Depends on:test

Aggregate task that performs verification tasks, such as running the tests. Some plugins add their own verification tasks tocheck. You should also attach any customTest tasks to this lifecycle task if you want them to execute for a full build. This task is added by the Base Plugin.

build

Depends on:check,assemble

Aggregate tasks that performs a full build of the project. This task is added by the Base Plugin.

buildNeeded

Depends on:build, andbuildNeeded tasks in all projects that are dependencies in thetestRuntimeClasspath configuration.

Performs a full build of the project and all projects it depends on.

buildDependents

Depends on:build, andbuildDependents tasks in all projects that have this project as a dependency in theirtestRuntimeClasspath configurations

Performs a full build of the project and all projects which depend upon it.

buildConfigName — task rule

Depends on: all tasks that generate the artifacts attached to the named — ConfigName — configuration

Assembles the artifacts for the specified configuration. This rule is added by the Base Plugin.

The following diagram shows the relationships between these tasks.

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.

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

name — (read-only)String

The name of the source set, used to identify it.

output — (read-only)SourceSetOutput

The output files of the source set, containing its compiled classes and resources.

output.classesDirs — (read-only)FileCollection

Default value:layout.buildDirectory.dir("classes/java/$name"), e.g.build/classes/java/main

The directories to generate the classes of this source set into. May contain directories for other JVM languages, e.g.build/classes/kotlin/main.

output.resourcesDir — File

Default value:layout.buildDirectory.dir("resources/$name"), e.g.build/resources/main

The directory to generate the resources of this source set into.

compileClasspath — FileCollection

Default value:${name}CompileClasspath configuration

The classpath to use when compiling the source files of this source set.

annotationProcessorPath — FileCollection

Default value:${name}AnnotationProcessor configuration

The processor path to use when compiling the source files of this source set.

runtimeClasspath — FileCollection

Default value:$output,${name}RuntimeClasspath configuration

The classpath to use when executing the classes of this source set.

java — (read-only)SourceDirectorySet

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

java.srcDirs — Set<File>

Default value:src/$name/java, e.g.src/main/java

The source directories containing the Java source files of this source set. You can set this to any value that is described inthis section.

java.destinationDirectory — DirectoryProperty

Default value:layout.buildDirectory.dir("classes/java/$name"), e.g.build/classes/java/main

The directory to generate compiled Java sources into. You can set this to any value that is described inthis section.

resources — (read-only)SourceDirectorySet

The resources of this source set. Contains only resources, and excludes any.java files found in the resource directories. Other plugins, such as theGroovy Plugin, exclude additional types of files from this collection.

resources.srcDirs — Set<File>

Default value:[src/$name/resources]

The directories containing the resources of this source set. You can set this to any type of value that is described inthis section.

allJava — (read-only)SourceDirectorySet

Default value: Same asjava property

All Java files of this source set. Some plugins, such as the Groovy Plugin, add additional Java source files to this collection.

allSource — (read-only)SourceDirectorySet

Default value: Sum of everything in theresources andjava properties

All source files of this source set of any language. This includes all resource files and all Java source files. Some plugins, such as the Groovy Plugin, add additional source files to this collection.

See theintegration test example in theTesting in Java & JVM projects chapter.

Adding a JAR containing the classes of a source set:

Generating Javadoc for a source set:

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

The following diagrams show the dependency configurations for themain source set. You can use this legend to interpret the colors:

• blue background — you can declare dependencies against the configuration.

• green background — the configuration is for consumption by tasks, not for you to declare dependencies.

• grey background — a task.

And the next graph describes thetest source set:

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

sourceSetImplementation

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

sourceSetCompileOnly

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

sourceSetCompileClasspath extendssourceSetCompileOnly,sourceSetImplementation

Compile classpath, used when compiling source. Used bycompileSourceSetJava.

sourceSetAnnotationProcessor

Annotation processors used during compilation of this source set.

sourceSetRuntimeOnly

Runtime only dependencies for the given source set.

sourceSetRuntimeClasspath extendssourceSetRuntimeOnly,sourceSetImplementation

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

toolchain

Java toolchain to be used by tasks using JVM tools, such as compilation and execution. Default value: build JVM toolchain.

JavaVersion sourceCompatibility

Java version compatibility to use when compiling Java source. Default value: language version of the toolchain from this extension.
Note that using atoolchain is preferred to using a compatibility setting for most cases.

JavaVersion targetCompatibility

Java version to generate classes for. Default value:sourceCompatibility.
Note that using atoolchain is preferred to using a compatibility setting for most cases.

withJavadocJar()

Automatically packages Javadoc and creates a variantjavadocElements with an artifact-javadoc.jar, which will be part of the publication.

withSourcesJar()

Automatically packages source code and creates a variantsourceElements with an artifact-sources.jar, which will be part of the publication.

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:reporting.baseDirectory

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:layout.buildDirectory.dir(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:layout.buildDirectory.dir(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:layout.buildDirectory.dir(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:layout.buildDirectory.dir(docsDirName)

String dependencyCacheDirName

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

(read-only)SourceSetContainer sourceSets

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

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.

• If you are using an annotation processor that reads resources (e.g. a configuration file), you need to declare those resources as an input of the compile task.

• If a resource file is changed, Gradle will trigger a full recompilation.

• Using a customexecutable orjavaHome deactivates some optimizations.The compile task does not use incremental build immediately after a compile error or if a Java constant changes.Usetoolchains instead if possible.

• Having a source structure that does not match the package names, while legal for compilation, might end up causing trouble in the toolchain.Even more if annotation processing andcaching are involved.

Please first have a look atincremental Java compilation, as incremental annotation processing builds on top of it.

Gradle supports incremental compilation for two common categories of annotation processors: "isolating" and "aggregating".Please consult the information below to decide which category fits your processor.

You can then register your processor for incremental compilation using a file in the processor’s META-INF directory.The format is one line per processor, with the fully qualified name of the processor class and its case-insensitive category separated by a comma.

If your processor can only decide at runtime whether it is incremental or not, you can declare it as "dynamic" in the META-INF descriptorand return its true type at runtime using theProcessor#getSupportedOptions() method.

Both categories have the following limitations:

• They can only readCLASS orRUNTIME retention annotations.

• They can only read parameter names if the user passes the-parameters compiler argument.

• They must generate their files using theFiler API.Writing files any other way will result in silent failures later on, as these files won’t be cleaned up correctly.If your processor does this, it cannot be incremental.

• They must not depend on compiler-specific APIs likecom.sun.source.util.Trees.Gradle wraps the processing APIs, so attempts to cast to compiler-specific types will fail.If your processor does this, it cannot be incremental, unless you have some fallback mechanism.

• If they useFiler#createResource,thelocation argument must be one of these values fromStandardLocation:CLASS_OUTPUT,SOURCE_OUTPUT, orNATIVE_HEADER_OUTPUT.Any other argument will disable incremental processing.

The fastest category, these look at each annotated element in isolation, creating generated files or validation messages for it.For instance anEntityProcessor could create a<TypeName>Repository for each type annotated with@Entity.

"Isolating" processors have the following additional limitations:

• They must make all decisions (code generation, validation messages) for an annotated type based on information reachable from its AST.This means you can analyze the types' super-class, method return types, annotations etc., even transitively.But you cannot make decisions based on unrelated elements in the RoundEnvironment.Doing so will result in silent failures because too few files will be recompiled later.If your processor needs to make decisions based on a combination of otherwise unrelated elements, mark it as "aggregating" instead.

• They must provide exactly one originating element for each file generated with theFiler API.If zero or many originating elements are provided, Gradle will recompile all source files.

When a source file is recompiled, Gradle will recompile all files generated from it.When a source file is deleted, the files generated from it are deleted.

These can aggregate several source files into one or more output files or validation messages.For instance, aServiceRegistryProcessor could create a singleServiceRegistry with one method for each type annotated with@Service.

Gradle will always reprocess (but not recompile) all annotated files that the processor was registered for.Gradle will always recompile any files the processor generates.