Gradle 7.3发布

升级说明

通过更新包装将构建更改为使用 Gradle 7.3：

./gradlew wrapper --gradle-version=7.3

请参阅Gradle 7.x 升级指南，了解升级到 Gradle 7.3 时的弃用、中断更改和其他考虑。

对于 Java、Groovy、科特林和安卓兼容性，请参阅完整的兼容性注释。

新功能和可用性改进

支持 Java 17

格拉德尔现在支持运行和建设与爪哇17。

在以前的格拉德尔版本中，在 Java 17 上运行 Gradle 本身会导致错误。JVM项目可以使用工具链与Java 17一起建造。

截至Gradle 7.3，无论是运行格拉德尔本身和建设JVM项目与Java 17是全力支持。

JVM 项目中的声明性测试套件

在测试 Java & JVM 项目时，您通常需要将测试类组一起组织成可管理的块，以便您可以以不同的频率或在构建管道中的不同点运行它们。例如，您可能需要定义单元测试、集成测试和功能测试组。

以前，分组测试正确地要求全面了解如何修改和连接 Gradle 中的不同域对象，如源集、配置和任务。如果您想将测试分为不同的组，您需要了解这些单独的部分如何相互交互。

使用Gradle 7.3，JVM测试套件插件简化了此类测试组的创建。我们称这些组为测试套件。请注意，这不能与测试框架套件混淆，如JUnit4 的套件。

测试套件是一个高级概念，可在构建脚本中直接和一致地引用。您可以配置测试使用的依赖关系、源和测试框架，而不必担心低级详细信息。

例如，您可以创建一个集成测试，通过在 Java 项目中添加以下片段来测试套件：

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 plugin. The built-in task has been re-implemented on top of test suites. See more in the user manual.javatest

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 when generating a new project.gradle init --incubating

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 , and other restricted keywords. With this release these restrictions are now lifted. Check the documentation for details.pluginversion

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 instead of being forced to use in the type unsafe API.groovy-jsongroovy.json

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 and plugins, both can be used in the block.kotlin.jskotlin.js.actionplugins

Declarations of dependencies with , , and support all accessor types.platformenforcedPlatformtestFixturesforce

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.

In some rare environments these events can be unreliable, and would cause Gradle to ignore some changes. To prevent this, Gradle now verifies that file system events are delivered in a timely fashion before enabling optimization based on them.

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 tasks that forces Gradle to ignore content in the destination directory.Copy

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:

• The input or output locations contain unreadable files like pipes where Gradle cannot track the content.
• The input or output is stored remotely, for example in a database, and its state cannot be tracked.
• Another tool like Git already takes care of keeping the state, so it doesn’t make sense for Gradle to do additional bookkeeping.
• The build does not own the output location exclusively and Gradle would need to track the state of a potentially large amount of content.

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.

@UntrackedTask and are a replacement for if you want your task to never be up-to-date. It has the advantage that it is faster since still spends time on capturing task state.Task.doNotTrackStateTask.outputs.upToDateWhen { false }Task.outputs.upToDateWhen { false }

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 and bundled libraries have been updated to resolve reported vulnerabilities. Head over to the upgrade guide for version and resolved vulnerabilities.antcommon-compress

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.

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

61 issues have been fixed in Gradle 7.3.

