撰寫設定檔 - Gradle 繁體中文

設定檔案是每個 Gradle 建置的進入點。

在 Gradle 建置生命週期的早期，初始化階段會在您的專案根目錄中找到設定檔案。

當找到設定檔案 settings.gradle(.kts) 時，Gradle 會實例化一個Settings 物件。

Settings 物件的其中一個目的是讓您宣告要包含在建置中的所有專案。

設定指令碼

設定指令碼是 Groovy 中的 settings.gradle 檔案或 Kotlin 中的 settings.gradle.kts 檔案。

在 Gradle 組合建置的專案之前，它會建立一個 Settings 實例，並針對它執行設定檔案。

當設定指令碼執行時，它會設定這個 Settings。因此，設定檔案定義了 Settings 物件。

一個 Settings 實例和一個 settings.gradle(.kts) 檔案之間是一對一的對應關係。

`Settings` 物件

Settings 物件是Gradle API 的一部分。

在 Groovy DSL 中，Settings 物件文件檔在此處找到。
在 Kotlin DSL 中，Settings 物件文件檔在此處找到。

設定指令碼中的許多頂層屬性和區塊都是 Settings API 的一部分。

例如，我們可以使用 Settings.rootProject 屬性在設定指令碼中設定根專案名稱

settings.rootProject.name = "root"

通常會縮寫為

rootProject.name = "root"

標準 `Settings` 屬性

Settings 物件會在您的設定指令碼中公開一組標準屬性。

下表列出幾個常用的屬性

名稱說明

名稱	說明
`buildCache`	建置快取設定。
`plugins`	已套用至設定的外掛容器。
`rootDir`	建置的根目錄。根目錄是根專案的專案目錄。
`rootProject`	建置的根專案。
`settings`	傳回此設定物件。

buildCache

建置快取設定。

plugins

已套用至設定的外掛容器。

rootDir

rootProject

建置的根專案。

settings

傳回此設定物件。

下表列出幾個常用的方法

名稱說明

名稱	說明
`include()`	將指定的專案新增至建置。
`includeBuild()`	將指定路徑的建置納入複合建置。

include()

將指定的專案新增至建置。

includeBuild()

將指定路徑的建置納入複合建置。

設定指令碼結構

設定指令碼是一系列對 Gradle API 的方法呼叫，通常會使用 { … }，這是 Groovy 和 Kotlin 語言中的特殊捷徑。{ } 區塊在 Kotlin 中稱為「lambda」，在 Groovy 中稱為「閉包」。

簡單來說，plugins{ } 區塊是一個方法呼叫，其中會將 Kotlin lambda 物件或 Groovy 閉包物件傳遞為引數。這是下列程式碼的簡寫形式

plugins(function() {
    id("plugin")
})

區塊會對應到 Gradle API 方法。

函式內部的程式碼會針對一個稱為 接收器（在 Kotlin lambda 中）或委派（在 Groovy 閉包中）的 this 物件執行。Gradle 會判斷正確的 this 物件，並呼叫正確的對應方法。方法呼叫 id("plugin") 的 this 物件屬於 PluginDependenciesSpec 類型。

設定檔案是由建立在 DSL 之上的 Gradle API 呼叫組成。Gradle 會逐行執行指令碼，由上而下。

我們來看一個範例並加以分析

settings.gradle.kts

pluginManagement {                                          (1)
    repositories {
        gradlePluginPortal()
        google()
    }
}

plugins {                                                   (2)
    id("org.gradle.toolchains.fake") version "0.6.0"
}

rootProject.name = "root-project"                           (3)

dependencyResolutionManagement {                            (4)
    repositories {
        mavenCentral()
    }
}

include("sub-project-a")                                    (5)
include("sub-project-b")
include("sub-project-c")

1	定義外掛的位置
2	套用外掛。
3	定義根專案名稱。
4	定義建置範圍存放庫。
5	將子專案新增至建置。

settings.gradle

pluginManagement {                                          (1)
    repositories {
        gradlePluginPortal()
        google()
    }
}

plugins {                                                   (2)
    id 'org.gradle.toolchains.fake' version '0.6.0'
}

rootProject.name = 'root-project'                           (3)

dependencyResolutionManagement {                            (4)
    repositories {
        mavenCentral()
    }
}

include('sub-project-a')                                    (5)
include('sub-project-b')
include('sub-project-c')

1	定義外掛的位置。
2	套用外掛。
3	定義根專案名稱。
4	定義建置範圍存放庫。
5	將子專案新增至建置。

1. 定義外掛的位置

設定檔可以選擇使用 pluginManagement 來定義專案使用的外掛，包括二進位儲存庫，例如 Gradle 外掛入口網站或使用 includeBuild 的其他 Gradle 建置

pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
    }
}

您也可以在此區塊中包含外掛和外掛相依性解析策略。

2. 套用外掛

設定檔可以選擇宣告稍後可能會套用的外掛，這可以在多個建置/子專案之間新增共用設定

套用至設定檔的外掛只會影響 Settings 物件。

plugins {
    id("org.gradle.toolchains.fake") version "0.6.0"
}

這通常用於確保所有子專案使用相同的外掛版本。

3. 定義根專案名稱

設定檔使用 rootProject.name 屬性來定義專案名稱

rootProject.name = "root-project"

每個建置只有一個根專案。

4. 定義建置範圍儲存庫

設定檔可以選擇使用 repositories 定義專案依賴的元件位置（以及如何解析這些元件），例如 Maven Central 等二進位儲存庫和/或使用 includeBuild 的其他 Gradle 建置

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

您也可以在此區段中包含版本目錄。

5. 將子專案新增至建置

設定檔使用 include 陳述來新增所有子專案，定義專案結構

include("app")
include("business-logic")
include("data-model")

設定檔指令碼

Settings 物件上有許多其他屬性和方法，您可以使用它們來設定建置。

重要的是要記住，雖然許多 Gradle 指令碼通常以簡短的 Groovy 或 Kotlin 語法撰寫，但設定檔指令碼中的每個項目基本上都在呼叫 Gradle API 中 Settings 物件上的方法

include("app")

實際上是

settings.include("app")

此外，Groovy 和 Kotlin 語言的完整功能都可以使用。

例如，您可以反覆運算專案根資料夾中的目錄清單並自動包含它們，而不是多次使用 include 來新增子專案

rootDir.listFiles().filter { it.isDirectory && (new File(it, "build.gradle.kts").exists()) }.forEach {
    include(it.name)
}

這種類型的邏輯應該在外掛中開發。

下一步： 了解如何撰寫 Build 腳本 >>

此頁面有幫助嗎？