Gradle

Gradle 构建运行程序运行 Gradle 项目。

要使用 Gradle 运行构建，所有代理机器上都必须安装 Gradle 0.9-rc-1 或更高版本。或者，如果您使用 Gradle wrapper，您需要在您的版本控制中检入正确配置的 Gradle Wrapper 脚本。

运行器支持所有 Gradle 构建配置，包括 build.gradle 和 build.gradle.kts。

Gradle 参数

选项	描述
Gradle 任务	指定由空格分隔的 Gradle 任务名称。例如， `:myproject:clean :myproject:build` 或 `clean build`。如果此字段留空，则使用 'default' 任务。请注意，TeamCity 目前支持使用 Gradle 构建 Java 项目。构建 Groovy ，Scala 等其他项目尚未经过测试。
Gradle 构建文件	一条通往 Gradle 构建文件的路径，相对于工作目录。如果为空（默认），Gradle 使用自己的设置来确定它。
增量构建	TeamCity 可以利用 Gradle 的 `:buildDependents` 功能。如果启用了增量构建选项，TeamCity 将检测到受构建中更改影响的 Gradle 模块，并仅为这些模块启动 `:buildDependents` 命令。这将导致 Gradle 完全构建并只测试受更改影响的模块。
Gradle 主目录路径	在此指定 Gradle 主目录的路径（ `bin` 目录的父目录）。如果未指定，TeamCity 将使用代理的 `GRADLE_HOME` 环境变量中指定的 Gradle。如果您的代理上没有安装 Gradle，您可以改用 Gradle wrapper。
附加的 Gradle 命令行参数	可选地，指定要传递给 Gradle 的以空格分隔的命令行参数列表。
Gradle Wrapper	如果启用，TeamCity 将在签出目录中查找 Gradle Wrapper 脚本，并使用上述字段指定的 Gradle 任务和额外的命令行参数来启动相应的脚本。在这种情况下，Gradle home path 中指定的 Gradle 和代理上安装的 Gradle 将被忽视。

运行参数

选项	描述
调试	选择记录调试信息复选框等同于添加 `-d` Gradle命令行参数。使用 `DEBUG` 日志级别运行 Gradle 可能会在构建日志中暴露敏感信息（在 Gradle 文档中了解更多信息）。在启用此模式之前，请确保只有受信任的用户才能查看日志。
堆栈跟踪	选择 Print stacktrace 复选框等同于添加 `-s` Gradle 命令行参数。

Java 参数

选项	描述
JDK	选择一个 JDK。本节详述了可用的选项。默认值为 `JAVA_HOME` 环境变量或代理自身的 Java。
JDK 主目录路径	当上方选择了 <Custom> 时，此选项便可用。使用此字段来指定用于运行构建的自定义 JDK 的路径。如果该字段为空，则会从代理机器的 `JAVA_HOME` 环境变量或在构建代理配置文件（ `buildAgent.properties` ）中指定的 `env.JAVA_HOME` 属性读取JDK Home的路径。如果这些值未被指定，TeamCity 将使用构建代理进程本身的 Java home。
JVM 命令行参数	附加的 JVM 命令行参数允许您设置初始和最大堆大小，启用额外的日志记录，选择所需的字节码验证器模式等等。您可以指定标准的（例如以 `-` 开始，例如 `-verbose：[class\|module\|gc\|jni]` 或 `--dry-run` ）和非标准的（例如以 `-X` 开始，例如 `-Xmx<size>` 或 `-XstartOnFirstThread` ）JVM 选项。要指定多个命令行参数，使用空格作为分隔符。例如： -verbose:gc -Xdiag -Xcomp -Xmx512m -Xms256m

选项

描述

JDK

选择一个 JDK。本节详述了可用的选项。默认值为 JAVA_HOME 环境变量或代理自身的 Java。

JDK 主目录路径

当上方选择了 <Custom> 时，此选项便可用。使用此字段来指定用于运行构建的自定义 JDK 的路径。如果该字段为空，则会从代理机器的 JAVA_HOME 环境变量或在构建代理配置文件（ buildAgent.properties ）中指定的 env.JAVA_HOME 属性读取JDK Home的路径。如果这些值未被指定，TeamCity 将使用构建代理进程本身的 Java home。

