本章提供将 Gradle 5.x 构建迁移到 Gradle 6.0 所需的信息。要从 Gradle 4.x 迁移,请先完成4.x 到 5.0 指南

我们向所有用户推荐以下步骤

  1. 尝试运行 gradle help --scan 并查看生成的构建扫描中的废弃用法视图

    Deprecations View of a Gradle Build Scan

    这样您就可以看到适用于您的构建的任何废弃警告。

    另外,您可以运行 gradle help --warning-mode=all 在控制台中查看废弃项,尽管它可能不会报告太多详细信息。

  2. 更新您的插件。

    某些插件在新版本的 Gradle 中会失效,例如因为它们使用了已移除或更改的内部 API。上一步将在插件尝试使用已废弃的 API 部分时发出废弃警告,从而帮助您识别潜在问题。

  3. 运行 gradle wrapper --gradle-version 6.0 将项目更新到 6.0。

  4. 尝试运行项目并使用故障排除指南调试任何错误。

从 5.6 及更早版本升级

废弃

不再推荐使用 compileruntime 配置声明依赖项

Gradle 3.4 起,已不推荐在 Java 生态系统插件中使用 compileruntime 配置。

这些配置用于编译和运行 main 源集中的代码。其他源集也会创建类似的配置(例如 test 源集的 testCompiletestRuntime),这些也不应使用。应使用 implementationapicompileOnlyruntimeOnly 配置来声明依赖项,使用 compileClasspathruntimeClasspath 配置来解析依赖项。请参阅这些配置之间的关系

旧的发布系统已废弃,并被 *-publish 插件取代

uploadArchives 任务和 maven 插件已废弃。

用户应迁移到 Gradle 的发布系统,使用 maven-publishivy-publish 插件。这些插件自 Gradle 4.8 起已稳定。

发布系统也是确保发布Gradle 模块元数据的唯一方式。

任务问题会发出废弃警告

当 Gradle 检测到任务定义问题(例如输入或输出定义不正确)时,它会在控制台上显示以下消息

Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org.cn/6.0/userguide/command_line_interface.html#sec:command_line_warnings

无论使用什么命令行开关,废弃警告都会在每次构建的构建扫描中显示。

当构建使用 --warning-mode all 执行时,将显示单个警告

> Task :myTask
Property 'inputDirectory' is declared without normalization specified. Properties of cacheable work must declare their normalization via @PathSensitive, @Classpath or @CompileClasspath. Defaulting to PathSensitivity.ABSOLUTE. This behavior is scheduled to be removed in Gradle 7.0.
Property 'outputFile' is not annotated with an input or output annotation. This behavior is scheduled to be removed in Gradle 7.0.

如果您拥有相关任务的代码,可以通过遵循建议来修复它们。您还可以使用 --stacktrace 来查看每个警告源自代码中的何处。

否则,您需要向相关任务或插件的维护者报告问题。

用于增量任务的旧 API IncrementalTaskInputs 已废弃

在 Gradle 5.4 中,我们引入了一个用于实现增量任务的新 API:InputChanges。基于 IncrementalTaskInputs 的旧 API 已废弃。

强制依赖项

对一级依赖项使用 force = true 强制指定依赖版本已废弃。

强制指定存在语义和顺序问题,可以通过使用严格版本约束来避免。

在 Gradle 5.0 中,我们移除了 --no-search-upward CLI 参数。

StartParameter 中相关的 API(如 isSearchUpwards())现已废弃。

API BuildListener.buildStartedGradle.buildStarted 已废弃

这些方法目前无法按预期工作,因为构建开始后,回调函数将永远不会被调用。

废弃这些方法是为了避免混淆。

Copy 或归档任务的隐式重复策略已废弃

默认情况下,归档任务 TarZip 允许在创建的归档文件中存在同一路径的多个条目。这可能导致“严重无效的 zip 文件”,可能触发 zip bomb 检测

为防止意外发生,在创建归档文件时遇到重复项现在会产生废弃消息,并且从 Gradle 7.0 开始将导致构建失败。

Copy 任务也会将具有相同相对路径的多个源文件复制到目标目录,而不会出错。此行为也已废弃。

如果您希望允许重复项,可以显式指定

task archive(type: Zip) {
    duplicatesStrategy = DuplicatesStrategy.INCLUDE // allow duplicates
    ...
}

在没有 settings 文件的情况下执行 Gradle 已废弃

Gradle 构建由当前或父目录中的 settings.gradle[.kts] 文件定义。如果没有 settings 文件,Gradle 构建将是未定义的,并会发出废弃警告。