• [#18660] – Move Untracked annotation to task level
• [#18635] – Improve error message when –project-cache-dir is used together with –watch-fs
• [#18632] – Test Suite cannot add version catalog item
• [#18626] – 7.3-rc-1 –project-cache-dir incompatible with org.gradle.vfs.watch=true
• [#18622] – SourceSet with name ‘test’ not found in KMP
• [#18606] – 7.3-rc-1: Incubating test suite changes breaks existing build
• [#18598] – Fix minor JvmTestSuitePlugin docs formatting issue
• [#9095] – Disable caching and up-to-date checks completely for task
• [#18840] – [Regression] Incremental annotation processor fails with “Attempt to recreate a file for type”
• [#18559] – Regression in Intellij Idea integration for Scala 3
• [#18506] – Support for Scaladoc with Scala 3
• [#18465] – JDK17 + JUnit broken test scanning
• [#18460] – Gradle 7.3 snapshot: dependencies task fails with “Build output cleanup registry has already been finalized – cannot register more outputs”
• [#18454] – Document the danger of publishing a library with a dependency on an enforcedPlatform
• [#18412] – Configuration cache corrupted: NonSerializableMemoizingSupplier, DefaultJvmInstallationMetadata, JavaToolchain
• [#18388] – Implement JvmTestSuite#useTestNG
• [#18387] – Add javadoc for JvmTestSuite#useSpock and #useKotlinTest
• [#18381] – Investigate possible breakage with test suite classpath
• [#18324] – gradle depends on an insecure third-party JAR package that contains the CVE vulnerability
• [#18294] – VFS couldn’t add watch, error = 2
• [#18269] – Make DisableCachingByDefault non-incubating
• [#18243] – Update existing test coverage to use new test suite API
• [#18241] – Add documentation to user manual for test suite API
• [#18239] – Support TestNG and Spock as a testing framework options
• [#18238] – Update build init to provide opt-in to best practices based on incubating APIs
• [#18229] – Allow version catalog sub-accessors for platform, enforcedPlatform, test-fixtures and variantOf
• [#18228] – Ignore empty directories on Java sourcepath compile option
• [#18211] – Scala plugin doesn’t pick jvm-target from java targetCompatability / toolchain
• [#18198] – Configuration Cache: ClassNotFoundException when reusing cache for java-gradle-plugin project
• [#18167] – In version catalog libs, alias ‘jme3-plugins’ is not a valid alias — Works in 7.1.1, fails in 7.2
• [#18161] – Add more tests for untracked properties
• [#18160] – Document untracked task properties
• [#18159] – Allow Copy tasks to mark their output as untracked
• [#18142] – Version Catalog: Sub-accessors and alias overload not supported for plugins.
• [#18115] – Cannot import project using Gradle 7.3 snapshot into IntelliJ
• [#18079] – Dependency resolution fails with ‘Corrupt serialized resolution result’
• [#18068] – Allow declaring untracked task properties
• [#18064] – Configuration cache issue with :pluginUnderTestMetadata when java-gradle-plugin has project dependency
• [#18002] – Please document Kotlin language compatibility with Gradle Build tool versions.
• [#17986] – Version catalog should allow users to configure libraries with plugin suffix
• [#17974] – Documentation: Incorrect instructions to increase inotify limits
• [#17964] – The exclude won’t be able to exclude rewritten dependency
• [#17882] – Make MinimalExternalModuleDependency#toString work
• [#17849] – Provide override for enforcedPlatform(Provider<MinimalExternalModuleDependency>) similar to platform
• [#17829] – Inconsistent task selector behavior in multi-projects build
• [#17812] – Gradle sometimes deadlocks at the start of task execution
• [#17785] – Ensure `JavaToolchain` API compatibility with the configuration cache
• [#17746] – Performance regression for multi-stage incremental annotation processors
• [#17563] – Configuration Cache fails to load after Dynamic Version TTL expires.
• [#17415] – providedRuntime is added to compileClasspath when using the war plugin
• [#17039] – Deprecation Warning Appears after Upgrading to Gradle 7.0
• [#16857] – Support JDK 17
• [#16527] – Support for Scala3
• [#13706] – Configuration cache should capture input normalization
• [#12232] – Endless creation of crashing daemons after upgrading to 6.0.1 or 6.1.1
• [#11587] – Gradle should not add non-existing paths to class paths
• [#9903] – Proper incremental Java/Groovy joint compilation
• [#7508] – ConcurrentModificationException in AbstractStyledTextOutput
• [#8749|- 对于想法插件， ‘. 添加’ 排除的文件夹不起作用， 只有重新分配工作
• [#18732|- 斯卡拉多克为斯卡拉 3 打破多模块构建
• [#18726|- 与分级 -7.3-rc2 和 java 17 一起构建时，无点例外

已知问题

已知问题与本版本中的更改直接相关，是发布后发现的问题。

目前没有已知的格拉德尔7.3问题。

外部捐款

我们喜欢从格拉德尔社区获得捐款。有关贡献的信息，请参阅gradle.org/contribute。

报告问题

如果您发现此版本有问题，请在遵守我们问题指南的 GitHub 问题上提交错误。如果您不确定自己是否遇到了错误，请使用论坛。

我们希望您能与格雷德尔建立幸福，我们期待着您的反馈通过推特或GitHub。

Upgrade instructions

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

./gradlew wrapper --gradle-version=7.3

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

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.

In some rare environments these events can be unreliable, and would cause Gradle to ignore some changes. To prevent this, Gradle now verifies that file system events are delivered in a timely fashion before enabling optimization based on them.

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:

• The input or output locations contain unreadable files like pipes where Gradle cannot track the content.
• The input or output is stored remotely, for example in a database, and its state cannot be tracked.
• Another tool like Git already takes care of keeping the state, so it doesn’t make sense for Gradle to do additional bookkeeping.
• The build does not own the output location exclusively and Gradle would need to track the state of a potentially large amount of content.

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.

@UntrackedTask and Task.doNotTrackState are a replacement for Task.outputs.upToDateWhen { false } if you want your task to never be up-to-date. It has the advantage that it is faster since Task.outputs.upToDateWhen { false } still spends time on capturing task state.

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

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

61 issues have been fixed in Gradle 7.3.

• [#18660] – Move Untracked annotation to task level
• [#18635] – Improve error message when –project-cache-dir is used together with –watch-fs
• [#18632] – Test Suite cannot add version catalog item
• [#18626] – 7.3-rc-1 –project-cache-dir incompatible with org.gradle.vfs.watch=true
• [#18622] – SourceSet with name ‘test’ not found in KMP
• [#18606] – 7.3-rc-1: Incubating test suite changes breaks existing build
• [#18598] – Fix minor JvmTestSuitePlugin docs formatting issue
• [#9095] – Disable caching and up-to-date checks completely for task
• [#18840] – [Regression] Incremental annotation processor fails with “Attempt to recreate a file for type”
• [#18559] – Regression in Intellij Idea integration for Scala 3
• [#18506] – Support for Scaladoc with Scala 3
• [#18465] – JDK17 + JUnit broken test scanning
• [#18460] – Gradle 7.3 snapshot: dependencies task fails with “Build output cleanup registry has already been finalized – cannot register more outputs”
• [#18454] – Document the danger of publishing a library with a dependency on an enforcedPlatform
• [#18412] – Configuration cache corrupted: NonSerializableMemoizingSupplier, DefaultJvmInstallationMetadata, JavaToolchain
• [#18388] – Implement JvmTestSuite#useTestNG
• [#18387] – Add javadoc for JvmTestSuite#useSpock and #useKotlinTest
• [#18381] – Investigate possible breakage with test suite classpath
• [#18324] – gradle depends on an insecure third-party JAR package that contains the CVE vulnerability
• [#18294] – VFS couldn’t add watch, error = 2
• [#18269] – Make DisableCachingByDefault non-incubating
• [#18243] – Update existing test coverage to use new test suite API
• [#18241] – Add documentation to user manual for test suite API
• [#18239] – Support TestNG and Spock as a testing framework options
• [#18238] – Update build init to provide opt-in to best practices based on incubating APIs
• [#18229] – Allow version catalog sub-accessors for platform, enforcedPlatform, test-fixtures and variantOf
• [#18228] – Ignore empty directories on Java sourcepath compile option
• [#18211] – Scala plugin doesn’t pick jvm-target from java targetCompatability / toolchain
• [#18198] – Configuration Cache: ClassNotFoundException when reusing cache for java-gradle-plugin project
• [#18167] – In version catalog libs, alias ‘jme3-plugins’ is not a valid alias — Works in 7.1.1, fails in 7.2
• [#18161] – Add more tests for untracked properties
• [#18160] – Document untracked task properties
• [#18159] – Allow Copy tasks to mark their output as untracked
• [#18142] – Version Catalog: Sub-accessors and alias overload not supported for plugins.
• [#18115] – Cannot import project using Gradle 7.3 snapshot into IntelliJ
• [#18079] – Dependency resolution fails with ‘Corrupt serialized resolution result’
• [#18068] – Allow declaring untracked task properties
• [#18064] – Configuration cache issue with :pluginUnderTestMetadata when java-gradle-plugin has project dependency
• [#18002] – Please document Kotlin language compatibility with Gradle Build tool versions.
• [#17986] – Version catalog should allow users to configure libraries with plugin suffix
• [#17974] – Documentation: Incorrect instructions to increase inotify limits
• [#17964] – The exclude won’t be able to exclude rewritten dependency
• [#17882] – Make MinimalExternalModuleDependency#toString work
• [#17849] – Provide override for enforcedPlatform(Provider<MinimalExternalModuleDependency>) similar to platform
• [#17829] – Inconsistent task selector behavior in multi-projects build
• [#17812] – Gradle sometimes deadlocks at the start of task execution
• [#17785] – Ensure `JavaToolchain` API compatibility with the configuration cache
• [#17746] – Performance regression for multi-stage incremental annotation processors
• [#17563] – Configuration Cache fails to load after Dynamic Version TTL expires.
• [#17415] – providedRuntime is added to compileClasspath when using the war plugin
• [#17039] – Deprecation Warning Appears after Upgrading to Gradle 7.0
• [#16857] – Support JDK 17
• [#16527] – Support for Scala3
• [#13706] – Configuration cache should capture input normalization
• [#12232] – Endless creation of crashing daemons after upgrading to 6.0.1 or 6.1.1
• [#11587] – Gradle should not add non-existing paths to class paths
• [#9903] – Proper incremental Java/Groovy joint compilation
• [#7508] – ConcurrentModificationException in AbstractStyledTextOutput
• [#8749] – For idea plugin, `.add`ing an excluded folder does not work, only reassignment works
• [#18732] – ScalaDoc for Scala 3 breaks multi-module build
• [#18726] – NullPointerException when building with gradle-7.3-rc2 and java 17

Known issues

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

There are no known issues of Gradle 7.3 at this time.

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.