The Java Plugin - Gradle User Manual

# The Java Plugin

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

## 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

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")