Settings

Table of Contents

Assembling a Multi-Project Build
Using Settings in a Settings File
Properties
Methods
Script blocks
Property details
Method details

API Documentation:	`Settings`

Declares the configuration required to instantiate and configure the hierarchy of Project instances which are to participate in a build.

There is a one-to-one correspondence between a Settings instance and a settings.gradle settings file. Before Gradle assembles the projects for a build, it creates a Settings instance and executes the settings file against it.

Assembling a Multi-Project Build

One of the purposes of the Settings object is to allow you to declare the projects which are to be included in the build. You add projects to the build using the Settings.include(java.lang.String[]) method. There is always a root project included in a build. It is added automatically when the Settings object is created. The root project's name defaults to the name of the directory containing the settings file. The root project's project directory defaults to the directory containing the settings file.

When a project is included in the build, a ProjectDescriptor is created. You can use this descriptor to change the default values for several properties of the project.

Using Settings in a Settings File

Dynamic Properties

In addition to the properties of this interface, the Settings object makes some additional read-only properties available to the settings script. This includes properties from the following sources:

Defined in the gradle.properties file located in the settings directory of the build.
Defined the gradle.properties file located in the user's .gradle directory.
Provided on the command-line using the -P option.

Properties

Property	Description
`buildCache`	The build cache configuration.
`caches`	Incubating The configuration for caches stored in the user home directory.
`extensions`	The container of extensions.
`gradle`	The `Gradle` instance for the current build.
`pluginManager`	The plugin manager for this plugin aware object.
`plugins`	The container of plugins that have been applied to this object.
`rootDir`	The root directory of the build. The root directory is the project directory of the root project.
`rootProject`	The root project of the build.
`settings`	Returns this settings object.
`settingsDir`	The settings directory of the build. The settings directory is the directory containing the settings file.
`startParameter`	The set of parameters used to invoke this instance of Gradle.

Methods

Method	Description
`apply(closure)`	Applies zero or more plugins or scripts.
`apply(options)`	Applies a plugin or script, using the given options provided as a map. Does nothing if the plugin has already been applied.
`apply(action)`	Applies zero or more plugins or scripts.
`buildCache(action)`	Configures build cache.
`caches(cachesConfiguration)`	Incubating Configures the settings for caches stored in the user home directory.
`findProject(projectDir)`	Returns the project with the given project directory.
`findProject(path)`	Returns the project with the given path.
`include(projectPaths)`	Adds the given projects to the build. Each path in the supplied list is treated as the path of a project to add to the build. Note that these path are not file paths, but instead specify the location of the new project in the project hierarchy. As such, the supplied paths must use the ':' character as separator (and NOT '/').
`include(projectPaths)`	Adds the given projects to the build. Each path in the supplied list is treated as the path of a project to add to the build. Note that these path are not file paths, but instead specify the location of the new project in the project hierarchy. As such, the supplied paths must use the ':' character as separator (and NOT '/').
`includeBuild(rootProject)`	Includes a build at the specified path to the composite build.
`includeBuild(rootProject, configuration)`	Includes a build at the specified path to the composite build, with the supplied configuration.
`includeFlat(projectNames)`	Adds the given projects to the build. Each name in the supplied list is treated as the name of a project to add to the build.
`includeFlat(projectNames)`	Adds the given projects to the build. Each name in the supplied list is treated as the name of a project to add to the build.
`project(projectDir)`	Returns the project with the given project directory.
`project(path)`	Returns the project with the given path.

Script blocks

No script blocks

Property details

`BuildCacheConfiguration` `buildCache` (read-only)

The build cache configuration.

`CacheConfigurations` `caches` (read-only)

Note: This property is incubating and may change in a future version of Gradle.

The configuration for caches stored in the user home directory.

`ExtensionContainer` `extensions` (read-only)

The container of extensions.

`Gradle` `gradle` (read-only)

The Gradle instance for the current build.

`PluginManager` `pluginManager` (read-only)

The plugin manager for this plugin aware object.

`PluginContainer` `plugins` (read-only)

The container of plugins that have been applied to this object.

While not deprecated, it is preferred to use the methods of this interface or the PluginAware.getPluginManager() than use the plugin container.

Use one of the 'apply' methods on this interface or on the PluginAware.getPluginManager() to apply plugins instead of applying via the plugin container.

Use PluginManager.hasPlugin(java.lang.String) or similar to query for the application of plugins instead of doing so via the plugin container.

`File` `rootDir` (read-only)

The root directory of the build. The root directory is the project directory of the root project.

`ProjectDescriptor` `rootProject` (read-only)

The root project of the build.

`Settings` `settings` (read-only)

Returns this settings object.

`File` `settingsDir` (read-only)

