编写设置文件 - 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 = "application"

这通常缩短为

settings.gradle.kts

rootProject.name = "application"

settings.gradle

rootProject.name = 'application'

标准 `Settings` 属性

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

下表列出了一些常用属性

名称描述

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

buildCache

构建缓存配置。

plugins

已应用于设置的插件容器。

rootDir

rootProject

构建的根项目。

settings

返回此设置对象。

下表列出了一些常用方法

名称描述

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

include()

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

includeBuild()

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

设置脚本结构

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

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

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

块映射到 Gradle API 方法。

函数内部的代码针对名为 Kotlin lambda 中的receiver 和 Groovy closure 中的delegate 的 this 对象执行。Gradle 确定正确的 this 对象并调用正确的相应方法。方法调用 id("plugin") 对象的 this 类型为 PluginDependenciesSpec。

设置文件由构建在 DSL 之上的 Gradle API 调用组成。Gradle 从上到下逐行执行脚本。

让我们看一个例子并将其分解

settings.gradle.kts

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

plugins {   (2)
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.9.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.9.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	应用设置插件。
3	定义根项目名称。
4	定义依赖项解析策略。
5	将子项目添加到构建中。

1. 定义插件的位置

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

settings.gradle.kts

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

settings.gradle

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

2. 应用设置插件

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

在设置文件中应用的插件仅影响 Settings 对象。

settings.gradle.kts

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

settings.gradle

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

3. 定义根项目名称

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

settings.gradle.kts

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

settings.gradle

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

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

4. 定义依赖项解析策略

设置文件可以选择性地定义规则和配置，用于跨项目进行依赖项解析。它提供了一种集中管理和自定义依赖项解析的方法。

settings.gradle.kts

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

settings.gradle

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

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

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

设置文件通过使用 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 对象上还有许多其他属性和方法，您可以使用它们来配置构建。

重要的是要记住，虽然许多 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)
}

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

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

此页面是否对您有帮助？