Settings

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

PropertyDescription
gradle

The Gradle instance for the current build.

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

MethodDescription
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 heirarchy. As such, the supplied paths must use the ':' character as separator.

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

Gradle gradle (read-only)

The Gradle instance for the current build.

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

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(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 heirarchy. As such, the supplied paths must use the ':' character as separator.

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.

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

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.

Returns the project with the given path.