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

This release continues on the series of performance improvements, particularly for incremental builds.
File system watching introduced in Gradle 6.5 is [now ready for production use](#file-system-watching).
You can expect up to 20% build speed improvements in large projects after turning this feature on.
Additionally, the experimental [configuration cache](#configuration-cache) has been improved to make troubleshooting easier for early adopters.

This release introduces [Java toolchain support](#jvm-toolchains) that makes it much easier to build JVM projects using a different version of Java than the one Gradle is running on.
Starting with this release, Gradle itself can also run on [Java 15](#java-15).

New dependency management features in this release include support for [compile only API dependencies](#compile-only-api),
the ability to [ignore selected dependencies in dependency locking](#dependency-locking)
and [version ranges in repository content filtering](#repository-content-filtering).

This release also includes several general improvements including improved [`gradle init` task](#gradle-init),
[better documentation](#multi-project-docs)
and [new samples](#new-samples).

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

[Roberto Perez Alcolea](https://github.com/rpalcolea),
[SheliakLyr](https://github.com/SheliakLyr),
[Christian Edward Gruber](https://github.com/cgruber),
[René Gröschke](https://github.com/breskeby),
[Louis CAD](https://github.com/LouisCAD),
[Campbell Jones](https://github.com/serebit),
[Leonardo Bezerra Silva Júnior](https://github.com/leonardobsjr),
[Christoph Dreis](https://github.com/dreis2211),
[Matthias Robbers](https://github.com/MatthiasRobbers),
[Vladimir Sitnikov](https://github.com/vlsi),
[Stefan Oehme](https://github.com/oehme),
[Thad House](https://github.com/ThadHouse),
[Michał Mlak](https://github.com/Miehau)
and [Jochen Schalanda](https://github.com/joschi).

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

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

## Performance improvements

<a name="file-system-watching"></a>
### File system watching is ready for production use

In an [incremental build](userguide/more_about_tasks.html#sec:up_to_date_checks), input and output files are checked to determine what needs to be rebuilt.
This feature typically saves a lot of time; however, it adds some I/O overhead, which can be noticeable in large projects when not much has changed since the previous build.

Back in Gradle 6.5 we've introduced _[file-system watching](userguide/gradle_daemon.html#sec:daemon_watch_fs)_ as an experimental feature.
When enabled, it allows Gradle to keep what it has learned about the file system in memory during and between builds instead of polling the file system on each build.
This significantly reduces the amount of disk I/O needed to determine what has changed since the previous build.

This feature is now ready for production use and supported on Linux, Windows and macOS.
You can enable it by adding the following to `gradle.properties` in the project root or in your Gradle user home:

```
org.gradle.vfs.watch=true
```

Read more about this new feature and its impact [on the Gradle blog](https://blog.gradle.org/introducing-file-system-watching)!

<img src="data:image/png;base64,[encoded data, 16188 characters]" alt="Build time improvements using Santa Tracker Android with file-system watching enabled, Linux with OpenJDK 8."/>

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

Gradle 6.6 introduced [configuration caching](userguide/configuration_cache.html) as an experimental feature.
This release comes with usability and performance improvements for the configuration cache.

Early adopters of configuration cache can use the command line output and HTML report for [troubleshooting](userguide/configuration_cache.html#config_cache:troubleshooting).
Previously, the configuration cache state was saved despite reported problems, which in some situations required manual cache invalidation.
In this release, the configuration cache gets discarded when the build fails because of configuration cache problems.
Note that you can still [ignore](userguide/configuration_cache.html#config_cache:usage:ignore_problems) known problems.

The problem report is also more helpful now.
It reports the source of problems more accurately, pointing at the offending location in plugins and scripts in more cases.

Loading from the configuration cache is also faster and memory consumption during builds has been reduced, especially for Kotlin and Android builds.

Read about this feature and its impact [on the Gradle blog](https://blog.gradle.org/introducing-configuration-caching). 
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).

## New JVM ecosystem features

<a name="jvm-toolchains"></a>
### Toolchain support for JVM projects

By default, Gradle uses the same Java version for running Gradle itself and building JVM projects.

This is not always desirable.
Building projects with different Java versions on different developer machines and CI servers may lead to unexpected issues.
Additionally, you may want to build a project using a Java version that running Gradle is not compatible with.

Before this release, it required [several steps](https://docs.gradle.org/6.6.1/userguide/building_java_projects.html#compiling_and_testing_java_67) to configure a different Java version for compilation, testing, generating Javadoc, and executing applications.

This release introduces the toolchain concept to simplify such a setup.
A Java toolchain is a set of tools (`javac` compiler,`java` command etc), taken from a local Java installation and used during the build.
Instead of manually specifying executables for the various tasks, toolchains provide a centralized place to define the Java version requirements in the build.

Setting up a toolchain can be done through the `java` extensions:

```
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(14)
    }
}
```

The snippet above makes Gradle use `javac`, `java` and `javadoc` commands from the specified toolchain for compilation, running tests, and generating documentation.
Gradle will detect locally installed Java versions to run the build according to the specified requirements.

By default, Gradle supports common installation locations on various operating systems as well as popular package managers like asdf-vm, jabba and SDKMAN!.
If no matching Java version is available locally, it will download a matching JDK from AdoptOpenJDK.

<img src="data:image/png;base64,[encoded data, 118724 characters]" alt="Java Toolchain Download" />

Learn more about this new feature in the [Java Toolchain documentation](userguide/toolchains.html) and the [toolchain sample](samples/sample_jvm_multi_project_with_toolchains.html).

<a name="java-15"></a>
### Support for Java 15

Gradle now supports running on and building with [Java 15](https://openjdk.java.net/projects/jdk/15/). 

## New dependency management features

<a name="compile-only-api"></a>
### Compile-only API dependencies for JVM libraries

When writing a Java (or Groovy/Kotlin/Scala) library, there are cases where you require dependencies at compilation time which are parts of the API of your library, but which should not be on the runtime classpath.

An example of such a dependency is an annotation library with annotations that are not used at runtime.
These typically need to be available at compile time of the library's consumers when annotation processors inspect annotations of all classes.
Another example is a dependency that is part of the runtime environment the library is expected to run on, but also provides types that are used in the public API of the library.

The [Java Library Plugin](userguide/java_library_plugin.html#sec:java_library_configurations_graph) now offers the _compileOnlyApi_ configuration for this purpose.
It effectively combines the major properties of the _compileOnly_ configuration (dependency will _not_ be on the runtime classpath) and the api (dependencies are visible for consumers at compile time).

```
plugins {
  id("java-library")
  // add Groovy, Kotlin or Scala plugin if desired
}

dependencies {
  compileOnlyApi(
    "com.google.errorprone:error_prone_annotations:2.4.0")
}
```

The behavior of `compileOnlyApi` dependencies is preserved for published libraries when published with [Gradle Module Metadata](userguide/publishing_gradle_module_metadata.html#).

<a name="dependency-locking"></a>
### Ignore dependencies in dependency lock state

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

When using dependency locking, you may want to use a different frequency of version upgrades for different types of dependencies.
For example, you may want to explicitly control external dependencies upgrades with locking but use the latest version for internal dependencies on every build. 

To enable such use case, this release allows you to specify ignored dependencies in the `dependencyLocking` extension:

```
dependencyLocking {
    ignoredDependencies.add("com.example:*")
}
```

With the above, any dependency in the `com.example` group will be ignored by the lock state validation or writing.
This means that the dependencies in this group will be automatically updated without updating the lock file. 

See the documentation for more details on [ignored dependencies in locking](userguide/dependency_locking.html#ignoring_dependencies).

<a name="repository-content-filtering"></a>
### Version ranges in repository content filtering

Builds can control which repositories are queried for which dependency for better performance and security using [repository content filtering](userguide/declaring_repositories.html#sec:repository-content-filtering).
This feature provides performance and security benefits.

With this release, when including or excluding a specific dependency version, the build author can use a version range:

```
repositories {
    maven {
        url = 'http://some-url'
        content {
             excludeVersion('com.google.guava', 'guava', '[19.0,)')
       }
    }
}
```

In this case, no `guava` version after `19.0` will be searched for in the referenced Maven repository.

## Other new features and usability improvements 

<a name="kebab-case"></a>
### Abbreviation of kebab-case project names

Gradle allows you to [abbreviate project and task names from the command-line](userguide/command_line_interface.html#sec:name_abbreviation).
For example, you can execute the task `compileTestJava` by running `gradle cTJ`.

Up until this release, fuzzy name matching only worked for camelCase names (e.g. `compileTestJava`).
This is the recommended convention for task names, but it is unusual for project names.
In the Java world, directory names are usually all lowercase by convention and in Gradle, project names usually follow the name of the directory the project is in.

Many projects worked around this limitation by using kebab-case project directories (e.g. `my-awesome-lib`) while defining different camelCase project names in their settings scripts.
This allowed them to use project name abbreviations in the command line but added additional complexity to the build.

This release changes the fuzzy name matching to support for kebab-case names.
Now, you can execute the `compileTestJava` task in the project `my-awesome-lib` with the following command:

```
gradle mAL:cT
```

<a name="gradle-init"></a>
### Bootstrapping new projects with `gradle init` 

The built-in [`init` task](userguide/build_init_plugin.html) can be used to quickly create a new Gradle build or convert a Maven build to a Gradle build.

In this release, the projects generated by `gradle init` have been updated to use the latest recommended build authoring practices.
Some of the generated builds demonstrate the use of `buildSrc` for sharing common build logic.

For new projects, you can now generate a multi-project build for JVM languages.
In order to generate a multi-project build, choose `application`, select one of the JVM languages and then choose `application and library projects`:

```
Select type of project to generate:
  1: basic
  2: application
  3: library
  4: Gradle plugin
Enter selection (default: basic) [1..4] 2

Select implementation language:
  1: C++
  2: Groovy
  3: Java
  4: Kotlin
  5: Scala
  6: Swift
Enter selection (default: Java) [1..6] 3

Split functionality across multiple subprojects?:
   1: no - only one application project
   2: yes - application and library projects
Enter selection [1..2] 2
```  

For [Maven-to-Gradle conversion](userguide/migrating_from_maven.html), this release adds support for generating Kotlin DSL scripts.

<a name="build-src"></a>
### Included builds are now visible to buildSrc

We recommend that builds use the specially named [buildSrc](userguide/organizing_gradle_projects.html#sec:build_sources) build to organize imperative and common build logic. 

Sometimes, you may also need to share build logic between `buildSrc` itself and your root build.
In the previous releases, that was not possible because `buildSrc` could not access build logic from other included builds. 

In this release, it's now possible to share build logic between buildSrc and the root build or any other included build.
This makes it easier to share common repository declarations or conventions between buildSrc and other builds as demonstrated in [this sample](samples/sample_sharing_convention_plugins_with_build_logic.html).

**NOTE** Using a plugin from an included build with buildSrc will break importing your build into Android Studio and IntelliJ until a fix for [IDEA-250774](https://youtrack.jetbrains.com/issue/IDEA-250774) has been released. 

## Documentation improvements

<a name="new-samples"></a>
### New samples

The [sample index](samples/index.html) includes new samples, with step-by-step instructions on how to get started with Gradle for different project types and programming languages:

- Building an application with libraries:
[Java](samples/sample_building_java_applications_multi_project.html),
[Groovy](samples/sample_building_groovy_applications_multi_project.html),
[Scala](samples/sample_building_scala_applications_multi_project.html),
[Kotlin](samples/sample_building_kotlin_applications_multi_project.html)
- Building a simple application:
[Java](samples/sample_building_java_applications.html),
[Groovy](samples/sample_building_groovy_applications.html),
[Scala](samples/sample_building_scala_applications.html),
[Kotlin](samples/sample_building_kotlin_applications.html),
[C++](samples/sample_building_cpp_applications.html),
[Swift](samples/sample_building_swift_applications.html)
- Building a single library:
[Java](samples/sample_building_java_libraries.html),
[Groovy](samples/sample_building_groovy_libraries.html),
[Scala](samples/sample_building_scala_libraries.html),
[Kotlin](samples/sample_building_kotlin_libraries.html),
[C++](samples/sample_building_cpp_libraries.html),
[Swift](samples/sample_building_swift_libraries.html)

<a name="multi-project-docs"></a>
### Authoring multi-project builds 

We've reworked our documentation for [authoring multi-project builds](userguide/multi_project_builds.html) that now includes the 
[new guidance on how to share build logic between subprojects](userguide/sharing_build_logic_between_subprojects.html#sec:convention_plugins)
with [convention plugins](samples/sample_convention_plugins.html).

## Promoted features
Promoted features are features that were incubating in previous versions of Gradle but are now supported and subject to backwards compatibility.
See the User Manual section on the “[Feature Lifecycle](userguide/feature_lifecycle.html)” for more information.

* [File system watching is now stable](#file-system-watching-is-ready-for-production-use)

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