第十五天：初探 Gradle properties

为了让 Gradle 在运行的时候可以更弹性，Gradle 支援一系列载入建置环境（Build Environment）的机制，让我们可以动态修改运行时的行为。这些方式的优先率由高至低如下：

1. 指令列参数（Command-line flags）：比方说 --build-cache 这种由使用者透过终端机输入的参数拥有最高优先权，可以覆写属性（Properties）及环境变数（Environment Variable）
2. 系统属性（System properties）：比方说 systemProp.http.proxyHost=somehost.org 这种写在系统等级的 gradle.properties 档案
3. Gradle 属性（Gradle properties）：比方说 org.gradle.caching=true 这种通常写在专案根目录底下的 gradle.properties 档案或是 GRADLE_USER_HOME 的环境变数
4. 环境变数（Environment variables）：比方说 GRADLE_OPTS 这种来自运行 Gradle 时的环境变数

除了设定建置环境外，我们还可以使用专案属性（Project properties）像是 -PreleaseType=final 来设定专案建置。以下就分别讨论一下这些不同的属性设定方式：

系统属性

我们可以用 -D 指令列选项传递一个系统属性给运行 Gradle 的 JVM。使用 -D 传递给 gradle 跟传递给 java 有一样的效果。您也可以使用 systemProp 前缀词在 gradle.properties 里设定系统属性，比方说：

systemProp.gradle.wrapperUser=myuser
systemProp.gradle.wrapperPassword=mypassword

要注意一点的是，当专案是有包含数个子专案结构时，只有父专案（Root Project）的 gradle.properties 支援 systemProp. 前缀词。

Gradle 属性

Gradle 支援透过 gradle.properties 储存在建置时会用到的属性，我们可以将这个档案 Commit 到版本控制系统里方便与团队成员共享。gradle.properties 可以从数个来源取得，Gradle 会将这些属性设定全部汇整後合并计算，计算时的优先顺序为：

1. 直接用 -P 或 --project-prop 从指令列传递过来的属性
2. 在 GRADLE_USER_HOME 资料夹底下的 gradle.properties
3. 在专案根目录底下的 gradle.properties
4. 在 Gradle 安装目录底下的 gradle.properties

我们来看一个实际的范例，假设我们的 gradle.properties 的内容为：

gradlePropertiesProp=gradlePropertiesValue
sysProp=shouldBeOverWrittenBySysProp
systemProp.system=systemValue

而 Build Script 的内容为：

val commandLineProjectProp: String by project
val gradlePropertiesProp: String by project
val systemProjectProp: String by project

tasks.register("printProps") {
    doLast {
        println(commandLineProjectProp)
        println(gradlePropertiesProp)
        println(systemProjectProp)
        println(System.getProperty("system"))
    }
}

当我们执行以下指令时，输出的结果就会像这样：

$ gradle -q -PcommandLineProjectProp=commandLineProjectPropValue \
            -Dorg.gradle.project.systemProjectProp=systemPropertyValue \ 
            printProps

commandLineProjectPropValue
gradlePropertiesValue
systemPropertyValue
systemValue

环境变数

在使用 gradle 指令时，可以取得以下 3 个标准的环境变数。不过要注意一下的是，指令列参数及系统属性的优先权比环境变数高，是可以依照需求覆写的。

1. GRADLE_OPTS：指定当 Gradle 启动时使用的 JVM 参数
2. GRADLE_USER_HOME：指定使用者的 Gradle 家目录，预设的位置是在 $USER_HOME/gradle
3. JAVA_HOME：指定 JDK 的安装位置。这也是 Gradle 指令会用的 JDK，除非在 properties 里的 org.gradle.java.home 有另外覆写

专案属性

我们可以透过 -P 指令列参数来增加 Project 物件的属性。Gradle 也可以在看到特定名称的系统属性或环境变数时设定专案属性。比方说，假如环境变数里有一个名字看起来像 ORG_GRADLE_PROJECT_prop=somevalue，那 Gradle 就在 Project 物件设定一个 prop 的属性且值为 somevalue。Gradle 对系统属性也支援这种机制，只是使用 org.gradle.project.prop 的图样。

这个功能在当您没有 CI 主机的管理员权限，但又需要设定一些不能让一般使用者看到的属性值时非常有用。因为在这样的情况下您不能使用 -P 来设定，也不能修改系统等级的设定档。所以标准作法就是修改 CI 主机建置任务的设定，用这种环境变数图样的变数设定上去，一方面可以让 CI Runner 取得设定值，一方面也让一般使用者无法看到机敏资讯。

参考资料

• Build Environment