iT邦幫忙

2021 iThome 鐵人賽

DAY 15
0
Software Development

Gradle 通靈術系列 第 15

第十五天:初探 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 Scan
下一篇
第十六天:複數專案架構
系列文
Gradle 通靈術24
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言