Gradle Release Notes

Upgrade instructions

Switch your build to use Gradle 6.7 by updating your wrapper:

./gradlew wrapper --gradle-version=6.7

See the Gradle 6.x upgrade guide to learn about deprecations, breaking changes and other considerations when upgrading to Gradle 6.7.

For Java, Groovy, Kotlin and Android compatibility, see the full compatibility notes.

Performance improvements

File system watching is ready for production use

In an incremental build, 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 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!

Configuration cache improvements

Gradle 6.6 introduced configuration caching 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. 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 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. You can also track progress of configuration cache support in core plugins and community plugins.

New JVM ecosystem features

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

Learn more about this new feature in the Java Toolchain documentation and the toolchain sample.

Support for Java 15

Gradle now supports running on and building with Java 15.

New dependency management features

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

Ignore dependencies in dependency lock state

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

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

Abbreviation of kebab-case project names

Gradle allows you to abbreviate project and task names from the command-line. 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

Bootstrapping new projects with gradle init

The built-in init task 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, this release adds support for generating Kotlin DSL scripts.

Included builds are now visible to buildSrc

We recommend that builds use the specially named buildSrc 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.

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 has been released.

Documentation improvements

New samples

The sample index 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, Groovy, Scala, Kotlin
• Building a simple application: Java, Groovy, Scala, Kotlin, C++, Swift
• Building a single library: Java, Groovy, Scala, Kotlin, C++, Swift

Authoring multi-project builds

We've reworked our documentation for authoring multi-project builds that now includes the new guidance on how to share build logic between subprojects with convention plugins.

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” for more information.

• File system watching is now stable

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.

Reporting Problems

If you find a problem with this release, please file a bug on GitHub Issues adhering to our issue guidelines. If you're not sure you're encountering a bug, please use the forum.

We hope you will build happiness with Gradle, and we look forward to your feedback via Twitter or on GitHub.