在 Gradle 7.0 中,对于未定义的构建,Gradle 将仅允许您调用 init 任务或诊断命令行标志,例如 --version

在已评估的项目上调用 Project.afterEvaluate 已废弃

项目评估完成后,Gradle 将忽略传递给 Project#afterEvaluate 的所有配置,并发出废弃警告。此情况在 Gradle 7.0 中将变为错误。

废弃的插件

以下捆绑插件从未宣布过,并且将在 Gradle 的下一个主要版本中移除

  • org.gradle.coffeescript-base

  • org.gradle.envjs

  • org.gradle.javascript-base

  • org.gradle.jshint

  • org.gradle.rhino

其中一些插件可能在插件门户上找到了替代品。

潜在的破坏性更改

不再支持 Android Gradle Plugin 3.3 及更早版本

Gradle 6.0 支持 Android Gradle Plugin 3.4 及更高版本。

不再支持 Build scan plugin 2.x

对于 Gradle 6,必须使用 Develocity 插件替换 build scan 插件。这还需要更改应用插件的方式。更多信息请参阅 https://gradle.com/help/gradle-6-build-scan-plugin

更新捆绑的 Gradle 依赖项

更新默认集成版本

复合构建中构建和任务名称的更改

以前,Gradle 使用根项目的名称作为包含构建的构建名称。现在,使用构建根目录的名称,如果根项目名称不同则不予考虑。如果通过 settings 文件包含构建,可以指定构建的另一个名称。

includeBuild("some-other-build") {
    name = "another-name"
}

以前的行为有问题,因为它导致在构建期间不同时间使用了不同的名称。

buildSrc 现已保留作为项目和子项目构建名称

以前,Gradle 不阻止在多项目构建的子项目或包含构建的名称中使用名称 "buildSrc"。现在,这是不允许的。"buildSrc" 名称现已保留给用于构建额外构建逻辑的常规 buildSrc 项目。

buildSrc 的典型使用不受此更改影响。只有当您的 settings 文件指定 include("buildSrc")includeBuild("buildSrc") 时,您才会受到影响。

Scala Zinc 编译器

Zinc 编译器已升级到版本 1.3.0。Gradle 不再支持针对 Scala 2.9 进行构建。

Gradle 支持的最低 Zinc 编译器版本是 1.2.0,测试过的最高版本是 1.3.0。

为了更轻松地选择 Zinc 编译器的版本,您现在可以配置一个 zincVersion 属性

scala {
    zincVersion = "1.2.1"
}

请移除您已添加到 zinc 配置中的任何显式依赖项,并改用此属性。如果您尝试使用 com.typesafe.zinc:zinc 依赖项,Gradle 将切换到新的 Zinc 实现。

本地构建缓存始终是目录缓存

以前,可以使用任何构建缓存实现作为 local 缓存。现在不再允许这样做,因为本地缓存必须始终是 DirectoryBuildCache

调用 BuildCacheConfiguration.local(Class) 时,如果类型不是 DirectoryBuildCache,将导致构建失败。使用 DirectoryBuildCache 类型调用这些方法将产生废弃警告。

请改用 getLocal()local(Action)

打包或解包缓存结果失败现在将导致构建失败

以前,当 Gradle 在打包缓存任务结果时遇到问题时,它会忽略该问题并继续运行构建。

当遇到损坏的缓存 artifact 时,Gradle 会移除已解包的内容,并重新执行任务以确保构建有机会成功。

虽然此行为旨在使构建成功,但这产生了隐藏问题的负面影响,并导致缓存性能下降。

在 Gradle 6.0 中,打包和解包错误都将导致构建失败,以便更容易地发现这些问题。

buildSrc 项目自动使用构建缓存配置

以前,为了在 buildSrc 构建中使用构建缓存,您需要在 buildSrc 构建中重复您的构建缓存配置。现在,它会自动使用由顶级 settings 脚本定义的构建缓存配置。

始终发布 Gradle 模块元数据

Gradle 模块元数据于 Gradle 5.3 正式引入,旨在解决困扰依赖管理多年的许多问题,特别是在 Java 生态系统中,但不仅限于此。

在 Gradle 6.0 中,Gradle 模块元数据默认启用。

这意味着,如果您使用 Gradle 发布库并使用 maven-publishivy-publish 插件,除了传统元数据之外,还会始终发布 Gradle 模块元数据文件。

