Gradle 发行说明

升级说明

通过更新项目中的 wrapper，将您的构建切换为使用 Gradle 8.13

./gradlew wrapper --gradle-version=8.13 && ./gradlew wrapper

请参阅 Gradle 8.x 升级指南，了解有关升级到 Gradle 8.13 时的弃用、重大更改和其他注意事项。

有关 Java、Groovy、Kotlin 和 Android 兼容性，请参阅完整的兼容性说明。

新功能和可用性改进

工具链支持

Gradle 的 工具链支持 允许配置和选择构建项目（编译代码、运行测试等）和运行 Gradle 本身所需的 JDK 版本。

守护进程工具链自动配置

自 Gradle 8.8 以来，用户可以通过配置 守护进程 JVM 标准，为构建项目指定与运行 Gradle 不同的 JVM。
Gradle 首先尝试从已安装的版本中查找兼容的 Java 工具链——此过程称为 守护进程 JVM 自动检测。

随着 守护进程 JVM 自动配置 的引入，当本地找不到匹配的 Java 工具链时，Gradle 现在还可以下载匹配的 Java 工具链。

运行 updateDaemonJvm 任务会生成 gradle/gradle-daemon-jvm.properties 文件，该文件现在包含所需 JDK 的下载 URL

toolchainUrl.LINUX.AARCH64=https\://server.com/jdk
toolchainUrl.LINUX.X86_64=https\://server.com/jdk
...
toolchainVendor=adoptium
toolchainVersion=17

如果已安装的 JDK 均不匹配指定的版本或供应商，Gradle 将自动下载所需的版本

IntelliJ IDEA 支持从 2025.1 EAP 或更高版本开始提供，并在“设置”菜单中包含可配置的值

要启用自动配置，需要最新版本的 foojay 插件（或自定义实现）

plugins {
    // Apply the foojay-resolver plugin to allow automatic download of JDKs
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.9.0"
}

一旦应用插件，运行 updateDaemonJvm 任务

./gradlew updateDaemonJvm --jvm-version=17 --jvm-vendor=adoptium

使用 JDK 下载信息填充 gradle/gradle-daemon-jvm.properties

toolchainUrl.LINUX.AARCH64=https\://api.foojay.io/disco/v3.0/ids/ff8d269e2495c538cfa04b4b52d22286/redirect
toolchainUrl.LINUX.X86_64=https\://api.foojay.io/disco/v3.0/ids/4dfe7aab2abf71db71537e9dca36c154/redirect
...
toolchainVendor=adoptium
toolchainVersion=17

已解析的平台和 URL 是可自定义的。有关更多详细信息，请参阅 守护进程 JVM 标准文档。

scala 扩展中显式的 Scala 版本声明

Scala 插件 提供对 Scala 项目的编译、测试和打包的支持。

从此版本的 Gradle 开始，当应用 scala-base 或 scala 插件时，您现在可以在 scala 扩展上显式声明 Scala 版本。这允许 Gradle 自动解析所需的 Scala 工具链依赖项，从而无需用户手动声明它们。它还消除了从生产运行时类路径推断 Scala 版本的需要，而这种方法很容易出错。

现在，您可以在 scala 扩展中显式设置 Scala 版本，并且不再需要 scala-library 依赖项

plugins {
    id("scala")
}

repositories {
    mavenCentral()
}

scala {
    scalaVersion = "2.13.12"
    // OR 
    scalaVersion = "3.6.3"
}

以前，您必须声明 scala-library 依赖项，如下所示

plugins {
    id("scala")
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.scala-lang:scala-library:2.13.12")
    // OR
    implementation("org.scala-lang:scala3-library_3:3.6.3")
}

有关使用 Scala 插件的更多详细信息，请参阅文档。

JUnit XML 时间戳中的额外精度

Gradle 提供对运行 JUnit 测试和生成详细报告的内置支持。由 test 任务生成的 JUnit XML 报告 现在在测试事件时间戳中包含毫秒精度

<testsuite name="ExampleTest" tests="1" failures="0" errors="0" timestamp="2024-02-03T12:34:56.789" time="1.234">
    <testcase name="testExample" classname="com.example.ExampleTest" time="1.234">
    </testcase>
</testsuite>

此更改提高了分析测试执行时间的准确性，尤其是在精确计时至关重要的环境中。

有关 Gradle 中 JUnit 测试报告的更多详细信息，请参阅 JVM 项目中的测试。

构建编写改进

Gradle 为插件作者和构建工程师提供了 丰富的 API，以开发自定义构建逻辑。

ProjectLayout API 改进

ProjectLayout 类提供对项目中目录和文件的访问。从此版本的 Gradle 开始，它还可以访问 settings 目录（settings.gradle(.kts) 文件的位置）。

虽然 settings 目录不是任何项目特有的，但某些用例需要解析相对于它的文件路径

val versionFile = layout.settingsDirectory.file("version.txt")

以前，访问 settings 目录需要使用 rootProject.layout.projectDirectory。这种方法涉及访问 rootProject 对象，这是不鼓励的，然后手动解析到 settings 目录的路径

val versionFile = rootProject.layout.projectDirectory.file("version.text")

新功能解决了常见场景：解析在构建中所有项目之间共享的文件，例如根文件夹中的 linting 配置或 version.txt 文件。

有关更多详细信息，请参阅 ProjectLayout.getSettingsDirectory()。

新的 artifactTransforms 报告任务

