设置

API 文档Settings

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

一个 Settings 实例与一个 settings.gradle 设置文件之间存在一一对应关系。在 Gradle 组装构建的项目之前,它会创建一个 Settings 实例并针对该实例执行设置文件。

组装多项目构建

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

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

在设置文件中使用设置

动态属性

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

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

属性

属性描述
buildCache

构建缓存配置。

caches
孵化中

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

extensions

扩展容器。

gradle

当前构建的 Gradle 实例。

pluginManager

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

plugins

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

rootDir

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

rootProject

构建的根项目。

settings

返回此设置对象。

settingsDir

构建的设置目录。设置目录是包含设置文件的目录。

startParameter

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

方法

方法描述
apply(closure)

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

apply(options)

应用插件或脚本,使用作为映射提供的给定选项。如果插件已应用,则不执行任何操作。

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 (只读)

返回此设置对象。

File settingsDir (只读)

构建的设置目录。设置目录是包含设置文件的目录。

StartParameter startParameter (只读)

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

方法详情

void apply(Closure closure)

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

给定的闭包用于配置 ObjectConfigurationAction,它“构建”插件应用程序。

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

void apply(Map<String, ?> options)

应用插件或脚本,使用作为映射提供的给定选项。如果插件已应用,则不执行任何操作。

给定的映射作为一系列方法调用应用于新创建的 ObjectConfigurationAction。也就是说,映射中的每个键都应为 ObjectConfigurationAction 的方法名称,并且值应与该方法的参数兼容。

可用的选项如下

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

void apply(Action<? super ObjectConfigurationAction> action)

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

给定的闭包用于配置 ObjectConfigurationAction,它“构建”插件应用程序。

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

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、名称为 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、名称为 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)

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

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