传统元数据文件将包含一个标记,以便 Gradle 知道有额外的元数据可供使用。

Gradle 模块元数据具有更严格的验证

发布 Gradle 模块元数据时会验证以下规则

这些也在规范中进行了说明。

默认情况下不再查询没有元数据的 Maven 或 Ivy 仓库中的 Artifact

如果 Gradle 未能在 repositories { } 部分定义的仓库中找到模块的元数据文件(.pomivy.xml),它现在假定该模块不存在于该仓库中。

对于动态版本,相应模块的 maven-metadata.xml 必须存在于 Maven 仓库中。

以前,Gradle 还会查找默认 artifact(.jar)。当使用多个仓库时,此行为通常会导致大量不必要的请求,从而减慢构建速度。

您可以通过添加 artifact() 元数据源,为选定的仓库启用旧行为。

更改 pom packaging 属性不再更改 artifact 扩展名

以前,如果 pom packaging 不是 jarejbbundlemaven-plugin,则发布到 Maven 仓库的主要 artifact 的扩展名在发布期间会更改以匹配 pom packaging。

此行为导致 Gradle 模块元数据损坏,并且由于处理不同 packaging 类型而难以理解。

构建作者可以在创建 artifact 时更改 artifact 名称以获得与之前相同的结果 — 例如,通过显式设置 jar.archiveExtension.set(pomPackaging)

为 Java 库发布的 ivy.xml 包含更多信息

已进行了一些修复,以在 ivy-publish 插件中生成更正确的 ivy.xml 元数据。

因此,ivy.xml 文件的内部结构已发生变化。runtime 配置现在包含更多信息,对应于 Java 库的 runtimeElements 变体。default 配置应产生与之前相同的结果。

总的来说,建议用户从 ivy.xml 迁移到新的 Gradle 模块元数据格式。

buildSrc 中的类对 settings 脚本不再可见

以前,buildSrc 项目在应用项目 settings 脚本之前构建,其类在脚本中可见。现在,buildSrc 在 settings 脚本之后构建,其类对其不可见。buildSrc 类对项目构建脚本和脚本插件仍然可见。

可以通过声明外部依赖项,从 settings 脚本中使用自定义逻辑。

settings 脚本中的 pluginManagement 块现已隔离

以前,settings 脚本内的任何 pluginManagement {} 块都在脚本的正常执行期间执行。

现在,它们以类似于 buildscript {}plugins {} 的方式更早执行。这意味着此类块中的代码无法引用脚本中其他地方声明的任何内容。

进行此更改是为了在解析 settings 脚本自身的插件时,也可以应用 pluginManagement 配置。

在 settings 脚本中加载的插件和类对项目脚本和 buildSrc 可见

以前,使用 buildscript {} 添加到 settings 脚本的任何类在脚本外部不可见。现在,它们对所有项目构建脚本都可见。

它们也对 buildSrc 构建脚本及其 settings 脚本可见。

进行此更改是为了使应用于 settings 脚本的插件能够为整个构建贡献逻辑。

插件验证更改

  • validateTaskProperties 任务现已废弃,请改用 validatePlugins。新名称更好地反映了它也验证 artifact transform 参数和其他非属性定义的实际情况。

  • ValidateTaskProperties 类型被 ValidatePlugins 取代。

  • setClasses() 方法现已移除。请改用 getClasses().setFrom()

  • setClasspath() 方法也已移除。请改用 getClasspath().setFrom()

  • failOnWarning 选项现已默认启用。

  • 以下任务验证错误现在在运行时导致构建失败,并被提升为 ValidatePlugins 的错误

    • 任务属性被注解为任务不允许使用的属性注解,例如 @InputArtifact

使用 embedded-kotlin 插件现在需要指定仓库

就像使用 kotlin-dsl 插件一样,如果您应用 embedded-kotlin 插件,现在需要声明一个可以找到 Kotlin 依赖项的仓库。

plugins {
    `embedded-kotlin`
}

repositories {
    mavenCentral()
}

Kotlin DSL IDE 支持现在需要 Kotlin IntelliJ Plugin >= 1.3.50

Gradle JVM 设置的版本与 Project SDK 中的版本不同时,Kotlin IntelliJ 插件版本低于 1.3.50 的 Kotlin DSL 脚本会被错误地高亮显示。只需将 IDE 插件升级到版本 >= 1.3.50 即可恢复正确的 Kotlin DSL 脚本高亮显示行为。

Kotlin DSL 脚本基础类型不再继承 ProjectSettingsGradle

