# JavaPluginExtension

API Documentation: | `JavaPluginExtension`

Common configuration for JVM (Java) based projects. This extension is added by the `JavaBasePlugin` and would be more appropriately named the `JvmPluginExtension` extension. It is used to configure many of the project's JVM-related settings and behavior.

### Properties

Property | Description
`docsDir` | Returns a file pointing to the root directory supposed to be used for all docs.
`sourceCompatibility` | The source compatibility used for compiling Java sources.
`sourceSets` | The source sets container.
`targetCompatibility` | The target compatibility used for compiling Java sources.
`testReportDir` | Returns a file pointing to the root directory to be used for reports.
`testResultsDir` | Returns a file pointing to the root directory of the test results.
`toolchain` | Gets the project wide toolchain requirements that will be used for tasks requiring a tool from the toolchain (e.g. `JavaCompile`).

### Methods

Method | Description
`disableAutoTargetJvm()` | If this method is called, Gradle will not automatically try to fetch dependencies which have a JVM version compatible with the target compatibility of this module.
`manifest()` | Creates a new instance of a `Manifest`.
`manifest(closure)` | Creates and configures a new instance of a `Manifest`. The given closure configures the new manifest instance before it is returned.
`manifest(action)` | Creates and configures a new instance of a `Manifest`.
`registerFeature(name, configureAction)` | Registers a feature.
`toolchain(action)` | Configures the project wide toolchain requirements for tasks that require a tool from the toolchain (e.g. `JavaCompile`).
`withJavadocJar()` | Enables generating a Javadoc artifact for the main feature of this project. If no components with a main feature are defined for this project, this has no effect.
`withSourcesJar()` | Enables generating a sources artifact for the main feature of this project. If no components with a main feature are defined for this project, this has no effect.

### Script blocks

Block | Description
`sourceSets` | Configures the source sets of this project.

### Property details

#### `DirectoryProperty` `docsDir`

Returns a file pointing to the root directory supposed to be used for all docs.

Default with `java` plugin:
  ``${project.layout.buildDirectory}`/docs`

#### `JavaVersion` `sourceCompatibility`

The source compatibility used for compiling Java sources.

Default with `java` plugin:
  Value of the current used JVM (e.g. `JavaVersion.JAVA_1_6` on a 1.6 JVM).

#### `SourceSetContainer` `sourceSets` (read-only)

The source sets container.

#### `JavaVersion` `targetCompatibility`

The target compatibility used for compiling Java sources.

Default with `java` plugin:
  `project.sourceCompatibility`

#### `DirectoryProperty` `testReportDir`

Returns a file pointing to the root directory to be used for reports.

Default with `java` plugin:
  ``${project.reporting.baseDirectory}`/tests`

#### `DirectoryProperty` `testResultsDir`

Returns a file pointing to the root directory of the test results.

Default with `java` plugin:
  ``${project.layout.buildDirectory}`/test-results`

#### `JavaToolchainSpec` `toolchain` (read-only)

Gets the project wide toolchain requirements that will be used for tasks requiring a tool from the toolchain (e.g. `JavaCompile`).

Configuring a toolchain cannot be used together with `sourceCompatibility` or `targetCompatibility` on this extension. Both values will be sourced from the toolchain.

### Method details

#### `void` `disableAutoTargetJvm`()

If this method is called, Gradle will not automatically try to fetch dependencies which have a JVM version compatible with the target compatibility of this module.

This should be used whenever the default behavior is not applicable, in particular when for some reason it's not possible to split a module and that this module only has some classes which require dependencies on higher versions.

#### `Manifest` `manifest`()

Creates a new instance of a `Manifest`.

#### `Manifest` `manifest`(`Closure` closure)

Creates and configures a new instance of a `Manifest`. The given closure configures the new manifest instance before it is returned.

#### `Manifest` `manifest`(``Action`<? super `Manifest`>` action)

Creates and configures a new instance of a `Manifest`.

#### `void` `registerFeature`(`String` name, ``Action`<? super `FeatureSpec`>` configureAction)

Registers a feature.

The new feature will have a default capability corresponding to the "group", "name" + feature name and version of this project. For example, if the group of the component is "org", that the project name is "lib" the version is "1.0" and the feature name is "myFeature", then a capability named "org:lib-my-feature:1.0" is automatically added.

In order to consume this feature in another module add a dependency like the following:

     dependencies {
         implementation(project(":lib")) {
             capabilities {
                 requireCapability("org:lib-my-feature:1.0")
             }
         }
     }

The `FeatureSpec.capability(java.lang.String, java.lang.String, java.lang.String)` method can be used to refine the capabilities of this feature.

#### `JavaToolchainSpec` `toolchain`(``Action`<? super `JavaToolchainSpec`>` action)

Configures the project wide toolchain requirements for tasks that require a tool from the toolchain (e.g. `JavaCompile`).

Configuring a toolchain cannot be used together with `sourceCompatibility` or `targetCompatibility` on this extension. Both values will be sourced from the toolchain.

#### `void` `withJavadocJar`()

Enables generating a Javadoc artifact for the main feature of this project. If no components with a main feature are defined for this project, this has no effect.

Adds a task `javadocJar` that will package the output of the `javadoc` task in a JAR with classifier `javadoc`.

The produced artifact is registered as a documentation variant on the `java` component and added as a dependency on the `assemble` task. This means that if `maven-publish` or `ivy-publish` is also applied, the javadoc JAR will be published.

If the project already has a task named `javadocJar` then no task is created.

The publishing of the Javadoc variant can also be disabled using `ConfigurationVariantDetails.skip()` through `AdhocComponentWithVariants.withVariantsFromConfiguration(org.gradle.api.artifacts.Configuration, org.gradle.api.Action)`, if it should only be built locally by calling or wiring the ':javadocJar' task.

#### `void` `withSourcesJar`()

Enables generating a sources artifact for the main feature of this project. If no components with a main feature are defined for this project, this has no effect.

Adds a task `sourcesJar` that will package the Java sources of the main `SourceSet` in a JAR with classifier `sources`.

The produced artifact is registered as a documentation variant on the `java` component and added as a dependency on the `assemble` task. This means that if `maven-publish` or `ivy-publish` is also applied, the sources JAR will be published.

If the project already has a task named `sourcesJar` then no task is created.

The publishing of the sources variant can be disabled using `ConfigurationVariantDetails.skip()` through `AdhocComponentWithVariants.withVariantsFromConfiguration(org.gradle.api.artifacts.Configuration, org.gradle.api.Action)`, if it should only be built locally by calling or wiring the ':sourcesJar' task.

### Script block details

#### `sourceSets` { }

Configures the source sets of this project.

The given closure is executed to configure the `SourceSetContainer`. The `SourceSetContainer` is passed to the closure as its delegate.

See the example below how `SourceSet` 'main' is accessed and how the `SourceDirectorySet` 'java' is configured to exclude some package from compilation.

    plugins {
        id 'java'
    }

    sourceSets {
      main {
        java {
          exclude 'some/unwanted/package/**'
        }
      }
    }

Delegates to:
  `SourceSetContainer` from `sourceSets`