配置构建环境是自定义构建过程的强大方式。有多种机制可用。通过利用这些机制,可以使 Gradle 构建更加灵活,并能适应不同的环境和要求。
可用机制
Gradle 提供了多种机制来配置 Gradle 本身和特定项目的行为
机制 | 信息 | 示例 |
---|---|---|
配置构建行为和 Gradle 特性的标志 |
|
|
特定于您的 Gradle 项目的属性 |
|
|
传递给 Gradle 运行时 (JVM) 的属性 |
|
|
配置 Gradle 设置以及执行构建的 Java 进程的属性 |
|
|
基于环境配置构建行为的属性 |
|
配置优先级
配置 Gradle 行为时,可以使用这些方法,但必须考虑它们的优先级。
下表列出了这些方法,按优先级从高到低排列(第一个优先)
优先级 | 方法 | 位置 | 备注 |
---|---|---|---|
1 |
> 命令行 |
标志优先于属性和环境变量 |
|
2 |
> 项目根目录 |
存储在 |
|
3 |
> |
存储在 |
|
4 |
> 环境变量 |
由执行 Gradle 的环境提供 |
以下是指定 JDK 安装目录的所有可能配置,按优先级排序
-
命令行
$ ./gradlew exampleTask -Dorg.gradle.java.home=/path/to/your/java/home --scan
-
Gradle Properties 文件
gradle.propertiesorg.gradle.java.home=/path/to/your/java/home
-
环境变量
$ export JAVA_HOME=/path/to/your/java/home
gradle.properties
文件
Gradle 属性、系统属性和项目属性都可以在 gradle.properties
文件中找到
# Gradle properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.jvmargs=-Duser.language=en -Duser.country=US -Dfile.encoding=UTF-8
# System properties
systemProp.pts.enabled=true
systemProp.log4j2.disableJmx=true
systemProp.file.encoding = UTF-8
# Project properties
kotlin.code.style=official
android.nonTransitiveRClass=false
spring-boot.version = 2.2.1.RELEASE
您可以将 gradle.properties
文件放置在项目的根目录、Gradle 用户主目录(GRADLE_USER_HOME
)或 Gradle 可选安装目录(GRADLE_HOME
)中。
解析属性时,Gradle 首先查找项目级别的 gradle.properties
文件,然后是位于 GRADLE_USER_HOME
中的用户级别的 gradle.properties
文件,最后是位于 GRADLE_HOME
中的 gradle.properties
文件,项目级别属性优先于用户级别和安装级别属性。
项目属性
项目属性特定于您的 Gradle 项目,可用于定制构建。项目属性可以在构建文件中访问,并在执行构建时从外部源传入。在构建脚本中,可以使用 providers.gradleProperty()
惰性获取项目属性。
设置项目属性
您有四种方式添加项目属性,按优先级排序
-
命令行: 您可以通过
-P
命令行选项直接将项目属性添加到您的 Project 对象。$ ./gradlew build -PmyProperty='Hi, world'
-
系统属性: Gradle 为项目属性创建了特定命名的系统属性,您可以使用
-D
命令行标志或gradle.properties
文件设置它们。对于项目属性myProperty
,创建的系统属性名为org.gradle.project.myProperty
。$ ./gradlew build -Dorg.gradle.project.myProperty='Hi, world'
gradle.propertiesorg.gradle.project.myProperty='Hi, world'
-
Gradle Properties 文件: 您也可以在
gradle.properties
文件中设置项目属性。gradle.propertiesmyProperty='Hi, world'
-
环境变量: 您可以使用环境变量设置项目属性。如果环境变量名称类似于
ORG_GRADLE_PROJECT_myProperty='Hi, world'
,则 Gradle 将在您的项目对象上设置一个名为myProperty
的属性,其值为Hi, world
。$ export ORG_GRADLE_PROJECT_myProperty='Hi, world'
这通常是向无人值守构建(例如在 CI 服务器上运行的构建)提供项目属性(尤其是敏感信息)的首选方法。
可以根据调用时指定的项目属性来改变任务的行为。假设您希望确保发布构建仅由 CI 触发。处理此问题的简单方法是使用 isCI
项目属性
tasks.register("performRelease") {
val isCI = providers.gradleProperty("isCI")
doLast {
if (isCI.isPresent) {
println("Performing release actions")
} else {
throw InvalidUserDataException("Cannot perform release outside of CI")
}
}
}
tasks.register('performRelease') {
def isCI = providers.gradleProperty("isCI")
doLast {
if (isCI.present) {
println("Performing release actions")
} else {
throw new InvalidUserDataException("Cannot perform release outside of CI")
}
}
}
$ ./gradlew performRelease -PisCI=true --quiet Performing release actions
请注意,只要您的 gradle.properties
文件包含 isCI=true
,运行 ./gradlew performRelease
将产生相同的结果
isCI=true
$ ./gradlew performRelease --quiet
Performing release actions
系统属性
系统属性是在 JVM 级别设置的变量,Gradle 构建过程可以访问它们。在构建脚本中,可以使用 providers.systemProperty()
惰性获取系统属性。
设置系统属性
您有两种方式添加系统属性,按优先级排序
-
命令行: 使用
-D
命令行选项,您可以将系统属性传递给运行 Gradle 的 JVM。gradle
命令的-D
选项与java
命令的-D
选项效果相同。$ ./gradlew build -Dgradle.wrapperUser=myuser
-
Gradle Properties 文件: 您也可以在
gradle.properties
文件中以systemProp
前缀设置系统属性。gradle.propertiessystemProp.gradle.wrapperUser=myuser
系统属性参考
作为快速参考,以下是常见的系统属性
gradle.wrapperUser=(myuser)
-
指定用户名,以便使用 HTTP 基本认证从服务器下载 Gradle 发行版。
gradle.wrapperPassword=(mypassword)
-
指定密码,以便使用 Gradle wrapper 下载 Gradle 发行版。
gradle.user.home=(directory 路径)
-
指定
GRADLE_USER_HOME
目录。 https.protocols
-
以逗号分隔的格式指定支持的 TLS 版本。例如,
TLSv1.2,TLSv1.3
。
此处列出了更多 Java 系统属性。
在多项目构建中,除根项目外,在任何项目中设置的 systemProp
属性都将被忽略。只有根项目的 gradle.properties
文件会被检查是否包含以 systemProp
开头的属性。
Gradle 属性
Gradle 属性配置 Gradle 本身,通常名称为 org.gradle.\*
。Gradle 属性不应在构建逻辑中使用,其值不应在构建脚本中读取/获取。
设置 Gradle 属性
您有两种方式添加 Gradle 属性,按优先级排序
-
命令行: 使用
-D
命令行选项,您可以传递一个 Gradle 属性$ ./gradlew build -Dorg.gradle.caching.debug=false
-
Gradle Properties 文件: 将这些设置放入
gradle.properties
文件中,并将其提交到您的版本控制系统。gradle.propertiesorg.gradle.caching.debug=false
Gradle 考虑的最终配置是命令行上设置的所有 Gradle 属性和您的 gradle.properties
文件的组合。如果一个选项在多个位置配置,则在这些位置中找到的第一个配置生效
优先级 | 方法 | 位置 | 详情 |
---|---|---|---|
1 |
命令行界面 |
. |
在命令行中使用 |
2 |
|
|
存储在 |
3 |
|
项目根目录 |
存储在项目目录、然后其父项目目录(直到项目的根目录)的 |
4 |
|
|
存储在 |
GRADLE_USER_HOME 的位置可能已经通过命令行传递的 -Dgradle.user.home 系统属性事先更改。 |
Gradle 属性参考
作为参考,以下是常见的 Gradle 属性
org.gradle.caching=(true,false)
-
当设置为
true
时,Gradle 将尽可能重用之前构建的任务输出,从而显著加快构建速度。默认为
false
;构建缓存未启用。 org.gradle.caching.debug=(true,false)
-
当设置为
true
时,每个任务的单个输入属性哈希和构建缓存键将被记录在控制台上。默认为
false
。 org.gradle.configuration-cache=(true,false)
-
启用配置缓存。Gradle 将尝试重用之前构建的配置。
默认为
false
。 org.gradle.configureondemand=(true,false)
-
启用正在孵化中的按需配置,Gradle 将尝试仅配置必要的项目。
默认为
false
。 org.gradle.console=(auto,plain,rich,verbose)
-
定制控制台输出的颜色或详细程度。
默认值取决于 Gradle 的调用方式。
org.gradle.continue=(true,false)
-
如果启用,任务失败后继续执行,否则在任务失败后停止执行。
默认为
false
。 org.gradle.daemon=(true,false)
-
当设置为
true
时,使用 Gradle Daemon 运行构建。默认为
true
。 org.gradle.daemon.idletimeout=(空闲毫秒数)
-
Gradle Daemon 在指定毫秒数空闲后将自行终止。
默认为
10800000
(3 小时)。 org.gradle.debug=(true,false)
-
当设置为
true
时,Gradle 将以启用远程调试的方式运行构建,监听端口 5005。请注意,这相当于在 JVM 命令行中添加-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005
,并将暂停虚拟机直到调试器附加。默认为
false
。 org.gradle.java.home=(JDK home 路径)
-
指定 Gradle 构建过程的 Java home。该值可以设置为
jdk
或jre
位置;但是,根据您的构建做什么,使用 JDK 更安全。这不会影响用于启动Gradle 客户端 VM 的 Java 版本。您也可以使用Daemon JVM 标准来控制运行 Gradle 本身的 JVM。
如果未指定此设置,则默认值从您的环境(
JAVA_HOME
或java
的路径)派生。 org.gradle.jvmargs=(JVM 参数)
-
指定 Gradle Daemon 使用的 JVM 参数。此设置对于配置 JVM 内存设置以提高构建性能特别有用。这不影响 Gradle 客户端 VM 的 JVM 设置。
默认值为
-Xmx512m "-XX:MaxMetaspaceSize=384m"
。 org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)
-
当设置为 quiet、warn、info 或 debug 时,Gradle 将使用此日志级别。这些值不区分大小写。
默认为
lifecycle
级别。 org.gradle.parallel=(true,false)
-
配置后,Gradle 将fork 最多
org.gradle.workers.max
个 JVM,以便并行执行项目。默认为
false
。 org.gradle.priority=(low,normal)
-
指定 Gradle daemon 及其启动的所有进程的调度优先级。
默认为
normal
。 org.gradle.projectcachedir=(目录)
-
指定项目特定的缓存目录。默认为根项目目录中的
.gradle
。默认为
.gradle
。 org.gradle.problems.report=(true|false)
-
启用 (
true
) 或禁用 (false
)build/reports/problems-report.html
的生成。默认为true
。报告包含提供给Problems API的问题。 org.gradle.unsafe.isolated-projects=(true,false)
-
启用项目隔离,这会启用配置缓存。
默认为
false
。 org.gradle.vfs.verbose=(true,false)
-
配置文件系统监控时的详细日志记录。
默认为
false
。 org.gradle.vfs.watch=(true,false)
-
切换文件系统监控。启用后,Gradle 会在构建之间重用收集到的有关文件系统的信息。
在 Gradle 支持此特性的操作系统上,默认为
true
。 org.gradle.warning.mode=(all,fail,summary,none)
-
当设置为
all
、summary
或none
时,Gradle 将使用不同的警告类型显示方式。默认为
summary
。 org.gradle.workers.max=(最大worker进程数)
-
配置后,Gradle 将使用给定数量的最大 worker 数。
默认为 CPU 处理器数量。
环境变量
Gradle 提供了许多环境变量,如下所示。在构建脚本中,可以使用 providers.environmentVariable()
惰性获取环境变量。
设置环境变量
举例说明如何设置 $JAVA_HOME 环境变量
$ set JAVA_HOME=C:\Path\To\Your\Java\Home // Windows
$ export JAVA_HOME=/path/to/your/java/home // Mac/Linux
您可以在构建脚本中使用 System.getenv()
方法将环境变量作为属性访问
task printEnvVariables {
doLast {
println "JAVA_HOME: ${System.getenv('JAVA_HOME')}"
}
}
环境变量参考
gradle
命令可用的环境变量如下
GRADLE_HOME
-
Gradle 的安装目录。
可以用来指定本地 Gradle 版本,而不是使用 wrapper。
您可以将
GRADLE_HOME/bin
添加到您的PATH
中,用于特定的应用和用例(例如测试 Gradle 的早期发布版本)。 JAVA_OPTS
-
用于将 JVM 选项和自定义设置传递给 JVM。
export JAVA_OPTS="-Xmx18928m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dkotlin.daemon.jvm.options=-Xmx6309m"
GRADLE_OPTS
-
指定启动 Gradle 客户端 VM 时使用的 JVM 参数。
客户端 VM 仅处理命令行输入/输出,因此很少需要更改其 VM 选项。
实际构建由 Gradle daemon 运行,它不受此环境变量影响。
GRADLE_USER_HOME
-
指定
GRADLE_USER_HOME
目录,Gradle 在其中存储其全局配置属性、初始化脚本、缓存、日志文件等。如果未设置,默认为
USER_HOME/.gradle
。 JAVA_HOME
-
指定客户端 VM 使用的 JDK 安装目录。
该 VM 也用于 daemon,除非在 Gradle 属性文件中使用
org.gradle.java.home
或使用Daemon JVM 标准指定了不同的 VM。 GRADLE_LIBS_REPO_OVERRIDE
-
默认 Gradle 库仓库的覆盖。
可用于在
org.gradle.plugins.ide.internal.resolver
中指定默认的 Gradle 仓库 URL。如果您的公司使用防火墙/代理,此覆盖很有用,可以指定内部托管的仓库。