在以前的版本中,Kotlin DSL 脚本被编译成实现了三个核心 Gradle 配置接口之一的类,以便将它们的 API 隐式暴露给脚本。org.gradle.api.Project 用于项目脚本,org.gradle.api.initialization.Settings 用于设置脚本,org.gradle.api.invocation.Gradle 用于初始化脚本。

让脚本实例实现它本应配置的模型对象的核心 Gradle 接口很方便,因为它使模型对象 API 可以立即用于脚本主体,但这也是一个谎言,当脚本本身被用作模型对象的替代品时,可能会导致各种问题,一个项目脚本并不是一个真正的 Project 实例,仅仅因为它实现了核心的 Project 接口,设置脚本和初始化脚本也是如此。

在 6.0 中,所有 Kotlin DSL 脚本都被编译成实现新引入的 org.gradle.kotlin.dsl.KotlinScript 接口的类,并且相应的模型对象现在在脚本主体中作为隐式接收者可用。换句话说,项目脚本的行为就像脚本主体被包含在 with(project) { …​ } 块中一样,设置脚本就像脚本主体被包含在 with(settings) { …​ } 块中一样,初始化脚本就像脚本主体被包含在 with(gradle) { …​ } 块中一样。这意味着相应的模型对象也作为属性在脚本主体中可用,project 属性用于项目脚本,settings 属性用于设置脚本,gradle 属性用于初始化脚本。

作为更改的一部分,设置脚本不再实现 SettingsScriptApi 接口,初始化脚本不再实现 InitScriptApi 接口。它们应替换为相应的模型对象接口,即 SettingsGradle

Javadoc 和 Groovydoc 默认不再包含时间戳

生成文档中的时间戳实际用途非常有限,但它们使得可重复的文档构建成为不可能。因此,JavadocGroovydoc 任务现在配置为默认不再包含时间戳。

Checkstyle 忽略用户提供的 'config_loc' 属性

Gradle 在运行 Checkstyle 时,始终使用 configDirectory 作为 'config_loc' 的值。

新的 Tooling API 进度事件

在 Gradle 6.0 中,我们引入了一个新的进度事件 (org.gradle.tooling.events.test.TestOutputEvent),用于暴露测试执行的输出。这个新事件打破了使用 StartEvent-FinishEvent 对来表达进度的惯例。TaskOutputEvent 是一个简单的 ProgressEvent

任务容器行为的更改

任务容器上的以下已弃用方法现在会导致错误

  • TaskContainer.add()

  • TaskContainer.addAll()

  • TaskContainer.remove()

  • TaskContainer.removeAll()

  • TaskContainer.retainAll()

  • TaskContainer.clear()

  • TaskContainer.iterator().remove()

此外,以下已弃用功能现在会导致错误

  • 替换一个已经实现的任务。

  • 用不兼容的类型替换一个已注册(未实现)的任务。兼容的类型是已注册类型的相同类型或子类型。

  • 替换一个从未注册过的任务。

DefaultTaskProjectLayout 上的方法已替换为 ObjectFactory

请使用 ObjectFactory.fileProperty() 代替以下已移除的方法

  • DefaultTask.newInputFile()

  • DefaultTask.newOutputFile()

  • ProjectLayout.fileProperty()

请使用 ObjectFactory.directoryProperty() 代替以下已移除的方法

  • DefaultTask.newInputDirectory()

  • DefaultTask.newOutputDirectory()

  • ProjectLayout.directoryProperty()

注解 @Nullable 已被移除

org.gradle.api.Nullable 注解类型已被移除。请使用 JSR-305 中的 javax.annotation.Nullable 代替。

FindBugs 插件已被移除

已弃用的 FindBugs 插件已被移除。作为替代,您可以使用 Gradle 插件门户中的 SpotBugs 插件

JDepend 插件已被移除

已弃用的 JDepend 插件已被移除。Gradle 插件门户上有许多社区提供的用于代码和架构分析的插件可供选择。

OSGI 插件已被移除

已弃用的 OSGI 插件已被移除。在 Gradle 插件门户上有许多社区提供的 OSGI 插件可供选择。

announce 和 build-announcements 插件已被移除

已弃用的 announce 和 build-announcements 插件已被移除。在 Gradle 插件门户上有许多社区提供的用于发送通知的插件可供选择。

Compare Gradle Builds 插件已被移除

已弃用的 Compare Gradle Builds 插件已被移除。请使用 构建扫描 (build scans) 进行构建分析和比较。

Play 插件已被移除

