Interface Settings
- All Superinterfaces:
ExtensionAware
,PluginAware
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 include(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.
-
Field Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
buildCache
(Action<? super BuildCacheConfiguration> action) Configures build cache.void
caches
(Action<? super CacheConfigurations> cachesConfiguration) Configures the settings for caches stored in the user home directory.void
defaults
(Action<? super SharedModelDefaults> action) Configures the model defaults for this build.void
dependencyResolutionManagement
(Action<? super DependencyResolutionManagement> dependencyResolutionConfiguration) Configures the cross-project dependency resolution aspectsvoid
enableFeaturePreview
(String name) Enables a feature preview by name.findProject
(File projectDir) Returns the project with the given project directory.findProject
(String path) Returns the project with the given path.Returns the build cache configuration.Returns the build script handler for settings.Returns the configuration for caches stored in the user home directory.Returns the model defaults object for this build.Returns the dependency resolution management handler.Returns theGradle
instance for the current build.Provides access to important locations for a Gradle build.Returns the plugin management configuration.Provides access to methods to create various kinds ofProvider
instances.Returns the root directory of the build.Returns the root project of the build.Returns this settings object.Returns the settings directory of the build.Returns the source control configuration.Returns the set of parameters used to invoke this instance of Gradle.Returns the toolchain management configuration.void
Adds the given projects to the build.default void
Adds the given projects to the build.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.default void
includeFlat
(String... projectNames) Adds the given projects to the build.void
pluginManagement
(Action<? super PluginManagementSpec> pluginManagementSpec) Configures plugin management.Returns the project with the given project directory.Returns the project with the given path.void
sourceControl
(Action<? super SourceControl> configuration) Configures source control.void
toolchainManagement
(Action<? super ToolchainManagement> toolchainManagementConfiguration) Configures toolchain management.Methods inherited from interface org.gradle.api.plugins.ExtensionAware
getExtensions
Methods inherited from interface org.gradle.api.plugins.PluginAware
apply, apply, apply, getPluginManager, getPlugins
-
Field Details
-
DEFAULT_SETTINGS_FILE
The default name for the settings file.
- See Also:
-
-
Method Details
-
include
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(File)
)As an example, the path
a:b
adds a project with path:a:b
, nameb
and project directory$rootDir/a/b
. It also adds the a project with path:a
, namea
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 }
- Parameters:
projectPaths
- the projects to add.
-
include
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(File)
)As an example, the path
a:b
adds a project with path:a:b
, nameb
and project directory$rootDir/a/b
. It also adds the a project with path:a
, namea
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 }
- Parameters:
projectPaths
- the projects to add.- Since:
- 7.4
-
includeFlat
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
, namea
and project directory$rootDir/../a
.- Parameters:
projectNames
- the projects to add.
-
includeFlat
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
, namea
and project directory$rootDir/../a
.- Parameters:
projectNames
- the projects to add.- Since:
- 7.4
-
getSettings
Settings getSettings()Returns this settings object.
- Returns:
- This settings object. Never returns null.
-
getLayout
Provides access to important locations for a Gradle build.- Since:
- 8.5
-
getBuildscript
ScriptHandler getBuildscript()Returns the build script handler for settings. You can use this handler to query details about the build script for settings, and manage the classpath used to compile and execute the settings script.- Returns:
- the classpath handler. Never returns null.
- Since:
- 4.4
-
getSettingsDir
File getSettingsDir()Returns the settings directory of the build. The settings directory is the directory containing the settings file.
- Returns:
- The settings directory. Never returns null.
-
getRootDir
File getRootDir()Returns the root directory of the build. The root directory is the project directory of the root project.
- Returns:
- The root directory. Never returns null.
-
getRootProject
ProjectDescriptor getRootProject()Returns the root project of the build.
- Returns:
- The root project. Never returns null.
-
project
Returns the project with the given path.
- Parameters:
path
- The path.- Returns:
- The project with the given path. Never returns null.
- Throws:
UnknownProjectException
- If no project with the given path exists.
-
findProject
Returns the project with the given path.
- Parameters:
path
- The path- Returns:
- The project with the given path. Returns null if no such project exists.
-
project
Returns the project with the given project directory.
- Parameters:
projectDir
- The project directory.- Returns:
- The project with the given project directory. Never returns null.
- Throws:
UnknownProjectException
- If no project with the given path exists.
-
findProject
Returns the project with the given project directory.
- Parameters:
projectDir
- The project directory.- Returns:
- The project with the given project directory. Returns null if no such project exists.
-
getStartParameter
StartParameter getStartParameter()Returns the set of parameters used to invoke this instance of Gradle.
- Returns:
- The parameters. Never returns null.
-
getProviders
ProviderFactory getProviders()Provides access to methods to create various kinds ofProvider
instances.- Since:
- 6.8
-
getGradle
Gradle getGradle()Returns theGradle
instance for the current build.- Returns:
- The Gradle instance. Never returns null.
-
includeBuild
Includes a build at the specified path to the composite build.- Parameters:
rootProject
- The path to the root project directory for the build.- Since:
- 3.1
-
includeBuild
Includes a build at the specified path to the composite build, with the supplied configuration.- Parameters:
rootProject
- The path to the root project directory for the build.configuration
- An action to configure the included build.- Since:
- 3.1
-
getBuildCache
BuildCacheConfiguration getBuildCache()Returns the build cache configuration.- Since:
- 3.5
-
buildCache
Configures build cache.- Since:
- 3.5
-
pluginManagement
Configures plugin management.- Since:
- 3.5
-
getPluginManagement
PluginManagementSpec getPluginManagement()Returns the plugin management configuration.- Since:
- 3.5
-
sourceControl
Configures source control.- Since:
- 4.4
-
getSourceControl
SourceControl getSourceControl()Returns the source control configuration.- Since:
- 4.4
-
enableFeaturePreview
Enables a feature preview by name.- Parameters:
name
- the name of the feature to enable- Since:
- 4.6
-
dependencyResolutionManagement
void dependencyResolutionManagement(Action<? super DependencyResolutionManagement> dependencyResolutionConfiguration) Configures the cross-project dependency resolution aspects- Parameters:
dependencyResolutionConfiguration
- the configuration- Since:
- 6.8
-
getDependencyResolutionManagement
DependencyResolutionManagement getDependencyResolutionManagement()Returns the dependency resolution management handler.- Since:
- 6.8
-
toolchainManagement
@Incubating void toolchainManagement(Action<? super ToolchainManagement> toolchainManagementConfiguration) Configures toolchain management.- Since:
- 7.6
-
getToolchainManagement
Returns the toolchain management configuration.- Since:
- 7.6
-
getCaches
Returns the configuration for caches stored in the user home directory.- Since:
- 8.0
-
caches
Configures the settings for caches stored in the user home directory.- Parameters:
cachesConfiguration
- the configuration- Since:
- 8.0
-
getDefaults
Returns the model defaults object for this build. This is an experimental feature.- Since:
- 8.10
-
defaults
Configures the model defaults for this build. This is an experimental feature.- Parameters:
action
- the configuration to apply- Since:
- 8.10
-