Gradle 提供了多种机制来配置 Gradle 本身和特定项目的行为。
以下是使用这些机制的参考:
机制 | 信息 | 例子 |
---|---|---|
配置构建行为和 Gradle 功能的标志 |
|
|
特定于您的 Gradle 项目的属性 |
|
|
传递到 Gradle 运行时 (JVM) 的属性 |
|
|
配置 Gradle 设置的属性 |
|
|
根据环境配置构建行为的属性 |
|
配置优先级
配置 Gradle 行为时,您可以使用这些方法,但必须考虑它们的优先级。下表按优先级从高到低的顺序列出了这些方法(第一个获胜):
优先事项 | 方法 | 地点 | 例子 | 细节 |
---|---|---|---|---|
1 |
命令行 |
|
它们优先于属性和环境变量。 |
|
2 |
项目根目录 |
|
存储在 |
|
3 |
|
|
存储在 |
|
4 |
环境 |
|
来自执行 Gradle 的环境。 |
项目属性
项目属性特定于您的 Gradle 项目。它们是使用构建脚本中的块或直接在project
对象中定义的。
例如,项目属性myProperty
是在构建文件中创建的:
ext {
myProperty = findProperty('myProperty') ?: 'Hello, world!'
}
println "My property value: ${project.ext.myProperty}"
您有两个选项来添加项目属性,按优先级顺序列出:
-
命令行:您可以通过命令行选项直接向项目
-P
对象添加属性。$ ./gradlew build -PmyProperty='Hi, world'
-
系统属性或环境变量:您可以使用专门命名的系统属性或环境变量来设置项目属性。
$ ./gradlew build -Dorg.gradle.project.myProperty='Hi, world'
如果环境变量名称看起来像,那么 Gradle 将在您的项目对象上设置一个属性,其值为。 Gradle 也支持系统属性,但具有不同的命名模式,看起来像.ORG_GRADLE_PROJECT_prop=somevalue
prop
somevalue
org.gradle.project.prop
以下示例将foo
Project 对象的属性设置为"bar"
。
示例 1:通过命令行设置项目属性。
$ ./gradlew build -Pfoo=bar
示例 2:通过系统属性设置项目属性。
org.gradle.project.foo=bar
示例 3:通过环境变量设置项目属性。
$ export ORG_GRADLE_PROJECT_foo=bar
当您没有持续集成服务器的管理员权限并且需要设置不易可见的属性值时,此功能非常有用。由于您无法-P
在该场景中使用该选项,也无法更改系统级配置文件,因此正确的策略是更改持续集成构建作业的配置,添加与预期模式匹配的环境变量设置。这对于系统上的普通用户来说是不可见的。
您只需使用名称即可访问构建脚本中的项目属性,就像访问变量一样。
系统属性
系统属性是在 JVM 级别设置的变量,可供 Gradle 构建过程访问。可以使用System
构建脚本中的类来访问系统属性。下面列出了常见的系统属性。
您有两个选项来添加按优先级列出的系统属性:
-
命令行:使用
-D
命令行选项,您可以将系统属性传递给运行 Gradle 的 JVM。-D
该命令的选项与该命令的选项gradle
具有相同的效果。-D
java
$ ./gradlew build -Dgradle.wrapperUser=myuser
-
gradle.properties
文件:您还可以在gradle.properties
带有前缀的文件中设置系统属性systemProp
:gradle.propertiessystemProp.gradle.wrapperUser=myuser systemProp.gradle.wrapperPassword=mypassword
以下是常见的系统属性:
gradle.wrapperUser=(myuser)
-
指定用户名以使用 HTTP 基本身份验证从服务器下载 Gradle 发行版。
gradle.wrapperPassword=(mypassword)
-
指定使用 Gradle 包装器下载 Gradle 发行版的密码。
gradle.user.home=(path to directory)
-
指定
GRADLE_USER_HOME
目录。 https.protocols
-
以逗号分隔的格式指定支持的 TLS 版本。例如,
TLSv1.2,TLSv1.3
。
此处列出了其他 Java 系统属性。
在多项目构建中,systemProp
除根项目之外的任何项目中设置的属性都将被忽略。仅gradle.properties
检查根项目的文件中以 开头的属性systemProp
。
以下示例演示了如何使用系统属性:
示例 1:使用文件设置系统属性gradle.properties
:
systemProp.system=gradlePropertiesValue
示例 2:在配置时读取系统属性:
// Using the Java API
println(System.getProperty("system"))
// Using the Java API
println(System.getProperty("system"))
// Using the Gradle API, provides a lazy Provider<String>
println(providers.systemProperty("system").get())
// Using the Java API
println(System.getProperty("system"))
// Using the Gradle API, provides a lazy Provider<String>
println(providers.systemProperty("system").get())
// Using the Java API
println System.getProperty('system')
// Using the Java API
println System.getProperty('system')
// Using the Gradle API, provides a lazy Provider<String>
println providers.systemProperty('system').get()
// Using the Java API
println System.getProperty('system')
// Using the Gradle API, provides a lazy Provider<String>
println providers.systemProperty('system').get()
示例 3:读取系统属性以供执行时使用:
tasks.register<PrintValue>("printProperty") {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue = providers.systemProperty("system")
}
tasks.register('printProperty', PrintValue) {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue = providers.systemProperty('system')
}
示例 4:从命令行设置系统属性-D gradle.wrapperUser=username
:
$ gradle -Dsystem=commandLineValue
等级属性
Gradle 提供了多个选项,可以轻松配置用于执行构建的 Java 进程。虽然可以通过GRADLE_OPTS
或在本地环境中配置这些JAVA_OPTS
,但能够JAVA_HOME
在版本控制中存储某些设置(例如 JVM 内存配置和位置)非常有用,以便整个团队可以在一致的环境中工作。
您有一种选择来添加 gradle 属性:
-
gradle.properties
文件:将这些设置放入gradle.properties
文件中并将其提交到版本控制系统。gradle.propertiesorg.gradle.caching.debug=false
Gradle 考虑的最终配置是命令行和文件上设置的所有 Gradle 属性的组合gradle.properties
。如果在多个位置配置了一个选项,则在以下任何位置找到的第一个选项获胜:
优先事项 | 方法 | 地点 | 细节 |
---|---|---|---|
1 |
命令行界面 |
。 |
在命令行中使用 |
2 |
|
|
存储 |
3 |
|
项目根目录 |
存储在 |
4 |
|
|
存储在可选 Gradle 安装目录 |
的位置可能已通过命令行上传递的系统属性
GRADLE_USER_HOME 预先更改。-Dgradle.user.home |
以下属性是常见的 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=(# of idle millis)
-
Gradle Daemon 将在指定的空闲毫秒数后自行终止。
默认值为
10800000
(3 小时)。 org.gradle.debug=(true,false)
-
当设置为 时
true
,Gradle 将在启用远程调试的情况下运行构建,并侦听端口 5005。请注意,这相当于添加-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005
到 JVM 命令行,并将挂起虚拟机,直到连接调试器。默认为
false
. org.gradle.java.home=(path to JDK home)
-
指定 Gradle 构建过程的 Java 主目录。该值可以设置为 a
jdk
或jre
location;但是,使用 JDK 更安全,具体取决于您的构建用途。这不会影响用于启动Gradle 客户端 VM的 Java 版本。如果未指定设置,则默认值源自您的环境(
JAVA_HOME
或路径)。java
org.gradle.jvmargs=(JVM arguments)
-
指定用于 Gradle 守护程序的 JVM 参数。该设置对于配置 JVM 内存设置以提高构建性能特别有用。这不会影响 Gradle 客户端 VM 的 JVM 设置。
默认为
-Xmx512m "-XX:MaxMetaspaceSize=384m"
. org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)
-
当设置为安静、警告、信息或调试时,Gradle 将使用此日志级别。这些值不区分大小写。
默认为
lifecycle
水平。 org.gradle.parallel=(true,false)
-
配置完成后,Gradle 将分叉多个
org.gradle.workers.max
JVM 来并行执行项目。默认为
false
. org.gradle.priority=(low,normal)
-
指定Gradle 守护进程及其启动的所有进程的调度优先级。
默认为
normal
. org.gradle.projectcachedir=(directory)
-
指定项目特定的缓存目录。默认位于
.gradle
根项目目录中。”默认为
.gradle
. org.gradle.unsafe.isolated-projects=(true,false)
-
启用项目隔离,从而启用配置缓存。
默认为
false
. org.gradle.vfs.verbose=(true,false)
-
在监视文件系统时配置详细日志记录。
默认为
false
. org.gradle.vfs.watch=(true,false)
-
切换监视文件系统。启用后,Gradle 会在构建之间重用其收集的有关文件系统的信息。
默认值是
true
在 Gradle 支持此功能的操作系统上。 org.gradle.warning.mode=(all,fail,summary,none)
-
当设置为
all
、、summary
或时none
,Gradle 将使用不同的警告类型显示。默认为
summary
. org.gradle.workers.max=(max # of worker processes)
-
配置后,Gradle 将使用给定数量的最大工作人员。
默认值是 CPU 处理器的数量。
以下示例演示了如何使用 Gradle 属性。
示例 1:使用文件设置 Gradle 属性gradle.properties
:
gradlePropertiesProp=gradlePropertiesValue
gradleProperties.with.dots=gradlePropertiesDottedValue
示例 2:在配置时读取 Gradle 属性:
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())
// Using Kotlin delegated properties on `settings`
val gradlePropertiesProp: String by settings
println(gradlePropertiesProp)
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())
// Using Kotlin delegated properties on `project`
val gradlePropertiesProp: String by project
println(gradlePropertiesProp)
// Using the API, provides a lazy Provider<String>
println providers.gradleProperty('gradlePropertiesProp').get()
// Using Groovy dynamic names
println gradlePropertiesProp
println settings.gradlePropertiesProp
// Using Groovy dynamic array notation on `settings`
println settings['gradlePropertiesProp']
// Using the API, provides a lazy Provider<String>
println providers.gradleProperty('gradlePropertiesProp').get()
// Using Groovy dynamic names
println gradlePropertiesProp
println project.gradlePropertiesProp
// Using Groovy dynamic array notation on `project`
println project['gradlePropertiesProp']
Kotlin委托属性是 Gradle Kotlin DSL 的一部分。您需要明确指定类型为String
。如果您需要根据属性的存在进行分支,您还可以使用String?
并检查null
.
请注意,如果 Gradle 属性名称中包含点,则不可能使用动态 Groovy 名称。您必须改用 API 或动态数组表示法。
示例 3:读取 Gradle 属性以供执行时使用:
tasks.register<PrintValue>("printProperty") {
// Using the API, provides a lazy Provider<String> wired to a task input
inputValue = providers.gradleProperty("gradlePropertiesProp")
}
tasks.register('printProperty', PrintValue) {
// Using the API, provides a lazy Provider<String> wired to a task input
inputValue = providers.gradleProperty('gradlePropertiesProp')
}
示例 4:从命令行设置 Gradle 属性:
$ gradle -DgradlePropertiesProp=commandLineValue
请注意,初始化脚本无法直接读取 Gradle 属性。最早可以在初始化脚本中读取的 Gradle 属性是settingsEvaluated {}
:
示例 5:从初始化脚本读取 Gradle 属性:
settingsEvaluated {
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())
// Using Kotlin delegated properties on `settings`
val gradlePropertiesProp: String by this
println(gradlePropertiesProp)
}
settingsEvaluated { settings ->
// Using the API, provides a lazy Provider<String>
println settings.providers.gradleProperty('gradlePropertiesProp').get()
// Using Groovy dynamic names
println settings.gradlePropertiesProp
// Using Groovy dynamic array notation on `settings`
println settings['gradlePropertiesProp']
}
子项目目录中的文件中声明的属性gradle.properties
仅适用于该项目及其子项目。
环境变量
Gradle 提供了许多环境变量,如下所示。您可以使用该方法将环境变量作为构建脚本中的属性进行访问System.getenv()
。
以下环境变量可用于该gradle
命令。
GRADLE_HOME
-
Gradle 的安装目录。
可用于指定本地 Gradle 版本,而不是使用包装器。
您可以添加
GRADLE_HOME/bin
到您的PATH
特定应用程序和用例(例如测试 Gradle 的早期版本)。 JAVA_OPTS
-
用于将 JVM 选项和自定义设置传递给 JVM。
GRADLE_OPTS
-
指定启动 Gradle 客户端 VM 时要使用的 JVM 参数。
客户端虚拟机仅处理命令行输入/输出,因此很少需要更改其虚拟机选项。
实际构建由 Gradle 守护进程运行,不受此环境变量的影响。
GRADLE_USER_HOME
-
指定
GRADLE_USER_HOME
Gradle 存储其全局配置属性、初始化脚本、缓存、日志文件等的目录。USER_HOME/.gradle
如果未设置则默认为。 JAVA_HOME
-
指定用于客户端 VM 的 JDK 安装目录。
该 VM 也用于守护进程,除非在 Gradle 属性文件中使用
org.gradle.java.home
. GRADLE_LIBS_REPO_OVERRIDE
-
覆盖默认 Gradle 库存储库。
可用于指定 .gradle 中的默认 Gradle 存储库 URL
org.gradle.plugins.ide.internal.resolver
。如果您的公司使用防火墙/代理,则可用于指定内部托管存储库的有用覆盖。
以下示例演示了如何使用环境变量。
示例1:配置时读取环境变量:
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))
// Using the Gradle API, provides a lazy Provider<String>
println(providers.environmentVariable("ENVIRONMENTAL").get())
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))
// Using the Gradle API, provides a lazy Provider<String>
println(providers.environmentVariable("ENVIRONMENTAL").get())
// Using the Java API
println System.getenv('ENVIRONMENTAL')
// Using the Java API
println System.getenv('ENVIRONMENTAL')
// Using the Gradle API, provides a lazy Provider<String>
println providers.environmentVariable('ENVIRONMENTAL').get()
// Using the Java API
println System.getenv('ENVIRONMENTAL')
// Using the Gradle API, provides a lazy Provider<String>
println providers.environmentVariable('ENVIRONMENTAL').get()
示例2:读取环境变量以供执行时使用:
tasks.register<PrintValue>("printValue") {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue = providers.environmentVariable("ENVIRONMENTAL")
}
tasks.register('printValue', PrintValue) {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue = providers.environmentVariable('ENVIRONMENTAL')
}