编写设置文件 - 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)
}

此类逻辑应在插件中开发。

下一步： 了解如何编写构建脚本 >>

此页面是否有用？