# Settings

interface Settings : PluginAware, ExtensionAware(source)

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

There is a one-to-one correspondence between a `Settings` instance and a `{@value * #DEFAULT_SETTINGS_FILE}` 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 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 {@value org.gradle.api.Project#GRADLE_PROPERTIES} file located in the settings directory of the build.
- Defined the {@value org.gradle.api.Project#GRADLE_PROPERTIES} file located in the user's `.gradle` directory.
- Provided on the command-line using the -P option.

## Properties

DEFAULT_SETTINGS_FILE
Link copied to clipboard
val DEFAULT_SETTINGS_FILE: String = "settings.gradle"
The default name for the settings file.
extra
Link copied to clipboard
val ExtensionAware.extra: ExtraPropertiesExtension

The extra properties extension in this object's extension container.

## Functions

apply
Link copied to clipboard
abstract fun apply(closure: Closure)
apply
Link copied to clipboard
inline fun <T : Plugin<Settings>> Settings.apply()
inline fun <T : Plugin<*>> PluginAware.apply()

Applies the plugin of the given type T. Does nothing if the plugin has already been applied.

inline fun PluginAware.apply(vararg options: Pair<String, Any>)

Kotlin extension function for org.gradle.api.plugins.PluginAware.apply.

fun PluginAware.apply(from: Any? = null, plugin: String? = null, to: Any? = null)

Applies the given plugin or script.

applyTo
Link copied to clipboard
inline fun <T : Plugin<*>> PluginAware.applyTo(vararg targets: Any)

Applies the plugin of the given type T to the specified object. Does nothing if the plugin has already been applied.

buildCache
Link copied to clipboard
abstract fun buildCache(action: Action<in BuildCacheConfiguration>)
Configures build cache.
caches
Link copied to clipboard
@Incubating
abstract fun caches(cachesConfiguration: Action<in CacheConfigurations>)
Configures the settings for caches stored in the user home directory.
configure
Link copied to clipboard
inline fun <T : Any> ExtensionAware.configure(noinline configuration: T.() -> Unit)

Executes the given configuration block against the extension of the specified type.

defaults
Link copied to clipboard
@Incubating
abstract fun defaults(action: Action<in SharedModelDefaults>)
Configures the model defaults for this build.
dependencyResolutionManagement
Link copied to clipboard
abstract fun dependencyResolutionManagement(dependencyResolutionConfiguration: Action<in DependencyResolutionManagement>)
Configures the cross-project dependency resolution aspects
enableFeaturePreview
Link copied to clipboard
abstract fun enableFeaturePreview(name: String)
Enables a feature preview by name.
findProject
Link copied to clipboard
@Nullable
abstract fun findProject(projectDir: File): @Nullable ProjectDescriptor
Returns the project with the given project directory.
@Nullable
abstract fun findProject(path: String): @Nullable ProjectDescriptor
Returns the project with the given path.
getBuildCache
Link copied to clipboard
abstract fun getBuildCache(): BuildCacheConfiguration
Returns the build cache configuration.
getBuildscript
Link copied to clipboard
abstract fun getBuildscript(): ScriptHandler
Returns the build script handler for settings.
getCaches
Link copied to clipboard
@Incubating
abstract fun getCaches(): CacheConfigurations
Returns the configuration for caches stored in the user home directory.
getDefaults
Link copied to clipboard
@Incubating
abstract fun getDefaults(): SharedModelDefaults
Returns the model defaults object for this build.
getDependencyResolutionManagement
Link copied to clipboard
abstract fun getDependencyResolutionManagement(): DependencyResolutionManagement
Returns the dependency resolution management handler.
getExtensions
Link copied to clipboard
abstract fun getExtensions(): ExtensionContainer
getGradle
Link copied to clipboard
abstract fun getGradle(): Gradle
Returns the Gradle instance for the current build.
getLayout
Link copied to clipboard
@Incubating
abstract fun getLayout(): BuildLayout
Provides access to important locations for a Gradle build.
getPluginManagement
Link copied to clipboard
abstract fun getPluginManagement(): PluginManagementSpec
Returns the plugin management configuration.
getPluginManager
Link copied to clipboard
abstract fun getPluginManager(): PluginManager
getPlugins
Link copied to clipboard
abstract fun getPlugins(): PluginContainer
getProviders
Link copied to clipboard
abstract fun getProviders(): ProviderFactory
Provides access to methods to create various kinds of Provider instances.
getRootDir
Link copied to clipboard
abstract fun getRootDir(): File
Returns the root directory of the build.
getRootProject
Link copied to clipboard
abstract fun getRootProject(): ProjectDescriptor
Returns the root project of the build.
getSettings
Link copied to clipboard
abstract fun getSettings(): Settings
Returns this settings object.
getSettingsDir
Link copied to clipboard
abstract fun getSettingsDir(): File
Returns the settings directory of the build.
getSourceControl
Link copied to clipboard
abstract fun getSourceControl(): SourceControl
Returns the source control configuration.
getStartParameter
Link copied to clipboard
abstract fun getStartParameter(): StartParameter
Returns the set of parameters used to invoke this instance of Gradle.
getToolchainManagement
Link copied to clipboard
@Incubating
abstract fun getToolchainManagement(): ToolchainManagement
Returns the toolchain management configuration.
include
Link copied to clipboard
abstract fun include(projectPaths: Iterable<String>)
open fun include(projectPaths: Array<String>)
Adds the given projects to the build.
includeBuild
Link copied to clipboard
abstract fun includeBuild(rootProject: Any)
Includes a build at the specified path to the composite build.
abstract fun includeBuild(rootProject: Any, configuration: Action<ConfigurableIncludedBuild>)
Includes a build at the specified path to the composite build, with the supplied configuration.
includeFlat
Link copied to clipboard
abstract fun includeFlat(projectNames: Iterable<String>)
open fun includeFlat(projectNames: Array<String>)
Adds the given projects to the build.
pluginManagement
Link copied to clipboard
abstract fun pluginManagement(pluginManagementSpec: Action<in PluginManagementSpec>)
Configures plugin management.
project
Link copied to clipboard
abstract fun project(projectDir: File): ProjectDescriptor
Returns the project with the given project directory.
abstract fun project(path: String): ProjectDescriptor
Returns the project with the given path.
provideDelegate
Link copied to clipboard
operator fun Settings.provideDelegate(any: Any?, property: KProperty<*>): PropertyDelegate

Locates a property on Settings.

sourceControl
Link copied to clipboard
abstract fun sourceControl(configuration: Action<in SourceControl>)
Configures source control.
the
Link copied to clipboard
inline fun <T : Any> ExtensionAware.the(): T

Returns the extension of the specified type.

fun <T : Any> ExtensionAware.the(extensionType: KClass<T>): T

Returns the extension of the specified extensionType.

toolchainManagement
Link copied to clipboard
@Incubating
abstract fun toolchainManagement(toolchainManagementConfiguration: Action<in ToolchainManagement>)
Configures toolchain management.