gradle/org.gradle.api.initialization/Settings

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

val DEFAULT_SETTINGS_FILE: String = "settings.gradle"

The default name for the settings file.

val ExtensionAware.extra: ExtraPropertiesExtension

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

Functions

abstract fun apply(closure: Closure)

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.

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.

abstract fun buildCache(action: Action<in BuildCacheConfiguration>)

Configures build cache.

abstract fun caches(cachesConfiguration: Action<in CacheConfigurations>)

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

inline fun <T : Any> ExtensionAware.configure(noinline configuration: T.() -> Unit)

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

dependencyResolutionManagement

abstract fun dependencyResolutionManagement(dependencyResolutionConfiguration: Action<in DependencyResolutionManagement>)

Configures the cross-project dependency resolution aspects

enableFeaturePreview

abstract fun enableFeaturePreview(name: String)

Enables a feature preview by name.

@Nullable

abstract fun findProject(projectDir: File): ProjectDescriptor

Returns the project with the given project directory.

@Nullable

abstract fun findProject(path: String): ProjectDescriptor

Returns the project with the given path.

abstract fun getBuildCache(): BuildCacheConfiguration

Returns the build cache configuration.

abstract fun getBuildscript(): ScriptHandler

Returns the build script handler for settings.

abstract fun getCaches(): CacheConfigurations

Returns the configuration for caches stored in the user home directory.

getDependencyResolutionManagement

abstract fun getDependencyResolutionManagement(): DependencyResolutionManagement

Returns the dependency resolution management handler.

abstract fun getExtensions(): ExtensionContainer

abstract fun getGradle(): Gradle

Returns the Gradle instance for the current build.

abstract fun getLayout(): BuildLayout

Provides access to important locations for a Gradle build.

getPluginManagement

abstract fun getPluginManagement(): PluginManagementSpec

Returns the plugin management configuration.

getPluginManager

abstract fun getPluginManager(): PluginManager

abstract fun getPlugins(): PluginContainer

abstract fun getProviders(): ProviderFactory

Provides access to methods to create various kinds of Provider instances.

abstract fun getRootDir(): File

Returns the root directory of the build.

abstract fun getRootProject(): ProjectDescriptor

Returns the root project of the build.

abstract fun getSettings(): Settings

Returns this settings object.

abstract fun getSettingsDir(): File

Returns the settings directory of the build.

getSourceControl

abstract fun getSourceControl(): SourceControl

Returns the source control configuration.

getStartParameter

abstract fun getStartParameter(): StartParameter

Returns the set of parameters used to invoke this instance of Gradle.

getToolchainManagement

abstract fun getToolchainManagement(): ToolchainManagement

Returns the toolchain management configuration.

abstract fun include(projectPaths: Iterable<String>)

open fun include(projectPaths: Array<String>)

Adds the given projects to the build.

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.

abstract fun includeFlat(projectNames: Iterable<String>)

open fun includeFlat(projectNames: Array<String>)

Adds the given projects to the build.

pluginManagement

abstract fun pluginManagement(pluginManagementSpec: Action<in PluginManagementSpec>)

Configures plugin management.

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

operator fun Settings.provideDelegate(any: Any?, property: KProperty<*>): PropertyDelegate

Locates a property on Settings.

abstract fun sourceControl(configuration: Action<in SourceControl>)

Configures source control.

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

abstract fun toolchainManagement(toolchainManagementConfiguration: Action<in ToolchainManagement>)

Configures toolchain management.