Settings

目录

组装多项目构建
在 Settings 文件中使用 Settings
属性
方法
脚本块
属性详情
方法详情
API 文档Settings

声明实例化和配置参与构建的 Project 实例层级结构所需的配置。

一个 Settings 实例与一个 settings.gradle settings 文件一一对应。在 Gradle 组装构建项目之前，它会创建一个 Settings 实例并对其执行 settings 文件。

组装多项目构建

Settings 对象的一个目的是允许您声明要包含在构建中的项目。您可以使用 Settings.include(java.lang.String[]) 方法将项目添加到构建中。构建中始终包含一个根项目。在创建 Settings 对象时会自动添加该项目。根项目的名称默认为包含 settings 文件的目录名称。根项目的项目目录默认为包含 settings 文件的目录。

当项目包含在构建中时，会创建一个 ProjectDescriptor。您可以使用此描述符更改项目的几个属性的默认值。

在 Settings 文件中使用 Settings

动态属性

除了此接口的属性之外，Settings 对象还向 settings 脚本提供一些额外的只读属性。这包括来自以下来源的属性：

  • 定义在构建 settings 目录中的 gradle.properties 文件中。
  • 定义在用户 .gradle 目录中的 gradle.properties 文件中。
  • 使用 -P 选项在命令行提供。

属性

属性描述
buildCache

构建缓存配置。

caches
孵化中

用户主目录中缓存的配置。

extensions

扩展容器。

gradle

当前构建的 Gradle 实例。

pluginManager

此插件感知对象的插件管理器。

plugins

已应用于此对象的插件容器。

rootDir

构建的根目录。根目录是根项目的项目目录。

rootProject

构建的根项目。

settings

返回此 settings 对象。

settingsDir

构建的 settings 目录。settings 目录是包含 settings 文件的目录。

startParameter

用于调用此 Gradle 实例的参数集。

方法

方法描述
apply(closure)

应用零个或多个插件或脚本。

apply(options)

应用插件或脚本，使用 map 形式提供的给定选项。如果插件已应用，则不执行任何操作。

apply(action)

应用零个或多个插件或脚本。

buildCache(action)

配置构建缓存。

caches(cachesConfiguration)
孵化中

配置用户主目录中缓存的设置。

findProject(projectDir)

返回具有给定项目目录的项目。

findProject(path)

返回具有给定路径的项目。

include(projectPaths)

将给定项目添加到构建中。所提供列表中的每个路径都被视为要添加到构建中的项目的路径。请注意，这些路径不是文件路径，而是指定新项目在项目层级结构中的位置。因此，提供的路径必须使用 ':' 字符作为分隔符（而不是 '/'）。

include(projectPaths)

将给定项目添加到构建中。所提供列表中的每个路径都被视为要添加到构建中的项目的路径。请注意，这些路径不是文件路径，而是指定新项目在项目层级结构中的位置。因此，提供的路径必须使用 ':' 字符作为分隔符（而不是 '/'）。

includeBuild(rootProject)

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

includeBuild(rootProject, configuration)

在指定路径包含一个构建到复合构建中，并应用提供的配置。

includeFlat(projectNames)

将给定项目添加到构建中。所提供列表中的每个名称都被视为要添加到构建中的项目名称。

includeFlat(projectNames)

将给定项目添加到构建中。所提供列表中的每个名称都被视为要添加到构建中的项目名称。

project(projectDir)

返回具有给定项目目录的项目。

project(path)

返回具有给定路径的项目。

脚本块

无脚本块

属性详情

BuildCacheConfiguration buildCache (只读)

构建缓存配置。

CacheConfigurations caches (只读)

注意：此属性处于孵化阶段，可能会在 Gradle 的未来版本中更改。

用户主目录中缓存的配置。

ExtensionContainer extensions (只读)

扩展容器。

Gradle gradle (只读)

当前构建的 Gradle 实例。

PluginManager pluginManager (只读)

此插件感知对象的插件管理器。

PluginContainer plugins (只读)

已应用于此对象的插件容器。

虽然未弃用，但推荐使用此接口的方法或 PluginAware.getPluginManager()，而不是直接使用插件容器。

使用此接口或 PluginAware.getPluginManager() 上的 'apply' 方法之一来应用插件，而不是通过插件容器应用。

使用 PluginManager.hasPlugin(java.lang.String) 或类似方法查询插件的应用情况，而不是通过插件容器查询。

File rootDir (只读)

构建的根目录。根目录是根项目的项目目录。

ProjectDescriptor rootProject (只读)

构建的根项目。

Settings settings (只读)

返回此 settings 对象。

File settingsDir (只读)

构建的 settings 目录。settings 目录是包含 settings 文件的目录。

StartParameter startParameter (只读)

用于调用此 Gradle 实例的参数集。

方法详情

void apply(Closure closure)

应用零个或多个插件或脚本。

给定的闭包用于配置一个 ObjectConfigurationAction，它“构建”插件应用。

此方法与 PluginAware.apply(java.util.Map) 的区别在于它允许多次调用配置 action 的方法。

