编写 Settings 文件 - Gradle 构建系统

Settings 文件是每个 Gradle 构建的入口点。

在 Gradle 构建生命周期的早期，初始化阶段会在您的项目根目录中找到 settings 文件。

当找到 settings 文件 settings.gradle(.kts) 时，Gradle 会实例化一个 Settings 对象。

Settings 对象的一个目的是允许您声明要包含在构建中的所有项目。

Settings 脚本

Settings 脚本可以是 Groovy 语言的 settings.gradle 文件，也可以是 Kotlin 语言的 settings.gradle.kts 文件。

在 Gradle 为构建组装项目之前，它会创建一个 Settings 实例并对照它执行 settings 文件。

settings 脚本执行时，会配置这个 Settings 对象。因此，settings 文件定义了 Settings 对象。

一个 Settings 实例与一个 settings.gradle(.kts) 文件之间存在一对一的对应关系。

`Settings` 对象

Settings 对象是 Gradle API 的一部分。

在 Groovy DSL 中，Settings 对象的文档位于此处。
在 Kotlin DSL 中，Settings 对象的文档位于此处。

settings 脚本中的许多顶级属性和块都是 Settings API 的一部分。

例如，我们可以在 settings 脚本中使用 Settings.rootProject 属性设置根项目名称

settings.rootProject.name = "application"

通常缩写为

settings.gradle.kts

rootProject.name = "application"

settings.gradle

rootProject.name = 'application'

标准 `Settings` 属性

Settings 对象在您的 settings 脚本中公开了一组标准属性。

下表列出了一些常用属性

名称描述

名称	描述
`buildCache`	构建缓存配置。
`plugins`	已应用于 settings 的插件容器。
`rootDir`	构建的根目录。根目录是根项目的项目目录。
`rootProject`	构建的根项目。
`settings`	返回此 settings 对象。

buildCache

构建缓存配置。

plugins

已应用于 settings 的插件容器。

rootDir

rootProject

构建的根项目。

settings

返回此 settings 对象。

下表列出了一些常用方法

名称描述

名称	描述
`include()`	将给定的项目添加到构建中。
`includeBuild()`	将指定路径下的构建包含到复合构建中。

include()

将给定的项目添加到构建中。

includeBuild()

将指定路径下的构建包含到复合构建中。

Settings 脚本结构

Settings 脚本是对 Gradle API 的一系列方法调用，通常使用 { … }，这是 Groovy 和 Kotlin 语言中的一个特殊快捷方式。{ } 块在 Kotlin 中称为 lambda，在 Groovy 中称为 closure。

简而言之，plugins{ } 块是一个方法调用，其中将 Kotlin lambda 对象或 Groovy closure 对象作为参数传递。它是以下内容的简写形式：

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

块映射到 Gradle API 方法。

函数内部的代码是针对一个 this 对象执行的，该对象在 Kotlin lambda 中称为 receiver，在 Groovy closure 中称为 delegate。Gradle 会确定正确的 this 对象并调用正确的对应方法。方法调用 id("plugin") 对象的 this 的类型是 PluginDependenciesSpec。

settings 文件由基于 DSL 构建的 Gradle API 调用组成。Gradle 逐行、从上到下执行脚本。

让我们看一个例子并分解一下：

settings.gradle.kts

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

plugins {   (2)
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.10.0"
}

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

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

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

settings.gradle

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

plugins {   (2)
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.10.0"
}

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

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

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

1	定义插件的位置
2	应用 settings 插件。
3	定义根项目名称。
4	定义依赖解析策略。
5	将子项目添加到构建中。

1. 定义插件的位置

settings 文件可以使用 pluginManagement 块管理构建的插件版本和仓库。它提供了一种方式来定义项目应使用哪些插件以及应从哪些仓库解析它们。

settings.gradle.kts

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

settings.gradle

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

2. 应用 settings 插件

settings 文件可以选择性地应用插件，这些插件对于配置项目的 settings 是必需的。在下面的示例中，这些插件通常是 Develocity 插件和 Toolchain Resolver 插件。

在 settings 文件中应用的插件只影响 Settings 对象。

settings.gradle.kts

plugins {   (2)
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.10.0"
}

settings.gradle

plugins {   (2)
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.10.0"
}

3. 定义根项目名称

settings 文件使用 rootProject.name 属性定义您的项目名称

settings.gradle.kts

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

settings.gradle

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

每个构建只有一个根项目。

4. 定义依赖解析策略

settings 文件可以选择性地为您的项目定义依赖解析的规则和配置。它提供了一种集中管理和自定义依赖解析的方式。

settings.gradle.kts

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

settings.gradle

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

您也可以在此部分包含版本目录。

5. 将子项目添加到构建中

settings 文件通过使用 include 语句添加所有子项目来定义项目结构

settings.gradle.kts

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

settings.gradle

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

您也可以使用 includeBuild 包含整个构建。

Settings 文件脚本编写

Settings 对象还有更多属性和方法，您可以用来配置您的构建。

重要的是要记住，虽然许多 Gradle 脚本通常以简短的 Groovy 或 Kotlin 语法编写，但 settings 脚本中的每个项目本质上都在调用 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)
}

这种类型的逻辑应该在插件中开发。

下一步：学习如何编写构建脚本 >>

这个页面有用吗？