The Gradle team is excited to announce Gradle @version@.

This release significantly improves the [performance of Kotlin DSL build scripts compilation](#kotlin-dsl-performance), adds several [improvements to Java toolchain support](#java-toolchain-improvements), including vendor selection, and makes it easy to [execute any tasks in a composite build directly from the command line](#composite-builds). This release also introduces new [dependency management APIs for consistent resolution](#dm-features).

The [experimental configuration cache](#configuration-cache) has added support for composite builds and more core plugins shipped with Gradle.

Several other [improvements](#other-improvements) were added in this release.

We don't expect many builds to be affected, but this release [disables outdated TLS v1.0 and v1.1 protocols](#security-tls) to improve the security of builds resolving dependencies from external repositories.

We would like to thank the following community contributors for their contributions to this release of Gradle:

[Marcono1234](https://github.com/Marcono1234),
[Björn Sundahl](https://github.com/Ranzdo),
[Roberto Perez Alcolea](https://github.com/rpalcolea),
[Danny Thomas](https://github.com/DanielThomas),
[Jeff](https://github.com/mathjeff),
[Mattia Tommasone](https://github.com/Raibaz),
[jdai8](https://github.com/jdai8),
[David Burström](https://github.com/davidburstrom),
[Björn Kautler](https://github.com/Vampire),
[Stefan Oehme](https://github.com/oehme),
[Thad House](https://github.com/ThadHouse),
[knittl](https://github.com/knittl),
[hywelbennett](https://github.com/hywelbennett),
[wboult](https://github.com/wboult),
[Gregorios Leach](https://github.com/simtel12).

## Upgrade instructions

Switch your build to use Gradle @version@ by updating your wrapper:

`./gradlew wrapper --gradle-version=@version@`

See the [Gradle 6.x upgrade guide](userguide/upgrading_version_6.html#changes_@baseVersion@) to learn about deprecations, breaking changes and other considerations when upgrading to Gradle @version@.

NOTE: Gradle 6.8 has had **three** patch releases, which fix several issues from the original release.
We recommend always using the latest patch release.

For Java, Groovy, Kotlin and Android compatibility, see the [full compatibility notes](userguide/compatibility.html).

<!-- Do not add breaking changes or deprecations here! Add them to the upgrade guide instead. -->

<a name="kotlin-dsl-performance"></a>
## Performance improvements

### Kotlin DSL script compilation improvements

This release makes compilation of [Gradle Kotlin DSL](userguide/kotlin_dsl.html) scripts (`*.gradle.kts`) faster, reduces the amount of memory consumed, and introduces compilation avoidance that can eliminate the need to recompile Kotlin build scripts altogether.

On a sample build with 100 subprojects, the cumulative script compilation time goes from [~50 seconds](https://scans.gradle.com/s/3bg67eccnya5i/performance/configuration?showScriptCompilationTimes) down to [~21 seconds](https://scans.gradle.com/s/y7dw5ekes24ag/performance/configuration?showScriptCompilationTimes) with cold caches and cold daemons.
Garbage collection time goes from [2.6 seconds](https://scans.gradle.com/s/3bg67eccnya5i/performance/build#garbage-collection) down to [1.3 seconds](https://scans.gradle.com/s/y7dw5ekes24ag/performance/build#garbage-collection). 
This improvement also reduces memory pressure.
On top of that, a non-ABI change can [eliminate build script recompilation altogether now](https://scans.gradle.com/s/exxa2y22shld6/performance/configuration#summary-script-compile), saving those 21 seconds.

<img src="data:image/png;base64,[encoded data, 22220 characters]" alt="Gradle Kotlin DSL script compilation performance improvements"/> 

Until now, any change to build logic in [buildSrc](userguide/organizing_gradle_projects.html#sec:build_sources) required all of the build scripts to be recompiled.
This release introduces compilation avoidance for [Gradle Kotlin DSL](userguide/kotlin_dsl.html) scripts.

Compilation avoidance will cause Gradle to only recompile build scripts when a change to shared build logic impacts the
ABI (application binary interface) of the classpath of the build script.
Changes to private implementation details of build logic, such as private methods or classes,
bodies of non-private methods or classes, as well as internal changes to [precompiled script plugins](userguide/custom_plugins.html#sec:precompiled_plugins),
will no longer trigger recompilation of the project's build scripts.

Compilation avoidance also applies to changes in any JAR on the build script's classpath.
That includes JARs added by plugins define in included builds and JARs added directly via the `buildscript {}` block.

While the impact on your build may vary, most builds can expect a noticeably shorter feedback loop when editing Kotlin DSL build logic.

**Note**: Kotlin's public [inline functions](https://kotlinlang.org/docs/reference/inline-functions.html#inline-functions) are not supported with compilation avoidance. 
If such functions appear in the public API of a JAR on the buildscript's classpath, changes to classes in that JAR will cause Gradle to fallback to its old behavior.
For example, if `buildSrc` contains a class with a public inline function, then any change to a class in `buildSrc` will cause all build scripts to be recompiled.

### More cache hits for tasks with runtime classpaths

For [up-to-date checks](userguide/more_about_tasks.html#sec:up_to_date_checks) and the [build cache](userguide/build_cache.html), Gradle needs to determine if two task input properties have the same value. 
In order to do so, Gradle first [normalizes](userguide/more_about_tasks.html#sec:configure_input_normalization) both inputs and then compares the result.

Runtime classpath analysis now smartly inspects all properties files, ignoring changes to comments, whitespace, and differences in property order.  Moreover, you can selectively ignore properties that don't impact the runtime classpath.

```
normalization {
    properties('**/build-info.properties') {
        ignoreProperty('timestamp')
    }
}
```

This improves the likelihood of up-to-date and build cache hits when a properties file on the classpath is regenerated or only differs by unimportant values.

See [the user manual](userguide/more_about_tasks.html#sec:property_file_normalization) for further information.

### More cache hits when empty directories are present

For [up-to-date checks](userguide/more_about_tasks.html#sec:up_to_date_checks) and the [build cache](userguide/build_cache.html), Gradle needs to determine if two directory structures contain the same contents.  When a directory contains an empty directory, it is considered to have different contents than an identical directory where the empty directory does not exist.

This may not always be desirable. There are many cases where only the files in a directory structure may be significant, and an empty directory will have no impact on the outputs of a task. In such cases, re-executing the task because an empty directory exists is unnecessary as it will only produce the same outputs.

A new annotation has been introduced to address this scenario. Inputs annotated with [@InputFiles](javadoc/org/gradle/api/tasks/InputFiles.html) or [@InputDirectory](javadoc/org/gradle/api/tasks/InputDirectory.html) can additionally be annotated with [@IgnoreEmptyDirectories](javadoc/org/gradle/api/tasks/IgnoreEmptyDirectories.html) to specify that directories should not be considered during build cache and up-to-date checks.
For inputs annotated in this way, only changes to files (including the file path) will be treated as differences in the input values.

```
class MyTask extends DefaultTask {
    @InputFiles
    @PathSensitive(@PathSensitivity.RELATIVE)
    @IgnoreEmptyDirectories
    FileCollection inputFiles;
}
```

Similarly, there is a corresponding runtime API equivalent:

```
tasks.register("myTask") {
    ext.inputFiles = files()
    inputs.files(inputFiles)
          .withPropertyName('inputFiles')
          .withPathSensitivity(PathSensitivity.RELATIVE)
          .ignoreEmptyDirectories()
}
```

[SourceTask](javadoc/org/gradle/api/tasks/SourceTask.html), [JavaCompile](javadoc/org/gradle/api/tasks/compile/JavaCompile.html), [GroovyCompile](javadoc/org/gradle/api/tasks/compile/GroovyCompile.html), and [AntlrTask](javadoc/org/gradle/api/plugins/antlr/AntlrTask.html) have all been updated to now ignore empty directories when doing up-to-date checks and build cache key calculations.

See [the user manual](userguide/more_about_tasks.html#sec:up_to_date_checks) for more information.

<a name="configuration-cache"></a>
### Configuration cache improvements

The [configuration cache](userguide/configuration_cache.html) improves build performance by caching the result of the configuration phase. Using the configuration cache, Gradle can skip the configuration phase entirely when nothing that affects the build configuration has changed.

Read about [this feature and its impact](https://blog.gradle.org/introducing-configuration-caching) on the Gradle blog. You can also track progress of configuration cache support in [core plugins](https://github.com/gradle/gradle/issues/13454) and [community plugins](https://github.com/gradle/gradle/issues/13490).

#### Support for composite builds

Starting with this release, [composite builds](userguide/composite_builds.html) are fully supported with the configuration cache.

#### More supported core plugins

In this release all core code analysis plugins received full support for the configuration cache:

* [`checkstyle`](userguide/checkstyle_plugin.html)
* [`pmd`](userguide/pmd_plugin.html)
* [`codenarc`](userguide/codenarc_plugin.html)
* [`jacoco`](userguide/jacoco_plugin.html)

See the [matrix of supported core plugins](userguide/configuration_cache.html#config_cache:plugins:core) in the user manual.

<a name="java-toolchain-improvements"></a>
## Java toolchain improvements 

[Java toolchain support](userguide/toolchains.html) provides an easy way to declare what Java version the project should be built with. 
By default, Gradle will [auto-detect installed JDKs](userguide/toolchains.html#sec:auto_detection) that can be used as toolchain.

With this release, toolchain support has been added to the Groovy compile task along with the following improvements.

### Selecting toolchain by vendor and implementation

In case your build has specific requirements from the used JRE/JDK, you may want to define the vendor for the toolchain as well.
`JvmVendorSpec` has a list of well-known JVM vendors recognized by Gradle. 

```
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
        vendor = JvmVendorSpec.ADOPTOPENJDK

        // alternativly, use custom matching
        // vendor = JvmVendorSpec.matching("customString")
    }
}
```

If the vendor is not enough to select the appropriate toolchain, you may as well filter by the implementation of the virtual machine.
For example, to use an [Open J9](https://www.eclipse.org/openj9/) JVM, distributed via [AdoptOpenJDK](https://adoptopenjdk.net/), you can filter by the implementation as shown in the example below. 

```
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
        vendor = JvmVendorSpec.ADOPTOPENJDK
        implementation = JvmImplementation.J9
    }
}
```

Please refer to [the documentation](userguide/toolchains.html#using_toolchains_by_specific_vendors) for more detailed information.

### Viewing all available toolchains

In order to see which toolchains got detected and their corresponding metadata, Gradle 6.8 now provides some insight with the `javaToolchains` task.

Output of `gradle -q javaToolchains`:
```
 + Options
     | Auto-detection:     Enabled
     | Auto-download:      Enabled

 + AdoptOpenJDK 1.8.0_242
     | Location:           /path/to/8.0.242.hs-adpt/jre
     | Language Version:   8
     | Vendor:             AdoptOpenJDK
     | Is JDK:             true
     | Detected by:        SDKMAN!

 + OpenJDK 15-ea
     | Location:           /path/to/java/15.ea.21-open
     | Language Version:   15
     | Vendor:             AdoptOpenJDK
     | Is JDK:             true
     | Detected by:        SDKMAN!

 + Oracle JDK 1.7.0_80
     | Location:           /Library/Java/jdk1.7.0_80.jdk/jre
     | Language Version:   7
     | Vendor:             Oracle
     | Is JDK:             true
     | Detected by:        macOS java_home
```

This can help to debug which toolchains are available to the build and if the expected toolchain got detected or [requires manual setup](userguide/toolchains.html#sec:custom_loc).
See the [toolchain documentation](userguide/toolchains.html) for more in-depth information on toolchain detection and usage.

<a name="composite-builds"></a>
## Composite builds improvements

[Composite builds](userguide/composite_builds.html) are a way of combining separate Gradle builds into a single build. Each build can have a separate purpose (build logic, backend code, frontend code) and can be worked on independently. 

### Tasks can be executed for included builds

Gradle now allows users to execute tasks from included builds directly from the command line. For example, if your build includes `my-other-project` as an included build and it has a subproject `sub` with a task `foo`, then you can execute `foo` with the following command:

    gradle :my-other-project:sub:foo

Note, unlike a multi-project build, running `gradle build` will _not_ run the `build` task in all of the included builds.
You could introduce [task dependencies](userguide/composite_builds.html#included_build_task_dependencies) to [lifecycle tasks](userguide/more_about_tasks.html#sec:lifecycle_tasks) in included builds if you wanted to recreate this behavior for included builds.

IDE support for executing tasks from included builds may not yet fully work depending on the IDE.
Updates for IntelliJ IDEA and Eclipse Buildship are planned to support this fully. 
Today, in IntelliJ IDEA, you can create a [Gradle run configuration](https://www.jetbrains.com/help/idea/create-run-debug-configuration-gradle-tasks.html) to execute a task directly (like you would on the command line).

### Desired cycles between builds are now fully supported

There are cases, where a cycle between included builds are desired.
For example, if two builds contain end-to-end tests that require the production code of both builds.
Such setups are possible with subprojects of a single build, but were not fully supported between projects of different builds.
With this release, this is possible and Gradle will only fail if there is a cycle between _tasks_.
Issues with importing such builds in IDEs are also fixed. 

### New documentation for composite builds and structuring software projects

Gradle's documentation now contains a [sample](samples/sample_structuring_software_projects.html) for structuring software projects with composite builds and a new a chapter on [structuring software projects](userguide/structuring_software_products.html) using composite builds.

<a name="dm-features"></a>
## Dependency management improvements

### Consistent dependency resolution

Dependency resolution in Gradle happens a lot during a build.
From the classpath to compile code or run tests, to the tools used for static analysis, they all resolve a configuration to a set of dependencies at some point.

However, these resolutions happen in isolation.
Sometimes, the dependencies resolved for the runtime classpath have different versions than the dependencies resolved for the compile classpath.
This typically happens when a transitive dependency that is only present at runtime brings in a higher version of a first level dependency.
Similarly, the runtime classpath of tests could use different versions than the compile classpath of production code.

To mitigate this problem, Gradle now lets you declare consistency between dependency configurations.
For example, in the Java ecosystem, you can write:

```
java {
    consistentResolution {
        useCompileClasspathVersions()
    }
}
```

This tells Gradle that the common dependencies between the runtime classpath and the compile classpath should be aligned to the versions used at compile time.

There are many options to configure this feature, including using it outside of the Java ecosystem, which are described in the [user manual](userguide/resolution_strategy_tuning.html#resolution_consistency).

### Central declaration of repositories

In previous Gradle versions, repositories used for dependency resolution had to be declared for every (sub)project individually.
However, in most cases, the same repositories should be used in every project.

In Gradle 6.8, repositories can now conveniently be defined for the whole build in `settings.gradle(.kts)`:

```
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}
```

This allows Gradle to ensure that you use the same repositories for resolving dependencies in all projects of the build.
Learn more by reading how to [declare repositories for the whole build](userguide/declaring_repositories.html#sub:centralized-repository-declaration).

### Central declaration of component metadata rules

[Component metadata rules](userguide/component_metadata_rules.html) are a powerful tool to fix bad metadata published on remote repositories.
However, similarly to repositories, rules traditionally had to be applied on each project.
Starting from this release, it is possible to declare component metadata rules in a central place in `settings.gradle(.kts)`:

```
dependencyResolutionManagement {
    components {
        withModule('com.google.guava:guava', GuavaRule)
    }
}
```

You can learn more about declaring rules globally in the [user manual](userguide/component_metadata_rules.html#sec:rules_in_settings).

### Locking of Gradle settings dependencies

[Dependency locking](userguide/dependency_locking.html) makes builds using dynamic versions deterministic.

So far you could lock dependency configurations from your project or from the project buildscript classpath.
This release adds support to lock configurations from the [Gradle `settings.gradle(.kts)`](userguide/build_lifecycle.html#sec:settings_file):

```
buildscript {
    configurations.classpath {
        resolutionStrategy.activateDependencyLocking()
    }
}
```

See the documentation for more details on [locking settings configurations](userguide/dependency_locking.html#locking_settings_classpath_configuration).

<a name="other-improvements"></a>
## Other improvements

### Test re-run JUnit XML reporting enhancements

The `Test` task, used for executing JVM tests, reports test results as HTML and as a set of XML files in the “JUnit XML” pseudo standard.
It is common for CI servers and other tooling to observe test results via the XML files.
A new `mergeReruns` option has been added that changes how tests that are executed more than once are reported in the XML files.

```
test {
    reports.junitXml.mergeReruns = true
}
```

When this new option is enabled, if a test fails but is then retried and succeeds, its failures will be recorded as `<flakyFailure>` instead of `<failure>`, within one `<testcase>`.
This is the same as the reporting produced by the [surefire plugin of Apache Maven™](https://maven.apache.org/components/surefire/maven-surefire-plugin/examples/rerun-failing-tests.html), when enabling reruns.
If your CI server understands this format, it will indicate that the test was flaky.

This option is disabled by default, causing each test execution to be listed as a separate `<testcase>` in the XML.
This means that when a test is executed multiple times, due to a retry-on-failure mechanism for example, it is listed multiple times.
This is also the behavior for all previous Gradle versions.

If you are using [build scans](https://scans.gradle.com) or [Gradle Enterprise](https://gradle.com/gradle-enterprise-solution-overview/failure-analytics/), flaky tests will be detected regardless of this setting.

Learn more about this new feature in the [Java testing documentation](userguide/java_testing.html#communicating_test_results_to_CI_servers_and_other_tools_via_xml_files).

### `@Inject` is an implicit import

When using [dependency injection](userguide/custom_gradle_types.html#service_injection) when developing plugins, tasks or project extensions, it is now possible to use the `@Inject` annotation without explicitly importing it into your build scripts the
same way it works for other Gradle API classes.

### Importing projects with custom source sets into Eclipse

This version of Gradle fixes problems with projects that use custom source sets, like additional functional test source sets.

Custom source sets are now imported into Eclipse automatically and no longer require manual configuration in the build.

This does not require a separate upgrade to Eclipse Buildship.

<a name="security-tls"></a>
## Security improvements

### Outdated TLS versions are no longer enabled by default

This version of Gradle removes TLS protocols v1.0 and v1.1 from the default list of allowed protocols. Gradle will no longer fallback to TLS v1.0 or v1.1 by default when resolving dependencies. Only TLS v1.2 or TLS v1.3 are allowed by default.

These TLS versions can be re-enabled by manually specifying the system property `https.protocols` with
a comma separated list of protocols required by your build.

The vast majority of builds should not need to change in any way. [Maven Central](https://central.sonatype.org/articles/2018/May/04/discontinued-support-for-tlsv11-and-below/) and [JCenter/Bintray](https://jfrog.com/knowledge-base/why-am-i-failing-to-work-with-jfrog-cloud-services-with-tls-1-0-1-1/) dropped support for TLS v1.0 and TLS v1.1 in 2018. Java has had TLS v1.2 available since Java 7. Disabling these protocols in Gradle protects builds from downgrade attacks.

Depending on the version of Java you use, Gradle will negotiate TLS v1.2 or TLS v1.3 when communicating with remote repositories.

**Note**: Early versions of JDK 11 & JDK 12 contained [race condition bug in the `TLSv1.3` handling logic](https://bugs.openjdk.java.net/browse/JDK-8213202)
which causes the exception `javax.net.ssl.SSLException: No PSK available. Unable to resume`. If you run into this issue,
we recommend updating to the latest minor JDK version.

## Fixed issues

## Known issues

Known issues are problems that were discovered post release that are directly related to changes made in this release.

## External contributions

We love getting contributions from the Gradle community. For information on contributing, please see [gradle.org/contribute](https://gradle.org/contribute).

## Reporting Problems

If you find a problem with this release, please file a bug on [GitHub Issues](https://github.com/gradle/gradle/issues) adhering to our issue guidelines.
If you're not sure you're encountering a bug, please use the [forum](https://discuss.gradle.org/c/help-discuss).

We hope you will build happiness with Gradle, and we look forward to your feedback via [Twitter](https://twitter.com/gradle) or on [GitHub](https://github.com/gradle).