void apply(Map<String, ?> options)

应用插件或脚本，使用 map 形式提供的给定选项。如果插件已应用，则不执行任何操作。

给定的 map 将作为一系列方法调用应用于新创建的 ObjectConfigurationAction。也就是说，map 中的每个 key 都应是 ObjectConfigurationAction 的方法名，而 value 则应是该方法的兼容参数。

可用选项如下：

  • from：要应用的脚本。接受 Project.uri(java.lang.Object) 支持的任何路径。
  • plugin：要应用的插件的 id 或实现类。
  • to：目标委托对象。默认是此插件感知对象。使用此项配置此对象之外的其他对象。

void apply(Action<? super ObjectConfigurationAction> action)

应用零个或多个插件或脚本。

给定的闭包用于配置一个 ObjectConfigurationAction，它“构建”插件应用。

此方法与 PluginAware.apply(java.util.Map) 的区别在于它允许多次调用配置 action 的方法。

void buildCache(Action<? super BuildCacheConfiguration> action)

配置构建缓存。

void caches(Action<? super CacheConfigurations> cachesConfiguration)

注意：此方法处于孵化阶段，可能会在 Gradle 的未来版本中更改。

配置用户主目录中缓存的设置。

ProjectDescriptor findProject(File projectDir)

返回具有给定项目目录的项目。

ProjectDescriptor findProject(String path)

返回具有给定路径的项目。

void include(Iterable<String> projectPaths)

将给定项目添加到构建中。所提供列表中的每个路径都被视为要添加到构建中的项目的路径。请注意，这些路径不是文件路径，而是指定新项目在项目层级结构中的位置。因此，提供的路径必须使用 ':' 字符作为分隔符（而不是 '/'）。

提供的路径的最后一个元素用作项目名称。提供的路径被转换为相对于根项目目录的项目目录。在项目包含之后，可以通过更改 'projectDir' 属性来修改项目目录（参见 ProjectDescriptor.setProjectDir(java.io.File)）。

例如，路径 a:b 添加一个路径为 :a:b，名称为 b，项目目录为 $rootDir/a/b 的项目。如果尚不存在，它也会添加一个路径为 :a，名称为 a，项目目录为 $rootDir/a 的项目。

使用项目路径的一些常见示例如下：

  // include two projects, 'foo' and 'foo:bar'
  // directories are inferred by replacing ':' with '/'
  include(['foo:bar'])

  // include one project whose project dir does not match the logical project path
  include(['baz'])
  project(':baz').projectDir = file('foo/baz')

  // include many projects whose project dirs do not match the logical project paths
  file('subprojects').eachDir { dir ->
    include([dir.name])
    project(":${dir.name}").projectDir = dir
  }

void include(String... projectPaths)

将给定项目添加到构建中。所提供列表中的每个路径都被视为要添加到构建中的项目的路径。请注意，这些路径不是文件路径，而是指定新项目在项目层级结构中的位置。因此，提供的路径必须使用 ':' 字符作为分隔符（而不是 '/'）。

提供的路径的最后一个元素用作项目名称。提供的路径被转换为相对于根项目目录的项目目录。在项目包含之后，可以通过更改 'projectDir' 属性来修改项目目录（参见 ProjectDescriptor.setProjectDir(java.io.File)）。

例如，路径 a:b 添加一个路径为 :a:b，名称为 b，项目目录为 $rootDir/a/b 的项目。如果尚不存在，它也会添加一个路径为 :a，名称为 a，项目目录为 $rootDir/a 的项目。

使用项目路径的一些常见示例如下：

  // include two projects, 'foo' and 'foo:bar'
  // directories are inferred by replacing ':' with '/'
  include 'foo:bar'

  // include one project whose project dir does not match the logical project path
  include 'baz'
  project(':baz').projectDir = file('foo/baz')

  // include many projects whose project dirs do not match the logical project paths
  file('subprojects').eachDir { dir ->
    include dir.name
    project(":${dir.name}").projectDir = dir
  }

void includeBuild(Object rootProject)

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

void includeBuild(Object rootProject, Action<ConfigurableIncludedBuild> configuration)

在指定路径包含一个构建到复合构建中，并应用提供的配置。

void includeFlat(Iterable<String> projectNames)

将给定项目添加到构建中。所提供列表中的每个名称都被视为要添加到构建中的项目名称。

提供的名称被转换为相对于根项目目录的父目录的项目目录。

例如，名称 a 添加一个路径为 :a，名称为 a，项目目录为 $rootDir/../a 的项目。

void includeFlat(String... projectNames)

将给定项目添加到构建中。所提供列表中的每个名称都被视为要添加到构建中的项目名称。

提供的名称被转换为相对于根项目目录的父目录的项目目录。

例如，名称 a 添加一个路径为 :a，名称为 a，项目目录为 $rootDir/../a 的项目。

ProjectDescriptor project(File projectDir)

返回具有给定项目目录的项目。

返回具有给定路径的项目。