将构建从 Gradle 6.x 升级到 7.0
本章提供了将 Gradle 6.x 构建迁移到 Gradle 7.0 所需的信息。对于从 Gradle 5.x 或更早版本迁移的情况,请先完成 旧的迁移指南。
我们为所有用户推荐以下步骤
-
尝试运行
gradle help --scan
并查看生成的构建扫描中的弃用视图。这是为了让你能够看到适用于你的构建的任何弃用警告。
或者,你可以运行
gradle help --warning-mode=all
以在控制台中查看弃用信息,尽管它可能不会报告那么多详细信息。 -
更新你的插件。
一些插件可能会在新版本的 Gradle 中失效,例如因为它们使用了已被移除或更改的内部 API。上一步将通过在使用插件尝试使用 API 的弃用部分时发出弃用警告来帮助你识别潜在问题。
-
运行
gradle wrapper --gradle-version 7.0
将项目更新到 7.0。 -
尝试运行项目,并使用故障排除指南调试任何错误。
从 6.9 及更早版本升级
IDE 集成的变更
IDEA 模型中的变更
getGeneratedSourceDirectories()
和 getGeneratedTestDirectories()
方法已从 IdeaContentRoot
接口中移除。客户端应将这些调用替换为 getSourceDirectories()
和 getTestDirectories()
,并在返回的实例上使用 isGenerated()
方法。
依赖锁定现在默认为每个项目一个文件
依赖锁定文件的格式已更改,因此每个项目只有一个文件,而不是每个项目的每个配置一个文件。此更改仅影响锁定文件的*写入*。Gradle 仍然能够*加载*以旧格式保存的锁定状态。
请查阅文档,了解如何迁移到新格式。迁移可以按配置执行,无需一次性完成。Gradle 在迁移到新文件格式时将自动清理先前的锁定文件。
Gradle 模块元数据现在默认可重现
默认情况下,不会填充 buildId
字段,以确保在构建输入未更改时生成的元数据文件保持不变。用户仍然可以选择将此唯一标识符包含在生成的元数据中,详见文档。
jcenter()
便利方法现已弃用
JFrog 于 2021 年 2 月宣布 JCenter 仓库即将关闭。许多 Gradle 构建依赖 JCenter 获取项目依赖。
没有新的包或版本发布到 JCenter,但 JFrog 表示他们将无限期保持 JCenter 以只读状态运行。我们建议你考虑使用 mavenCentral()
、google()
或私有 maven
仓库替代。
当使用 jcenter()
作为仓库时,Gradle 会发出弃用警告,并且此方法计划在 Gradle 8.0 中移除。
潜在的破坏性变更
捆绑的 Gradle 依赖更新
-
Kotlin 已更新至 Kotlin 1.4.31。
-
Groovy 已更新至 Groovy 3.0.7。
Groovy 和 Groovy DSL 的变更
由于升级到 Groovy 的下一个主要版本,在升级到 Gradle 7.0 时,你可能会遇到一些小问题。
新版本的 Groovy 具有更严格的解析器,对于在以前的 Groovy 版本中可能被接受的代码会编译失败。如果你遇到语法错误,请查阅 Groovy 问题跟踪器 和 Groovy 3 发布亮点。
一些非常特定的回归已在 Groovy 的下一个小版本中得到修复。
Groovy 模块化
Gradle 不再嵌入将所有 Groovy 模块捆绑到一个 jar 中的 groovy-all
副本——只有最重要的模块会随 Gradle 分发版一起分发。
localGroovy()
依赖将包含以下 Groovy 模块
-
groovy
-
groovy-ant
-
groovy-astbuilder
-
groovy-console
-
groovy-datetime
-
groovy-dateutil
-
groovy-groovydoc
-
groovy-json
-
groovy-nio
-
groovy-sql
-
groovy-templates
-
groovy-test
-
groovy-xml
但**不**包含以下 Groovy 模块
-
groovy-cli-picocli
-
groovy-docgenerator
-
groovy-groovysh
-
groovy-jmx
-
groovy-jsr223
-
groovy-macro
-
groovy-servlet
-
groovy-swing
-
groovy-test-junit5
-
groovy-testng
你可以像任何其他外部依赖一样将这些依赖拉入你的构建中。
使用 Groovy 3 构建 Gradle 插件
使用 Gradle 7.0 构建的插件在使用 gradleApi()
或 localGroovy()
时,其类路径上现在将包含 Groovy 3。
如果你使用 Spock 测试你的插件,你需要使用 Spock 2.x。Spock 1.x 和 Groovy 3 没有兼容的版本。 |
dependencies {
// Ensure you use the Groovy 3.x variant
testImplementation('org.spockframework:spock-core:2.0-groovy-3.0') {
exclude group: 'org.codehaus.groovy'
}
}
// Spock 2 is based on JUnit Platform which needs to be enabled explicitly.
tasks.withType(Test).configureEach {
useJUnitPlatform()
}
性能
根据子项目数量和 Groovy DSL 构建脚本数量,你可能会在首次编译构建脚本或更改构建脚本的类路径时注意到性能下降。这是由于 Groovy 3 解析器的性能较慢,但 Groovy 团队已经意识到这个问题并正在努力缓解性能下降。
总的来说,我们也在研究如何改进 Groovy DSL 和 Kotlin DSL 构建脚本的编译性能。
遇到 'Could not find method X for arguments Y on DefaultDependencyHandler'
尽管以下错误最初看起来像编译错误,但实际上是由于移除了特定的 `Configuration` 所致。有关详细信息,请参阅移除 compile
和 runtime
配置。
Could not find method testCompile() for arguments [DefaultExternalModuleDependency{group='org.junit', name='junit-bom', version='5.7.0', configuration='default'}] on object of type org.gradle.api.internal.artifacts.dsl.dependencies.DefaultDependencyHandler.
默认工具集成版本更新
-
PMD 已更新至 PMD 6.31.0。
-
Groovy 和 GroovyDoc 已更新至 Groovy 3.0.7。
移除 compile
和 runtime
配置
自诞生以来,Gradle 提供了 compile
和 runtime
配置来声明依赖。然而,它们不支持对依赖进行细粒度范围划分。因此,Gradle 3.4 中引入了更好的替代方案。
-
implementation
配置应用于声明库的*实现细节*依赖:它们在编译时对库的消费者不可见。 -
api
配置(仅在应用java-library
插件时可用)应用于声明库 API 的依赖,需要在编译时暴露给消费者。
在 Gradle 7 中,compile
和 runtime
配置均已移除。因此,你必须迁移到上述的 implementation
和 api
配置。如果你仍然为 Java 库使用 java
插件,则需要改为应用 java-library
插件。
已移除的配置 | 新配置 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
通过阅读Java Library 插件文档,你可以找到有关新配置的优势以及如何替代 compile
和 runtime
的更多详细信息。
使用 Groovy DSL 时,在处理已移除的配置时需要注意一个特定的升级问题。
如果你创建了继承已移除配置的自定义配置,Gradle 可能会静默地创建不存在的配置。
这看起来像这样
configurations {
// This silently creates a configuration called "runtime"
myConf extendsFrom runtime
}
你的自定义配置的依赖解析结果可能与 Gradle 6.x 或更早版本不同。你可能会注意到依赖或 artifact 丢失。
ProjectBuilder
的临时项目文件位置
ProjectBuilder
API 用于在单元测试中检查 Gradle 构建。此 API 过去在系统临时目录(由 java.io.tmpdir
定义)下创建临时项目文件。
该 API 现在在 Test
任务的临时目录下创建临时项目文件。此路径通常位于项目构建目录下。当测试预期特定文件路径时,这可能会导致测试失败。
如果测试使用 ProjectBuilder.withProjectDir(…)
,则不受影响。
TestKit 测试的临时文件位置
使用TestKit API 的测试过去在系统临时目录(由 java.io.tmpdir
定义)下创建临时文件。这些文件用于存储 Gradle 分发版副本或其他仅用于测试的 Gradle 用户主目录。
TestKit 测试现在将在 Test
任务的临时目录下创建临时文件。此路径通常位于项目构建目录下。当测试预期特定文件路径时,这可能会导致测试失败。
如果测试使用 GradleRunner.withTestKitDir(…)
,则不受影响。
Windows 上 TestKit 的文件系统监听
Windows 上的文件系统监听实现会在根项目目录上添加一个锁,以便监听变更。这可能会导致你在使用 TestKit 运行构建后尝试删除根项目目录时出现错误。例如,将 TestKit 与 JUnit 的 @TempDir
扩展或 TemporaryFolder
规则一起使用的测试可能会遇到此问题。为了避免这些文件锁问题,TestKit
在 Windows 上通过 GradleRunner
执行的构建中禁用了文件系统监听。如果你想覆盖默认行为,可以通过将 --watch-fs
传递给 GradleRunner.withArguments()
来启用文件系统监听。
移除 uploadArchives
任务
uploadArchives
任务与旧版 Ivy 或 Maven 发布机制结合使用。它已在 Gradle 7 中移除。你应该改用 maven-publish
或 ivy-publish
插件。
请参阅 Maven Publish 插件的文档了解如何发布到 Maven 仓库。请参阅 Ivy Publish 插件的文档了解如何发布到 Ivy 仓库。
依赖版本排序变更
在依赖版本排序中,-SNAPSHOT
版本现在被认为恰好位于最终版本之前,但在任何 -RC
版本之后。更多特殊的版本后缀也已考虑在内。这使得 Gradle 算法对于知名版本后缀更接近 Maven 算法。
请查阅文档,了解 Gradle 应用的所有规则。
移除 Play Framework 插件
已弃用的 Play 插件已移除。插件门户提供了外部替代品 Play Framework plugin。
移除已弃用的 JVM 插件
这些未维护的替代 JVM 插件已移除:java-lang
、scala-lang
、junit-test-suite
、jvm-component
、jvm-resources
。
请改用稳定的Java Library 和 Scala 插件。
移除实验性 JavaScript 插件
以下用于实验性 JavaScript 集成的插件已从分发版中移除:coffeescript-base
、envjs
、javascript-base
、jshint
、rhino
。
如果你尽管它们是实验性插件但仍在使用它们,你可能会在 插件门户找到合适的替代品。
配置 Ivy 仓库的布局
接受配置块的 layout
方法已移除,由 patternLayout 替代。
执行没有 settings 文件的 Gradle 构建现在会报错
Gradle 构建由当前目录或父目录中的 settings.gradle(.kts)
文件定义。如果没有 settings 文件,Gradle 构建是未定义的,并且尝试执行任务时 Gradle 会产生错误。
要解决此错误,请为构建创建 settings.gradle(.kts)
文件。
例外情况是使用 init
任务调用 Gradle 或使用诊断命令行标志,例如 --version
。
在项目评估后调用 Project.afterEvaluate() 现在会报错
Gradle 6.x 在这种情况下会警告用户不正确的行为并忽略目标动作。从 7.0 开始,同样的情况将产生错误。插件和构建脚本应调整为仅在配置阶段调用 afterEvaluate
。如果你的构建出现此类故障并且相关的 afterEvaluate
语句声明在你的构建源中,则你可以简单地删除它。如果 afterEvaluate
声明在插件中,则向插件维护者报告此问题。
在值确定后修改文件集合现在会报错
在计算存储值后,对 ConfigurableFileCollection
调用任何修改方法(即 clear()
, add()
, remove()
等)会抛出异常。用户和插件作者应调整其代码,以便所有关于 ConfigurableFileCollection
的配置都发生在配置阶段,即在读取值之前。
移除 ProjectLayout#configurableFiles
请改用 ObjectFactory#fileCollection()
。
移除 BasePluginConvention.libsDir
和 BasePluginConvention.distsDir
请改用 libsDirectory
和 distsDirectory
属性。
移除 UnableToDeleteFileException
现有用法应替换为 RuntimeException
。
Checkstyle 和 PMD 插件中移除的属性
-
configDir
的 getter 和 setter 已从 Checkstyle 任务和扩展中移除。请改用configDirectory
属性。 -
rulePriority
的 getter 和 setter 已从 Pmd 任务和扩展中移除。请改用rulesMinimumPriority
属性。
移除 distribution
插件中的 baseName
属性
getBaseName()
和 setBaseName()
方法已从 Distribution
类中移除。客户端应将其用法替换为 distributionBaseName
属性。
使用 AbstractTask
使用 AbstractTask
类型或继承 AbstractTask
的类型注册任务在 Gradle 6.5 中已弃用,在 Gradle 7.0 中现在是错误。你可以改用 DefaultTask。
移除 BuildListener.buildStarted(Gradle)
BuildListener.buildStarted(Gradle)
在 Gradle 6.0 中已弃用,并在 Gradle 7.0 中移除。请改用 BuildListener.beforeSettings(Settings)。
移除未使用的 StartParameter
API
以下 API(自 Gradle 5.0 起无法再通过命令行选项使用)现已移除:StartParameter.useEmptySettings()
、StartParameter.isUseEmptySettings()
、StartParameter.setSearchUpwards(boolean)
和 StartParameter.isSearchUpwards()
。
移除在 'master' 目录中搜索 settings 文件
Gradle 不再支持在同级目录名为 master
的目录中查找 settings 文件。如果你的构建仍在使用此已弃用的特性,请考虑重构构建,使根目录与项目层级的物理根目录匹配。你可以在用户手册中找到有关如何构建 Gradle 构建结构的更多信息。或者,你仍然可以通过仅从 master
目录调用构建并使用任务的完全限定路径来运行此类构建中的任务。
移除 ValidateTaskProperties
ValidateTaskProperties
任务已移除,并由 ValidatePlugins 任务替代。
移除 ImmutableFileCollection
ImmutableFileCollection
类型已移除。请改用 工厂方法。可以通过 Project.layout 获取项目布局的句柄。
移除 ComponentSelectionReason.getDescription
方法 ComponentSelectionReason.getDescription
已移除。它被 ComponentSelectionReason.getDescriptions
替代,后者返回一个 ComponentSelectionDescriptor
列表,每个列表都有一个 getDescription
方法。
移除域对象集合构造函数
以下已弃用的构造函数已移除
-
DefaultNamedDomainObjectList(Class, Instantiator, Namer)
-
DefaultNamedDomainObjectSet(Class, Instantiator)
-
DefaultPolymorphicDomainObjectContainer(Class, Instantiator)
-
FactoryNamedDomainObjectContainer(Class, Instantiator, NamedDomainObjectFactory)
移除任意本地缓存配置
本地构建缓存配置现在需要通过 BuildCacheConfiguration.local() 完成。
移除 DefaultVersionSelectorScheme 构造函数
此内部 API 在插件中使用,其中包括 Nebula 插件,并在 Gradle 5.x 时间线中弃用,现在已移除。最新的插件版本不应再引用它。
在 checkstyle
插件上设置 config_loc
配置属性现在会报错
对于以下配置,checkstyle
插件现在会失败
checkstyle {
configProperties['config_loc'] = file("path/to/checkstyle-config-dir")
}
构建应该使用 checkstyle
块声明 checkstyle 配置
checkstyle {
configDirectory = file("path/to/checkstyle-config-dir")
}
在生产者完成之前查询 provider 的映射值现在会报错
Gradle 6.x 在这种情况下会警告用户不正确的行为,然后返回一个可能不正确的 provider 值。从 7.0 开始,同样的情况将产生错误。插件和构建脚本应调整为在任务完成后才查询 provider 的映射值,例如任务输出属性。
任务验证问题现在会报错
Gradle 6.0 开始警告任务定义中的问题(例如输入或输出定义不正确)。在 Gradle 7.0 中,这些警告现在是错误,并将导致构建失败。
与本地项目存在严格版本冲突时的行为变更
先前的 Gradle 版本在特定配置的冲突解决方面存在不一致的行为: - 你的项目声明了对发布模块的严格依赖(例如,com.mycompany:some-module:1.2!!
,其中 1.2!!
是对 1.2 的严格依赖的简写符号) - 你的构建实际上提供了更高版本的 com.mycompany:some-module
先前的 Gradle 版本会成功,选择项目依赖,尽管存在严格约束。从 Gradle 7 开始,这将触发依赖解析失败。
更多背景信息请参阅此问题。
弃用
任务之间丢失的依赖关系
有一个任务在一个位置产生输出,另一个任务通过将其作为输入引用来消费该位置,但消费者任务不依赖于生产者任务,这种行为已被弃用。此问题的修复方法是从消费者向生产者添加依赖关系。
重复项策略
当复制操作(或任何使用 org.gradle.api.file.CopySpec
的操作)遇到重复条目,且未设置重复项策略时,Gradle 7 现在会失败。有关详细信息,请查看 CopySpec 文档。
从 6.8 及更早版本升级
从 6.8 到 6.9 没有升级说明,因为 6.9 只包含错误修复。
从 6.7 及更早版本升级
潜在的破坏性变更
Toolchain API 现在标记为 @NonNull
支持 Java 工具链特性的 org.gradle.jvm.toolchain
中的 API 现在标记为 @NonNull
。
这可能会影响 Kotlin 消费者,因为 API 的返回类型不再是可空的。
默认工具集成版本更新
-
JaCoCo 已更新至 0.8.6。
-
Checkstyle 已更新至 Checkstyle 8.37。
-
CodeNarc 已更新到 CodeNarc 2.0.0。
捆绑的 Gradle 依赖项更新
-
Kotlin 已更新到 Kotlin 1.4.20。请注意,Gradle 脚本仍在使用 Kotlin 1.3 语言。
-
Apache Ant 已更新到 1.10.9 以修复 CVE-2020-11979
导入到 Eclipse 中的项目现在包含自定义源集类路径
以前,Eclipse 导入的项目仅包含 main 和 test 源集的依赖项。自定义源集的编译和运行时类路径会被忽略。
从 Gradle 6.8 起,导入到 Eclipse 中的项目包含构建定义的所有源集的编译和运行时类路径。
SourceTask 不再对空目录敏感
以前,对于 SourceTask
中声明的源,在进行最新检查和构建缓存键计算时会考虑空目录。这意味着包含空目录的源树与不包含空目录但其他方面相同的源树会被视为不同的源,即使任务会产生相同的输出。在 Gradle 6.8 中,SourceTask
在进行最新检查和构建缓存键计算时会忽略空目录。在绝大多数情况下,这是期望的行为,但任务可能扩展 SourceTask
并在源中存在空目录时产生不同的输出。对于涉及此问题的任务,可以暴露一个没有 @IgnoreEmptyDirectories
注解的单独属性,以捕获这些更改
@InputFiles
@SkipWhenEmpty
@PathSensitive(PathSensitivity.ABSOLUTE)
public FileTree getSourcesWithEmptyDirectories() {
return super.getSource()
}
发布方面的更改
发布依赖于 enforced platform 的组件现在会触发验证错误,防止意外发布不良元数据:enforced platform 的用例应限于应用程序,而不应是可被其他库或应用程序消费的事物。
如果由于某些原因,您仍然想要发布依赖于 enforced platforms 的组件,可以按照 文档 禁用验证。
在执行阶段更改默认排除项
Gradle 的文件树为了方便应用了一些默认的排除模式——实际上与 Ant 的默认值相同。更多信息请参阅 用户手册。有时,Ant 的默认排除项会带来问题,例如当您想将 .gitignore
包含在存档文件中时。
在执行阶段更改 Gradle 的默认排除项可能导致最新检查的正确性问题。因此,您只能在 settings 脚本中更改 Gradle 的默认排除项,有关示例请参阅 用户手册。
弃用
引用内含构建中的任务
在 mustRunAfter
、shouldRunAfter
和 finalizedBy
任务方法中,直接引用内含构建中的任务已被弃用。应使用 mustRunAfter
和 shouldRunAfter
进行任务排序以及使用 finalizedBy
指定的 finalizers 来进行构建内的任务排序。如果您恰好使用上述方法定义了跨构建任务排序,请考虑重构此类构建并将它们彼此解耦。
在 'master' 目录中搜索 settings 文件
当您的构建依赖于在同级目录中名为 master
的目录中查找 settings 文件时,Gradle 将发出弃用警告。
如果您的构建使用了此功能,请考虑重构构建,使根目录匹配项目层次结构的物理根目录。
或者,您仍然可以通过仅使用任务的 完全限定路径 从 master
目录调用构建来运行此类构建中的任务。
使用方法 NamedDomainObjectContainer<T>.invoke(kotlin.Function1)
Gradle Kotlin DSL 扩展已更改为优先使用 Gradle 的 Action<T>
类型而不是 Kotlin 函数类型。
虽然此更改对 Kotlin 客户端应该是透明的,但调用 Kotlin DSL 扩展的 Java 客户端需要更新以使用 Action<T>
API。
从 6.6 及更早版本升级
潜在的破坏性变更
buildSrc 现在可以从根目录看到内含构建
以前,buildSrc
的构建方式会忽略根构建中的内含构建。
从 Gradle 6.7 起,buildSrc
可以看到根构建中的任何内含构建。这可能导致 buildSrc
中的依赖项从内含构建中被替换。如果 buildSrc
需要内含构建,这还可能改变某些构建的执行顺序。
默认工具集成版本更新
-
PMD 已更新到 PMD 6.26.0。
-
Checkstyle 已更新到 Checkstyle 8.35。
-
CodeNarc 已更新到 CodeNarc 1.6.1。
弃用
在执行阶段更改默认排除项
Gradle 的文件树为了方便应用了一些默认的排除模式——实际上与 Ant 的默认值相同。更多信息请参阅 用户手册。有时,Ant 的默认排除项会带来问题,例如当您想将 .gitignore
包含在存档文件中时。
在执行阶段更改 Gradle 的默认排除项可能导致最新检查的正确性问题,此操作已被弃用。您只能在 settings 脚本中更改 Gradle 的默认排除项,有关示例请参阅 用户手册。
直接使用 Configuration 作为依赖项
Gradle 曾允许将 Configuration
实例直接用作依赖项
dependencies {
implementation(configurations.myConfiguration)
}
此行为现已弃用,因为它令人困惑:人们可能会期望“依赖配置”先被解析,然后将解析结果作为依赖项添加到包含配置中,但实际情况并非如此。弃用版本可以用实际行为(即配置继承)代替。
configurations.implementation.extendsFrom(configurations.myConfiguration)
从 6.5 及更早版本升级
潜在的破坏性变更
捆绑的 Gradle 依赖项更新
-
Ant 已更新到 1.10.8。
-
Groovy 已更新到 Groovy 2.5.12。
依赖项替换和 感知变体 依赖项解析
在依赖项替换中添加对表达 感知变体 支持的支持时,一个错误修复引入了某些构建可能依赖的行为变更。以前,被替换的依赖项仍然会使用原始选择器的属性,而不是替换选择器的属性。
随着此更改,围绕具有更丰富选择器(例如 platform 依赖项)的现有替换将不再像以前那样工作。在目标选择器中定义 感知变体 部分成为强制要求。
如果您出现以下情况,可能会受到此更改的影响
-
依赖于平台,例如
implementation platform("org:platform:1.0")
-
或者 如果您在依赖项上指定了属性,
-
并且 您在这些依赖项上使用了 解析规则。
有关解决受影响问题的更多信息,请参阅 文档。
弃用
Gradle 6.6 中没有进行任何弃用。
从 6.4 及更早版本升级
潜在的破坏性变更
捆绑的 Gradle 依赖项更新
-
Kotlin 已更新到 Kotlin 1.3.72。
-
Groovy 已更新到 Groovy 2.5.11。
默认工具集成版本更新
-
PMD 已更新到 PMD 6.23.0。
弃用
内部类 AbstractTask 已被弃用
AbstractTask
是一个内部类,作为公共类型 DefaultTask
的超类,在公共 API 上可见。AbstractTask
将在 Gradle 7.0 中移除,以下内容在 Gradle 6.5 中已被弃用:
-
注册类型为
AbstractTask
或TaskInternal
的任务。您可以从任务注册中移除任务类型,Gradle 将转而使用DefaultTask
。 -
注册类型是
AbstractTask
的子类但不是DefaultTask
的子类的任务。您可以更改任务类型,使其转而扩展DefaultTask
。 -
在插件代码或构建脚本中使用类
AbstractTask
。您可以更改代码,使其转而使用DefaultTask
。
从 6.3 及更早版本升级
潜在的破坏性变更
PMD 插件默认需要 PMD 6.0.0 或更高版本
Gradle 6.4 默认启用增量分析。增量分析仅在 PMD 6.0.0 或更高版本中可用。如果您想使用旧版本的 PMD,需要禁用增量分析
pmd {
incrementalAnalysis = false
}
依赖项锁定方面的更改
在 Gradle 6.4 中,依赖项锁定 LockMode
的孵化中 API 已更改。现在通过 Property<LockMode>
设置值,而不是直接的 setter。这意味着需要更新 Kotlin DSL 中设置值的写法。
dependencyLocking {
lockMode.set(LockMode.STRICT)
}
Groovy DSL 的用户应该不会受到影响,因为写法 lockMode = LockMode.STRICT
仍然有效。
已发布元数据中的 Java 版本
如果使用 Gradle Module Metadata 发布 Java 库,则它支持的 Java 版本信息编码在 org.gradle.jvm.version
属性中。默认情况下,此属性设置为您在 java.targetCompatibility
中配置的值。如果未配置,则设置为运行 Gradle 的当前 Java 版本。更改特定编译任务的版本(例如 javaCompile.targetCompatibility
)不会影响该属性,如果未手动调整属性,会导致错误的信息。此问题现已修复,该属性默认为与发布 jar 构建源关联的编译任务的设置。
具有自定义布局的 Ivy 仓库
Gradle 6.0 到 6.3.x 版本在发布到具有自定义仓库布局的 Ivy 仓库时可能会生成不良的 Gradle Module Metadata。从 6.4 开始,如果 Gradle 检测到您正在使用自定义仓库布局,将不再发布 Gradle Module Metadata。
新属性可能会遮蔽构建脚本中的变量
本版本在不同位置引入了一些新属性——mainClass
、mainModule
、modularity
。由于这些名称非常通用,您在构建脚本中可能将其中一个用作变量名。新属性可能会以不期望的方式遮蔽您的某个变量,导致构建失败,因为访问的是该属性而不是同名局部变量。您可以通过重命名构建脚本中对应的变量来解决此问题。
受影响的是 application {}
和 java {}
配置块内的配置代码,使用 project.javaexec {}
进行 java 执行设置的代码,以及各种任务配置(JavaExec
、CreateStartScripts
、JavaCompile
、Test
、Javadoc
)。
捆绑的 Gradle 依赖项更新
-
Kotlin 已更新到 Kotlin 1.3.71。
弃用
Gradle 6.3 和 6.4 之间没有进行任何弃用。
从 6.2 及更早版本升级
潜在的破坏性变更
IDEA 中可用的依赖项更少
Gradle 不再将注解处理器类路径作为 provided 依赖项包含在 IDEA 中。IDEA 在编译时看到的依赖项与 Gradle 在解析编译类路径(名为 compileClasspath
的配置)后看到的依赖项相同。这防止了注解处理器依赖项泄漏到项目代码中。
捆绑的 Gradle 依赖项更新
-
Kotlin 已更新到 Kotlin 1.3.70。
-
Groovy 已更新到 Groovy 2.5.10。
默认工具集成版本更新
-
PMD 已更新到 PMD 6.21.0。
-
CodeNarc 已更新到 CodeNarc 1.5。
某些 32 位操作系统已移除富控制台支持
Gradle 6.3 不支持 32 位 Unix 系统和旧版本 FreeBSD(早于 FreeBSD 10)的 富控制台。Microsoft Windows 32 位不受影响。
Gradle 将继续在 32 位系统上构建项目,但将不再显示富控制台。
弃用
使用 default 和 archives 配置
几乎每个 Gradle 项目都有 default 和 archives 配置,这些配置由 base 插件添加。在现代 Gradle 构建中,这些配置已不再使用,现代构建使用 感知变体 依赖管理 和 新的发布插件。
虽然这些配置目前为了向后兼容性会保留在 Gradle 中,但将它们用于声明依赖项或解析依赖项现已弃用。
解析这些配置从未是预期的用例,之所以可能只是因为在早期 Gradle 版本中 每个 配置都是可解析的。对于声明依赖项,请使用您使用的插件提供的配置,例如 Java Library 插件 提供的配置。
从 6.1 及更早版本升级
潜在的破坏性变更
编译和运行时类路径现在默认请求 library 变体
JVM 项目中的类路径现在显式请求 org.gradle.category=library
属性。如果某个库无法使用,这会导致更清晰的错误消息。例如,当库不支持所需的 Java 版本时。实际效果是现在所有 platform 依赖项 都必须声明为 platform。以前,对于本地平台或使用 Gradle Module Metadata 发布的平台,即使省略 platform()
关键字,platform 依赖项也意外地起作用。
项目根目录 gradle.properties
中的属性泄漏到 buildSrc
和内含构建中
Gradle 6.2 和 Gradle 6.2.1 中存在一个回归问题,导致在项目根目录的 gradle.properties
文件中设置的 Gradle 属性泄漏到 buildSrc
构建和根目录包含的任何构建中。
如果 buildSrc
构建或内含构建突然发现来自项目根目录 gradle.properties
文件的属性值不期望或不兼容,这可能导致您的构建开始失败。
该回归问题已在 Gradle 6.2.2 中修复。
弃用
Gradle 6.1 和 6.2 之间没有进行任何弃用。
从 6.0 及更早版本升级
弃用
在任务完成前查询任务的映射输出属性
在任务完成前查询映射输出属性的值可能导致奇怪的构建失败,因为它表明可能错误地使用了过时或不存在的输出。此行为已被弃用,并将发出弃用警告。这将在 Gradle 7.0 中成为错误。
以下示例演示了此问题,其中在 Producer 执行之前解析了 Producer 的输出文件
class Consumer extends DefaultTask {
@Input
final Property<Integer> threadPoolSize = ...
}
class Producer extends DefaultTask {
@OutputFile
final RegularFileProperty outputFile = ...
}
// threadPoolSize is read from the producer's outputFile
consumer.threadPoolSize = producer.outputFile.map { it.text.toInteger() }
// Emits deprecation warning
println("thread pool size = " + consumer.threadPoolSize.get())
如果在 producer
完成之前查询 consumer.threadPoolSize
的值,将产生弃用警告,因为输出文件尚未生成。
已停用方法
以下方法已停用,不应再使用。它们将在 Gradle 7.0 中移除。
-
BasePluginConvention.setProject(ProjectInternal)
-
BasePluginConvention.getProject()
-
StartParameter.useEmptySettings()
-
StartParameter.isUseEmptySettings()
替代 JVM 插件(也称为“软件模型”)
在 Gradle 2.x 中引入了一组基于“软件模型”的 Java 和 Scala 开发替代插件。这些插件现已弃用,最终将被移除。如果您仍在使用这些旧插件(java-lang
、scala-lang
、jvm-component
、jvm-resources
、junit-test-suite
),请查阅 构建 Java 和 JVM 项目 文档,以确定哪些稳定的 JVM 插件适合您的项目。
潜在的破坏性变更
ProjectLayout
不再作为服务提供给 worker actions
在 Gradle 6.0 中,ProjectLayout
服务通过服务注入的方式提供给 worker actions。此服务允许可变状态泄漏到 worker action 中,并引入了一种依赖项在 worker action 中未声明的方式。
ProjectLayout
已从可用服务中移除。曾使用 ProjectLayout
的 worker actions 应改为注入 projectDirectory
或 buildDirectory
作为参数。
捆绑的 Gradle 依赖项更新
-
Kotlin 已更新到 Kotlin 1.3.61。
默认工具集成版本更新
-
Checkstyle 已更新到 Checkstyle 8.27。
-
PMD 已更新到 PMD 6.20.0。
发布 Spring Boot 应用程序
从 Gradle 6.2 开始,Gradle 在上传前执行一次完整性检查,以确保您不会上传过时的文件(由另一个构建生成的文件)。这给使用 components.java
组件上传的 Spring Boot 应用程序带来了问题。
Artifact my-application-0.0.1-SNAPSHOT.jar wasn't produced by this build.
这是由于 Spring Boot 应用程序禁用了主要的 jar
任务,而组件期望该任务存在。由于 bootJar
任务默认使用与主要 jar
任务 相同的文件,因此 Gradle 的早期版本会:
-
发布过时的
bootJar
artifact -
或者如果之前没有调用过
bootJar
任务则失败
一种解决方法是告诉 Gradle 要上传什么。如果您想上传 bootJar
,则需要配置 outgoing configurations 来完成此操作。
configurations {
[apiElements, runtimeElements].each {
it.outgoing.artifacts.removeIf { it.buildDependencies.getDependencies(null).contains(jar) }
it.outgoing.artifact(bootJar)
}
}
或者,您可能希望重新启用 jar
任务,并添加具有不同 classifier 的 bootJar
。
jar {
enabled = true
}
bootJar {
classifier = 'application'
}