已弃用的 Play 插件已被移除。可以从插件门户获取一个外部替代插件,即 Play Framework 插件

方法 AbstractCompile.compile() 方法已被移除

抽象方法 compile() 不再由 AbstractCompile 声明。

继承 AbstractCompile 的任务可以实现它们自己选择名称的 @TaskAction 方法。

它们也可以自由地添加一个使用 InputChanges 参数并带有 @TaskAction 注解的方法,而无需同时实现一个无参数的方法。

其他已弃用的行为和 API

  • org.gradle.util.internal.GUtil.savePropertiesNoDateComment 已被移除。此内部方法没有公共替代方法。

  • 已弃用的类 org.gradle.api.tasks.compile.CompilerArgumentProvider 已被移除。请使用 org.gradle.process.CommandLineArgumentProvider 代替。

  • 已弃用的类 org.gradle.api.ConventionProperty 已被移除。请使用 Providers 代替 convention properties。

  • 已弃用的类 org.gradle.reporting.DurationFormatter 已被移除。

  • 返回 TaskInputs 的桥接方法 org.gradle.api.tasks.TaskInputs.property(String name, @Nullable Object value) 已被移除。使用此方法的插件必须使用 Gradle 4.3 编译才能在 Gradle 6.0 上工作。

  • JacocoReportBase 中已移除以下 setter 方法

  • JacocoTaskExtension 上的 append 属性已被移除。对于 Jacoco agent,append 现在总是配置为 true。

  • JacocoPlugin 上的 configureDefaultOutputPathForJacocoMerge 方法已被移除。此方法从未打算公开。

  • ear 插件的 部署描述符文件名 中不再允许包含文件路径。请改用简单名称,例如 application.xml

  • org.gradle.testfixtures.ProjectBuilder 构造函数已被移除。请改用 ProjectBuilder.builder()

  • 启用 增量 Groovy 编译 时,错误的源根配置或为 Groovy 启用 Java 注解现在会导致构建失败。在这些情况下,如果您想进行编译,请禁用增量 Groovy 编译。

  • ComponentSelectionRule 不再能够注入元数据或 ivy 描述符。请改用 ComponentSelection 参数上的方法。

  • 现在,声明一个没有声明输出的增量任务是一个错误。请声明文件输出或改用 TaskOutputs.upToDateWhen()

  • getEffectiveAnnotationProcessorPath() 方法已从 JavaCompileScalaCompile 任务中移除。

  • 在任务开始执行后更改类型为 Property<T> 的任务属性的值,现在会导致错误。

  • isLegacyLayout() 方法已从 SourceSetOutput 中移除。

  • TaskInputs.getProperties() 返回的 map 现在是不可修改的。尝试修改它将导致抛出 UnsupportedOperationException 异常。

  • 孵化中的 capabilities resolution API(在 5.6 中引入)有一些细微的变化,以允许基于 variant 名称进行变体选择

从 5.5 及更早版本升级

弃用

任务开始执行后更改 ConfigurableFileCollection 任务属性的内容

当任务属性的类型为 ConfigurableFileCollection 时,一旦任务开始执行,该属性引用的文件集合将忽略对集合内容的更改。这有两个好处。首先,这防止了任务执行期间意外更改属性值,这可能导致 Gradle 的最新检查和构建缓存查找使用与任务操作所使用的值不同的值。其次,这提高了性能,因为 Gradle 可以计算一次值并缓存结果。

这将在 Gradle 6.0 中成为一个错误。

创建 SignOperation 实例

直接创建 SignOperation 实例现在已被弃用。应改用 SigningExtension 的方法来创建这些实例。

这将在 Gradle 6.0 中成为一个错误。

声明一个没有输出的增量任务

现在,声明一个没有声明输出的增量任务已被弃用。请声明文件输出或改用 TaskOutputs.upToDateWhen()

这将在 Gradle 6.0 中成为一个错误。

方法 WorkerExecutor.submit() 已被弃用

WorkerExecutor.submit() 方法现在已被弃用。现在应该使用新的 noIsolation()classLoaderIsolation()processIsolation() 方法来提交工作。有关使用这些方法的更多信息,请参阅Worker API 的相关章节

WorkerExecutor.submit() 将在 Gradle 8.0 中移除。

潜在的破坏性更改

值是 Property 的任务 @Input 属性现在会遵守任务依赖关系

以前,对于类型为 Property<T> 的任务 @Input 属性,任务依赖关系会被忽略。现在它们得到遵守,因此可以将任务输出属性附加到任务 @Input 属性上。