The settings directory of the build. The settings directory is the directory containing the settings file.

`StartParameter` `startParameter` (read-only)

The set of parameters used to invoke this instance of Gradle.

Method details

`void` `apply`(`Closure` closure)

Applies zero or more plugins or scripts.

The given closure is used to configure an ObjectConfigurationAction, which “builds” the plugin application.

This method differs from PluginAware.apply(java.util.Map) in that it allows methods of the configuration action to be invoked more than once.

`void` `apply`(`Map<String, ?>` options)

Applies a plugin or script, using the given options provided as a map. Does nothing if the plugin has already been applied.

The given map is applied as a series of method calls to a newly created ObjectConfigurationAction. That is, each key in the map is expected to be the name of a method ObjectConfigurationAction and the value to be compatible arguments to that method.

The following options are available:

from: A script to apply. Accepts any path supported by Project.uri(java.lang.Object).
plugin: The id or implementation class of the plugin to apply.
to: The target delegate object or objects. The default is this plugin aware object. Use this to configure objects other than this object.

`void` `apply`(`Action<? super ObjectConfigurationAction>` action)

Applies zero or more plugins or scripts.

The given closure is used to configure an ObjectConfigurationAction, which “builds” the plugin application.

This method differs from PluginAware.apply(java.util.Map) in that it allows methods of the configuration action to be invoked more than once.

`void` `buildCache`(`Action<? super BuildCacheConfiguration>` action)

Configures build cache.

`void` `caches`(`Action<? super CacheConfigurations>` cachesConfiguration)

Note: This method is incubating and may change in a future version of Gradle.

Configures the settings for caches stored in the user home directory.

`ProjectDescriptor` `findProject`(`File` projectDir)

Returns the project with the given project directory.

`ProjectDescriptor` `findProject`(`String` path)

Returns the project with the given path.

`void` `include`(`Iterable<String>` projectPaths)

Adds the given projects to the build. Each path in the supplied list is treated as the path of a project to add to the build. Note that these path are not file paths, but instead specify the location of the new project in the project hierarchy. As such, the supplied paths must use the ':' character as separator (and NOT '/').

The last element of the supplied path is used as the project name. The supplied path is converted to a project directory relative to the root project directory. The project directory can be altered by changing the 'projectDir' property after the project has been included (see ProjectDescriptor.setProjectDir(java.io.File))

As an example, the path a:b adds a project with path :a:b, name b and project directory $rootDir/a/b. It also adds the a project with path :a, name a and project directory $rootDir/a, if it does not exist already.

Some common examples of using the project path are:

  // 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)

Some common examples of using the project path are:

  // 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)

Includes a build at the specified path to the composite build.

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

Includes a build at the specified path to the composite build, with the supplied configuration.

`void` `includeFlat`(`Iterable<String>` projectNames)

Adds the given projects to the build. Each name in the supplied list is treated as the name of a project to add to the build.

The supplied name is converted to a project directory relative to the parent directory of the root project directory.

As an example, the name a add a project with path :a, name a and project directory $rootDir/../a.

`void` `includeFlat`(`String...` projectNames)

Adds the given projects to the build. Each name in the supplied list is treated as the name of a project to add to the build.

The supplied name is converted to a project directory relative to the parent directory of the root project directory.

As an example, the name a add a project with path :a, name a and project directory $rootDir/../a.

`ProjectDescriptor` `project`(`File` projectDir)

Returns the project with the given project directory.

`ProjectDescriptor` `project`(`String` path)

Returns the project with the given path.

Settings

Assembling a Multi-Project Build

Using Settings in a Settings File

Dynamic Properties

Properties

Methods

Script blocks

Property details

BuildCacheConfiguration buildCache (read-only)

CacheConfigurations caches (read-only)

ExtensionContainer extensions (read-only)

Gradle gradle (read-only)

PluginManager pluginManager (read-only)

PluginContainer plugins (read-only)

File rootDir (read-only)

ProjectDescriptor rootProject (read-only)

Settings settings (read-only)

File settingsDir (read-only)

StartParameter startParameter (read-only)

Method details

void apply(Closure closure)

void apply(Map<String, ?> options)

void apply(Action<? super ObjectConfigurationAction> action)

void buildCache(Action<? super BuildCacheConfiguration> action)

void caches(Action<? super CacheConfigurations> cachesConfiguration)

ProjectDescriptor findProject(File projectDir)

ProjectDescriptor findProject(String path)

void include(Iterable<String> projectPaths)

void include(String... projectPaths)

void includeBuild(Object rootProject)

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

void includeFlat(Iterable<String> projectNames)

void includeFlat(String... projectNames)

ProjectDescriptor project(File projectDir)

ProjectDescriptor project(String path)