JVM 命令行参数

附加的 JVM 命令行参数允许您设置初始和最大堆大小，启用额外的日志记录，选择所需的字节码验证器模式等等。

您可以指定标准的（例如以 - 开始，例如 -verbose：[class|module|gc|jni] 或 --dry-run ）和非标准的（例如以 -X 开始，例如 -Xmx<size> 或 -XstartOnFirstThread ）JVM 选项。

要指定多个命令行参数，使用空格作为分隔符。例如：

-verbose:gc -Xdiag -Xcomp -Xmx512m -Xms256m

构建属性

在 Gradle 构建中，TeamCity 系统属性与 Java 系统属性不同。

常规的 Java 系统属性可以全局访问。使用 System.getProperty("my.property") 或 providers.systemProperty("my.property").get() 方法获取这些属性的值。
TeamCity 系统属性在构建初始化时写入到 Project 对象中。因此，只要 Project（项目） 可用，就可以在任何地方访问 TeamCity 系统属性（使用 project.hasProperty("property.name") 检查所需属性是否可用）。

参考 TeamCity 系统属性的推荐方式如下：

task printProperty {
    doLast {
        println "${teamcity['teamcity.build.id']}"
    }
}

tasks.register("printProperty") {
    doLast {
        val teamcity: Map<*,*> by project
        println("${teamcity["teamcity.build.id"]}")
    }
}

或者如果系统属性的名称是合法的名称标识符（例如， system.myPropertyName = myPropertyValue）：

task printProperty {
     doLast {
          println "$myPropertyName"
     }
}

tasks.register("printProperty") {
    doLast {
        val myPropertyName: String by project
        println("$myPropertyName")
    }
}

Docker 设置

在这个部分，您可以指定一个将被用于运行构建步骤的 Docker 镜像。

Code Coverage（代码覆盖率）

Gradle 构建运行程序支持基于 IDEA 代码覆盖率引擎和 JaCoCo 的代码覆盖率。

配置缓存

从2024.03版本开始，TeamCity Gradle runner 支持 configuration cache。此功能通过缓存配置阶段的结果并在后续构建中重用此缓存，显著提高了构建性能。

如果满足以下任何一种情况，配置缓存就会被启用：

参数 --configuration-cache 已添加到运行器的 额外的 Gradle 命令行参数 字段中。
一个 gradle.properties 文件包括 org.gradle.configuration-cache=true （适用于 Gradle 8.1+）或 org.gradle.unsafe.configuration-cache=true （适用于旧版 Gradle）行。这既适用于项目的 gradle.properties 文件，也适用于 GRADLE_USER_HOME 目录中的文件。

当前限制和已知问题

在以下情况下，Gradle 配置缓存可能无法按预期工作：

如果虚拟构建（在并行测试或 Matrix Build 运行期间生成的那些）的运行顺序与创建缓存时的顺序不同。请参阅此 YouTrack 工单以获取更多信息：TW-86556。
如果 Clean Checkout（干净签出）已启用；
如果构建步骤在 Docker 或 Podman 容器内运行；
如果 Gradle 忽略配置缓存问题。
如果附加命令行参数列表包含了 Gradle Tooling API 不支持的参数（ --daemon、 --停止 等等）。

构建参数其值始终会在每次构建中变化（例如， build.id 或 build.number ），只会在需要时加载。您仍然可以使用直接引用（例如， project.teamcity["build.number"] ）来获取这些属性的值，但是 findProperty() 方法（ project.findProperty("build.number") ）不会产生任何结果。如果您需要在您的 Gradle 脚本中调用此方法，请使用以下解决方案：

创建一个新的配置参数，并将其映射到受影响的参数： MyBuildNumber=%build.number%。
创建一个新的系统属性，将其映射到您的新配置参数： system.buildNumber = %MyBuildNumber%。
在您的 Gradle 脚本中，使用 ${findProperty}("buildNumber")} 语法来获取所需的值。

请注意，这种解决方法会阻止您的构建配置重用配置缓存，因此，您可能还希望将其禁用。

最后修改日期： 16日 7月 2024年