这可能会在任务依赖关系图中引入意外的循环,即输出属性的值被映射以生成输入属性的值。

使用不表示任务输出的文件 Provider 声明任务依赖关系

以前,可以将不表示任务输出的 Provider<File>Provider<RegularFile>Provider<Directory> 实例传递给 Task.dependsOn()。这些 provider 会被静默忽略。

现在这是一个错误,因为 Gradle 不知道如何构建非任务输出的文件。

注意,当 Provider 是任务带有 @OutputFile@OutputDirectory 注解的属性时,仍然可以将返回文件并表示任务输出的 Provider 传递给 Task.dependsOn(),例如 myTask.dependsOn(jar.archiveFile)myTask.dependsOn(taskProvider.flatMap { it.outputDirectory })

Property 值设置为 null 时使用属性约定

以前,调用 Property.set(null) 总是会将属性的值重置为“未定义”。现在,将使用通过 convention() 方法与属性关联的约定来确定属性的值。

增强对 publishing.publicationspublishing.repositories 名称的验证

仓库和出版物的名称用于构建发布任务的名称。以前可以提供会导致无效任务名称的名称。现在,出版物和仓库的名称限制为 [A-Za-z0-9_\\-.]+

Worker API 类加载器和进程 classpath 受限

Gradle 现在阻止内部依赖项(如 Guava)泄露到 Worker API 操作使用的 classpath 中。这解决了 一个问题,即 worker 需要使用 Gradle 内部也使用的依赖项。

在以前的版本中,可以依赖这些泄露的类。依赖此行为的插件现在将失败。要修复插件,worker 应在其 classpath 中明确包含所有必需的依赖项。

默认 PMD 版本升级到 6.15.0

PMD 插件已升级,默认使用 PMD 6.15.0 版本,而不是 6.8.0。

wreulicke 贡献

配置副本具有唯一名称

