设置 (Settings)

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

一个 Settings 实例和一个 settings.gradle 设置文件之间存在一对一的对应关系。在 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 (设置)

返回此设置对象。

settingsDir (设置目录)

构建的设置目录。设置目录是包含 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 (只读)

返回此设置对象。

File settingsDir (只读)

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

StartParameter startParameter (只读)

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

方法详情

void apply(Closure closure)

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

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

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

void apply(Map<String, ?> options)

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

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

以下选项可用

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

void apply(Action<? super ObjectConfigurationAction> action)

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

给定的 closure 用于配置 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 且项目目录为 $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)

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

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