构件转换 在依赖项解析过程中修改或转换依赖项的构件。

新的 artifactTransforms 任务可用，提供有关项目中所有已注册 构件转换 的信息。

该任务生成的报告帮助构建作者识别构建脚本和插件在其项目中注册的转换。查看已注册转换的列表对于调试 不明确的转换失败 特别有用。

该报告包括以下详细信息

• 实现转换的操作的完全限定类型名称
• 转换是否可缓存
• 用于选择转换的完整输入属性集及其值
• 转换生成的完整输出属性集及其值

有关更多信息，请参阅 ArtifactTransformsReportTask DSL 参考。

TestEventReporting API 改进

Gradle 提供 HTML 测试报告，以帮助您了解和解决测试失败问题。当将 test 任务与支持的测试框架（例如 JUnit）一起使用时，会自动生成此报告。

插件作者和平台提供商现在可以利用 Test Event Reporting API 来捕获测试事件并为在 Gradle 内置测试基础设施之外执行的测试生成报告

public abstract class CustomTest extends DefaultTask {

    @Inject
    protected abstract ProjectLayout getLayout();
    
    @Inject
    protected abstract TestEventReporterFactory getTestEventReporterFactory();

    @TaskAction
    void runTests() {
        try (TestEventReporter test = getTestEventReporterFactory().createTestEventReporter(
                "custom-test",
                getLayout().getBuildDirectory().dir("test-results/custom-test").get(),
                getLayout().getBuildDirectory().dir("reports/tests/custom-test").get()
        )) {
            // Start the test
            test.started(Instant.now());

            // Execute custom test...
            
            // Report test outcome
            if (testFailureCount > 0) {
                test.failed(Instant.now());
            } else {
                test.succeeded(Instant.now());
            }
        }
    }
}

这种集成允许自定义测试框架生成与 Gradle 内置报告格式一致的丰富 HTML 测试报告，从而增强可见性和可用性。

您可以在 Test Reporting API 中找到更多详细信息和示例代码。

以下部分重点介绍此 API 的两个关键功能。

元数据支持

自定义测试可以包含元数据，以提供有关测试执行的补充信息。

元数据显示在 HTML 测试报告中，以提高可见性

test.metadata(Instant.now(),"Parent class:", String.valueOf(result.getTestIdentifier().getParentId().get()));

嵌套支持

支持分层嵌套以逻辑方式分组测试套件和单个测试。这确保了详细且结构化的报告，以及范围限定到每个级别的丰富元数据

try (GroupTestEventReporter outer = root.reportTestGroup("OuterNestingSuite")) {
    outer.started(Instant.now());
        try (GroupTestEventReporter inner = root.reportTestGroup("InnerNestingSuite")) {
            inner.started(Instant.now());
            try (TestEventReporter test = inner.reportTest("nestedTest", "nestedTest()")) {
                test.started(Instant.now());
                test.succeeded(Instant.now());
            }
            inner.succeeded(Instant.now());
    }
    outer.succeeded(Instant.now());
}

嵌套事件反映在 HTML 测试报告中，提供清晰的可追溯性。

用于自定义分发的新 distribution-base 插件

Distribution Plugin 简化了项目二进制文件、脚本和其他资源的打包和分发。它创建一个包含指定项目输出的可分发归档文件（ZIP 或 TAR），并提供用于组装和安装分发的任务。

Gradle 现在包含一个 distribution-base 插件，该插件镜像了 Distribution Plugin 的功能，但不添加默认分发。相反，现有的 distribution 插件充当 distribution-base 插件的包装器，添加默认的 main 分发。

对于想要 Distribution Plugin 的功能但不需要 main 分发的插件开发者来说，distribution-base 插件特别有用

plugins {
    id("distribution-base")
}

distributions {
    create("custom") {
        distributionBaseName = "customName"
        contents {
            from("src/customLocation")
        }
    }
}

有关更多详细信息，请参阅 Distribution Plugin 文档。

已提升的功能

已提升的功能是在以前版本的 Gradle 中处于孵化阶段，但现在已受支持并受向后兼容性约束的功能。有关更多信息，请参阅用户手册中有关“功能生命周期”的部分。

以下是在此 Gradle 版本中已提升的功能。

Tooling API 中已提升的功能

Tooling API 是一种接口，允许外部工具（例如 IDE）与 Gradle 构建进行交互和控制。

用于异步发送数据到客户端的 API，其中包括 BuildActionExecuter.setStreamedValueListener(StreamedValueListener) 方法、StreamedValueListener 类型和 BuildController.send(Object) 方法已提升为稳定版本。

强类型 dependencies 代码块 API

在 Gradle 7.6 中引入的 强类型 dependencies 代码块 API 现在部分稳定。版本目录依赖项仍在审查中，可能会有潜在更改。

Dependencies API 使插件作者能够创建自定义 DSL 样式的 dependencies 代码块，类似于构建脚本中的顶级 dependencies 代码块。

已修复的问题

已知问题

已知问题是在此版本发布后发现的、与此版本中所做的更改直接相关的问题。

外部贡献

我们很高兴收到 Gradle 社区的贡献。有关贡献的信息，请参阅 gradle.org/contribute。

问题报告

如果您发现此版本存在问题，请在 GitHub Issues 上提交错误报告，并遵守我们的问题准则。如果您不确定是否遇到了错误，请使用论坛。

我们希望您能通过 Gradle 构建幸福，我们期待您通过 Twitter 或 GitHub 提供反馈。