以前,配置的所有副本始终具有名称 <OriginConfigurationName>Copy。现在,在创建多个副本时,每个副本都将通过从第二个副本开始添加索引来拥有一个唯一名称。(例如 CompileOnlyCopy2

Eclipse 的 classpath 过滤更改

Gradle 5.6 不再在 Eclipse 模型中提供自定义 classpath 属性。相反,它提供了 Eclipse 测试源的属性。此更改需要 Buildship 3.1.1 或更高版本。

嵌入式 Kotlin 升级到 1.3.41

使用 kotlin-dsl 插件编写的 Gradle Kotlin DSL 脚本和 Gradle 插件现在使用 Kotlin 1.3.41 进行编译。

有关包含的更改的更多信息,请参阅 Kotlin 博客文章更新日志

现在支持的最低 Kotlin Gradle 插件版本是 1.2.31。以前是 1.2.21。

自动能力冲突解决

Gradle 的先前版本在发生能力冲突时会自动选择具有最高能力版本的模块。从 5.6 开始,这是一种可选行为,可以通过以下方式激活

configurations.all {
   resolutionStrategy.capabilitiesResolution.all { selectHighestVersion() }
}

有关更多选项,请参阅文档中的能力章节

文件删除操作不跟随符号链接目录

当 Gradle 由于各种原因需要删除任务的输出文件时,它不会跟随符号链接目录。符号链接本身将被删除,但链接目录的内容将保持不变。

JavaExec 中禁用调试参数解析

Gradle 5.6 引入了一个新的 DSL 元素(JavaForkOptions.debugOptions(Action<JavaDebugOptions>))来配置分叉 Java 进程的调试属性。由于此更改,Gradle 不再解析与调试相关的 JVM 参数。因此,如果为进程指定了 -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 参数,JavaForkOptions.getDebu() 不再返回 true

Scala 2.9 和 Zinc 编译器

Gradle 不再支持使用 Scala 2.9 构建应用程序。

从 5.4 及更早版本升级

弃用

Play

内置的 Play 插件已被弃用,将由插件门户提供的一个新的 Play Framework 插件取代。

构建比较

构建比较插件已被弃用,并将在 Gradle 的下一个主要版本中移除。

构建扫描 (Build scans) 可以更深入地洞察您的构建,您可以使用 Develocity 直接比较两个构建的构建扫描。

潜在的破坏性更改

冲突时可能忽略用户提供的 Eclipse 项目名称

通过 EclipseProject.setName(…​) 配置的项目名称在所有情况下都受到 Gradle 和 Buildship 的尊重,即使这些名称导致冲突和导入/同步错误。

如果这些名称与 Eclipse 工作空间中的其他项目名称冲突,Gradle 现在可以对这些名称进行去重。这可能导致用户指定名称的项目在 Eclipse 中的项目名称发生变化。

即将发布的 Buildship 3.1.1 版本是利用此行为所必需的。

Christian Fränkel 贡献

默认 JaCoCo 版本升级到 0.8.4

JaCoCo 插件已升级,默认使用 JaCoCo 0.8.4 版本,而不是 0.8.3。

Evgeny Mandrikov 贡献

嵌入式 Ant 版本升级到 1.9.14

Gradle 发行的 Ant 版本已从 1.9.13 升级到 1.9.14

类型 DependencyHandler 现在静态暴露 ExtensionAware

这影响了在 dependencies {} 块内使用 ExtensionAware 扩展成员(例如 extra 属性访问器)的 Kotlin DSL 构建脚本。这些成员的接收者将不再是包含它们的 Project 实例,而是 dependencies 对象本身,即最内层符合 ExtensionAware 的接收者。为了在 dependencies {} 内访问 Project 的 extra properties,接收者必须明确限定,即使用 project.extra 而不是仅仅使用 extra。受影响的扩展还包括 the<T>()configure<T>(T.() → Unit)

改进的依赖排除处理

在一些复杂的依赖关系图中,当存在大量排除项时,Gradle 的先前版本可能会产生错误的结果或随机化的依赖顺序。为了缓解这个问题,计算排除项的算法已被重写。在某些极少数情况下,由于正确性更改,这可能会导致解析结果出现一些差异。

改进的 worker 进程 classpath 分离

使用 PROCESS 隔离时,由 Worker API 启动的 worker daemon 的系统 classpath 已缩减到最少的 Gradle 基础设施集。用户代码仍隔离到单独的类加载器中,以使其与 Gradle 运行时隔离。对于使用 worker API 的任务来说,这应该是一个透明的更改,但 Gradle 的先前版本在 worker 进程中混合了用户代码和 Gradle 内部代码。依赖于诸如 java.class.path 系统属性的事物的 worker actions 可能会受到影响,因为 java.class.path 现在仅表示 Gradle 内部的 classpath。

从 5.3 及更早版本升级

弃用

使用自定义本地构建缓存实现

现在,将自定义构建缓存实现用于本地构建缓存已被弃用。将来只允许使用 DirectoryBuildCache 类型。对于将自定义构建缓存实现用作远程构建缓存的支持没有变化。

潜在的破坏性更改

通过 googleApis() 配置 Google Hosted Libraries 时使用 HTTPS

通过 JavaScriptRepositoriesExtension#GOOGLE_APIS_REPO_URL 可访问的 Google Hosted Libraries URL 已更改为使用 HTTPS 协议。此更改也影响通过 googleApis() 配置的 Ivy 仓库。

从 5.2 及更早版本升级

潜在的破坏性更改

平台解析中的 bug 修复

在 Gradle 5.0 到 5.2.1(包含)期间存在一个 bug,强制平台(enforced platforms)可能会包含依赖项而不是约束。只要 POM 文件定义了依赖项和“约束”(通过 <dependencyManagement>),并且您使用了 enforcedPlatform,就会发生这种情况。Gradle 5.3 修复了这个 bug,这意味着如果您依赖了这个错误的行为,解析结果可能会有所不同。类似地,Gradle 5.3 不再尝试下载 platformenforcedPlatform 依赖项的 jar 包(因为它们应该只引入约束)。

自动目标 JVM 版本

如果您应用了任何 Java 插件,Gradle 现在将尽力选择与被编译模块的目标兼容性匹配的依赖项。实际上,这意味着如果模块 A 是为 Java 8 构建的,模块 B 也是为 Java 8 构建的,则没有变化。但是,如果模块 B 是为 Java 9+ 构建的,则不再二进制兼容,Gradle 将会报错,错误消息如下

Unable to find a matching variant of project :producer:
  - Variant 'apiElements' capability test:producer:unspecified:
      - Provides org.gradle.dependency.bundling 'external'
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found value 'java-api-jars'.
  - Variant 'runtimeElements' capability test:producer:unspecified:
      - Provides org.gradle.dependency.bundling 'external'
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found value 'java-runtime-jars'.

通常,这表明您的项目配置错误,并且依赖项不兼容。但是,在某些情况下您可能仍然想这样做,例如当您的模块只有一部分类实际需要 Java 9 依赖项,并且不打算在早期版本上使用时。通常 Java 不鼓励您这样做(您应该拆分您的模块),但如果遇到此问题,您可以通过在消费者端禁用此新行为来解决

java {
   disableAutoTargetJvm()
}

Maven / Ivy 与依赖替换互操作性中的 bug 修复

如果您有一个 Maven 依赖指向一个 Ivy 依赖,并且其 default 配置的依赖项与 compile + runtime + master 配置的依赖项不匹配,并且该 Ivy 依赖被替换了(使用 resolutionStrategy.forceresolutionStrategy.eachDependencyresolutionStrategy.dependencySubstitution),那么此修复将影响您。Gradle 5.0 之前的旧行为仍然存在,并未被改进的 pom 支持引入的更改取代。

Gradle 在 Windows 上存在 junction points 和符号链接时,不再忽略 clean 任务、所有 Delete 任务以及 project.delete {} 操作的 followSymlink 选项。

发布附加构件中的修复

在以前的 Gradle 版本中,在项目级别注册的附加构件不会被 maven-publishivy-publish 发布,除非它们也在出版配置中作为构件添加。

使用 Gradle 5.3,这些构件现在被正确地纳入考虑并发布。

这意味着同时在项目出版物(Ivy 或 Maven)上注册的构件将导致发布失败,因为它会创建重复条目。修复方法是从出版物配置中移除这些构件。

从 5.0 及更早版本升级

弃用

按照 API 链接了解如何处理这些弃用(如果此处未提供额外信息)

  • org.gradle.plugin.devel.tasks.ValidateTaskPropertiesclassesclasspath 的 setter 方法(已移除)

  • ConfigurableFileCollection 这样的延迟属性不应该有 setter 方法。请改用 setFrom。例如,

    validateTaskProperties.getClasses().setFrom(fileCollection)
    validateTaskProperties.getClasspath().setFrom(fileCollection)

潜在的破坏性更改

以下更改以前未弃用

Signing API 更改

Sign 任务的输入和输出文件现在分别通过 Signature.getToSign()Signature.getFile() 进行跟踪。

集合属性默认为空集合

在 Gradle 5.0 中,使用 ObjectFactory 创建的集合属性实例没有定义值,需要插件作者明确设置初始值。这被证明很笨拙且容易出错,因此 ObjectFactory 现在返回初始值为空集合的实例。

Worker API:不再能设置 worker 的工作目录

由于 JDK 11 不再支持更改正在运行进程的工作目录,现在禁止通过 fork options 设置 worker 的工作目录。所有 worker 现在都使用相同的工作目录以实现重用。请改为将文件和目录作为参数传递。有关示例,请参阅Worker API 文档

原生链接任务的更改

为了扩展我们地道的 Provider API 实践,org.gradle.nativeplatform.tasks.LinkSharedLibrary 中的 install name 属性受到此更改的影响。

  • getInstallName() 已更改为返回一个 Property

  • setInstallName(String) 已被移除。请改用 Property.set()

将参数传递给 Windows Resource Compiler

为了扩展我们地道的 Provider API 实践,WindowsResourceCompile 任务已转换为使用 Provider API。

传递附加编译器参数现在遵循与 CppCompile 和其他任务相同的模式。

复制的配置不再与原始配置共享 beforeResolve actions 列表

复制的配置与原始配置之间不再共享 beforeResolve actions 列表。相反,复制的配置在复制时接收 beforeResolve actions 的副本。复制后添加到(任一配置的)任何 beforeResolve actions 将不会在原始配置和复制配置之间共享。这可能会破坏依赖先前行为的插件。

孵化中的 POM 定制类型的更改

  • MavenPomDeveloper.properties 的类型已从 Property<Map<String, String>> 更改为 MapProperty<String, String>

  • MavenPomContributor.properties 的类型已从 Property<Map<String, String>> 更改为 MapProperty<String, String>

指定原生项目操作系统的变更

原生组件上孵化中的 operatingSystems 属性已替换为 targetMachines 属性。

归档任务 (Zip, Jar, War, Ear, Tar) 的变更

扩展 AbstractArchiveTask 的任务的行为变更

AbstractArchiveTask 使用 Provider API 新增了一些属性。扩展这些类型并覆盖基类方法的插件可能不再以相同的方式运行。在内部,AbstractArchiveTask 优先使用新属性,而 `getArchiveName()` 之类的方法是新属性的门面。

如果你的插件/构建仅使用这些类型(并且不扩展它们),则没有任何变化。