Gradle Release Notes

Version 7.3-rc-5

The Gradle team is excited to announce Gradle 7.3-rc-5.

This release introduces a declarative test suite API for JVM projects, adds support for building projects with Java 17, and updates the Scala plugin to support Scala 3.

There are also changes to make builds more reliable, provide additional details to IDEs when downloading dependencies, improve untracked files in custom plugins, several bug fixes and more.

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

Attix Zhang, anatawa12, Anil Kumar Myla, Marcono1234, Nicola Corti, Scott Palmer, Marcin Zajączkowski, Alex Landau, Stefan Oehme, yinghao niu, Björn Kautler, Tomasz Godzik, Kristian Kraljic, Matthew Haughton, Raphael Fuchs, Sebastian Schuberth, Roberto Perez Alcolea, Xin Wang

Table Of Contents

Upgrade instructions

Switch your build to use Gradle 7.3-rc-5 by updating your wrapper:

./gradlew wrapper --gradle-version=7.3-rc-5

See the Gradle 7.x upgrade guide to learn about deprecations, breaking changes and other considerations when upgrading to Gradle 7.3-rc-5.

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

New features and usability improvements

Support for Java 17

Gradle now supports running on and building with Java 17.

In previous Gradle versions, running Gradle itself on Java 17 resulted in an error. JVM projects could have been built with Java 17 using toolchains.

As of Gradle 7.3, both running Gradle itself and building JVM projects with Java 17 is fully supported.

Declarative test suites in JVM projects

When testing Java & JVM projects, you often need to group tests classes together to organize them into manageable chunks, so that you can run them with different frequencies or at distinct points in your build pipeline. For example, you may want to define groups of unit tests, integration tests, and functional tests.

Previously, grouping tests correctly required thorough knowledge of how to modify and connect various domain objects in Gradle, like SourceSets, configurations and tasks. If you wanted to divide tests into different groups, you needed to understand how these separate parts interact with one another.

With Gradle 7.3, the JVM Test Suite Plugin simplifies the creation of such groups of tests. We refer to these groups as Test Suites. Note that this is not to be confused with testing framework suites, like JUnit4’s Suite.

Test Suites are a high-level concept which can be referred to directly and consistently in build scripts. You can configure dependencies, sources and the testing framework used by the tests without having to worry about the low-level details.

For example, you can create an integration testing, test suite by adding the following snippet to a Java project:

testing {
    suites {
        // Add a new test suite
        integrationTest(JvmTestSuite) {
            // Use JUnit Jupiter as a testing framework
            useJUnitJupiter('5.7.1')

            // depend on the production code for tests
            dependencies {
                implementation project
            }
        }
    }
}

// Run integration tests as part of check
tasks.named('check') {
    dependsOn(testing.suites.integrationTest)
}

This functionality is available automatically for all JVM-based projects that apply the java plugin. The built-in test task has been re-implemented on top of test suites. See more in the user manual.

This API is incubating and will likely change in future releases as more functionality is added.

Scala 3 support

The Scala plugin allows users to compile their Scala code using Gradle and the Zinc incremental compiler underneath.

The Scala plugin is now able to compile Scala 3 code. All existing configuration options should still be usable with the newest language version.

The newest version of Scala 3 brings about numerous features while keeping compatibility with most of the existing Scala 2 code. To see more about the language features go to overview of the new features in Scala 3.

Explore new behavior with gradle init

When you initialize a new Gradle project using gradle init, Gradle will now ask if you want to try new but unstable features in the build. This will allow you to try out new features before they become stable. You can always ask for this behavior by running gradle init --incubating when generating a new project.

Currently, builds generated with this option will only enable Test Suites, but other new APIs or behaviors may be added as they are introduced.

Version catalog improvements

Version catalog is a feature preview that provides a convenient API for referencing dependencies and their versions. It received the following improvement in this release.

Lifted restrictions for alias names

In previous Gradle releases it was not possible to declare aliases with the suffix plugin, version and other restricted keywords. With this release these restrictions are now lifted. Check the documentation for details.

Version catalog type unsafe API changes

When using the type unsafe API, all methods accepting alias references now can use the exact same string as the alias definition. This means that you can declare and reference groovy-json instead of being forced to use groovy.json in the type unsafe API.

Note that access to the type unsafe API has changed, please see the upgrade guide.

Consistent version catalog accessors support in more scenarios

With more possibilities for declaring aliases, some accessors were not supported in specific APIs related to plugin or dependency declarations. This release fixes those issues and accessors can be used consistently in more contexts.

For plugins, if you have kotlin.js and kotlin.js.action plugins, both can be used in the plugins block.

Declarations of dependencies with platform, enforcedPlatform, testFixtures and force support all accessor types.

Reliability improvements

More robust file system watching

When running an incremental build, Gradle needs to understand what has changed since the previous build on the file system. To do this it relies on the operating system's file system events whenever possible.

However, these file system events can be unreliable in some environments, which could cause Gradle to ignore some changes.

To prevent this, Gradle now detects the reliability of file system events and automatically disables the file system watching optimization in case of issues.

Allow copying single files into directories which contain unreadable files.

Sometimes you want to copy files into a directory that contains unreadable files or into one that is not exclusively owned by the build. For example when you are deploying single files into application servers or installing executables.

Doing so may fail or be slow because Gradle tries to track all the content in the destination directory.

In order to work around such issues, you can now use the method Task.doNotTrackState() on Copy tasks that forces Gradle to ignore content in the destination directory.

See the samples in the user manual about Deploying single files into application servers and Installing executables.

Input normalization support in configuration cache

The input normalization is now correctly tracked by the experimental configuration cache. Task up-to-date checks now consider normalization rules when the configuration cache is enabled, leading to faster builds.

Plugin development improvements

Initializing new plugin projects using the Build Init Plugin can also benefit from the --incubating option.

Allow plugin authors to declare tasks as untracked

For up-to-date checks and the build cache, Gradle needs to track the state of the inputs and outputs of a task. It is not always desirable or possible for Gradle to fully track the state of the input and output files.

For example:

Gradle 7.3 introduces the annotation @UntrackedTask and the method Task.doNotTrackState() to declare that Gradle should not track the state of a task. This allows tasks to implement the above use-cases.

If a task is untracked, then Gradle does not do any optimizations when running the task. For example, such a task will always be out of date and never come from the build cache.

The method Task.doNotTrackState() is a replacement for Task.outputs.upToDateWhen { false } if you want your task to never be up-to-date. It has the advantage that there is no time spent on capturing state that would be discarded anyway.

See the samples in the user manual about Integrating an external tool which does its own up-to-date checking.

Improvements for tooling providers

The Tooling API allows applications to embed Gradle. This API is used by IDEs such as IDEA, Android Studio and Buildship to integrate Gradle into the IDE.

File download progress events

When a build downloads many files or very large files, for example when resolving dependencies, Gradle may appear to be unresponsive due to the lack of any logging or console output.

This release adds new events that notify the IDE as files are downloaded. This allows IDEs to show better progress information while Gradle is running and during IDE import/sync.

Security improvements

Both ant and common-compress bundled libraries have been updated to resolve reported vulnerabilities. Head over to the upgrade guide for version and resolved vulnerabilities.

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.

The following are the features that have been promoted in this Gradle release.

Disabling caching by default

The @DisableCachingByDefault annotation is now a stable feature.

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.