# Interface Settings

All Superinterfaces:
  `ExtensionAware, PluginAware`

public interface Settings extends PluginAware, ExtensionAware

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.

Since:
  0.7

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_SETTINGS_FILE`
  The default name for the settings file.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `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 aspects
  `void`
  `enableFeaturePreview(String name)`
  Enables a feature preview by name.
  `@Nullable ProjectDescriptor`
  `findProject(File projectDir)`
  Returns the project with the given project directory.
  `@Nullable ProjectDescriptor`
  `findProject(String path)`
  Returns the project with the given path.
  `BuildCacheConfiguration`
  `getBuildCache()`
  Returns the build cache configuration.
  `ScriptHandler`
  `getBuildscript()`
  Returns the build script handler for settings.
  `CacheConfigurations`
  `getCaches()`
  Returns the configuration for caches stored in the user home directory.
  `SharedModelDefaults`
  `getDefaults()`
  Returns the model defaults object for this build.
  `DependencyResolutionManagement`
  `getDependencyResolutionManagement()`
  Returns the dependency resolution management handler.
  `Gradle`
  `getGradle()`
  Returns the `Gradle` instance for the current build.
  `BuildLayout`
  `getLayout()`
  Provides access to important locations for a Gradle build.
  `PluginManagementSpec`
  `getPluginManagement()`
  Returns the plugin management configuration.
  `ProviderFactory`
  `getProviders()`
  Provides access to methods to create various kinds of `Provider` instances.
  `File`
  `getRootDir()`
  Returns the root directory of the build.
  `ProjectDescriptor`
  `getRootProject()`
  Returns the root project of the build.
  `Settings`
  `getSettings()`
  Returns this settings object.
  `File`
  `getSettingsDir()`
  Returns the settings directory of the build.
  `SourceControl`
  `getSourceControl()`
  Returns the source control configuration.
  `StartParameter`
  `getStartParameter()`
  Returns the set of parameters used to invoke this instance of Gradle.
  `ToolchainManagement`
  `getToolchainManagement()`
  Returns the toolchain management configuration.
  `void`
  `include(Iterable<String> projectPaths)`
  Adds the given projects to the build.
  `default void`
  `include(String... projectPaths)`
  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.
  `ProjectDescriptor`
  `project(File projectDir)`
  Returns the project with the given project directory.
  `ProjectDescriptor`
  `project(String path)`
  Returns the project with the given path.
  `<T extends SettingsService>
  T`
  `service(Class<T> serviceType)`
  Looks up a service provided by Gradle for use in this build.
  `void`
  `sourceControl(Action<? super SourceControl> configuration)`
  Configures source control.
  `void`
  `toolchainManagement(Action<? super ToolchainManagement> toolchainManagementConfiguration)`
  Configures toolchain management.

  ### Methods inherited from interface ExtensionAware

  `getExtensions`

  ### Methods inherited from interface PluginAware

  `apply, apply, apply, getPluginManager, getPlugins`

- ## Field Details

  - ### DEFAULT_SETTINGS_FILE

    static final String DEFAULT_SETTINGS_FILE

    The default name for the settings file.

    Since:
      0.7
    See Also:
      - Constant Field Values
    Implementation Note:
      For internal purposes, prefer constants from `BuildLogicFiles`.

- ## Method Details

  - ### include

    default 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 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`, 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
          }

    Parameters:
      `projectPaths` - the projects to add.
    Since:
      0.7

  - ### include

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

    Parameters:
      `projectPaths` - the projects to add.
    Since:
      7.4

  - ### includeFlat

    default 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`.

    Parameters:
      `projectNames` - the projects to add.
    Since:
      0.7

  - ### includeFlat

    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`.

    Parameters:
      `projectNames` - the projects to add.
    Since:
      7.4

  - ### getSettings

    Settings getSettings()

    Returns this settings object.

    Returns:
      This settings object. Never returns null.
    Since:
      0.8

  - ### getLayout

    @Incubating BuildLayout 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.
    Since:
      0.7

  - ### 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.
    Since:
      0.7

  - ### getRootProject

    ProjectDescriptor getRootProject()

    Returns the root project of the build.

    Returns:
      The root project. Never returns null.
    Since:
      0.7

  - ### project

    ProjectDescriptor project(String path) throws UnknownProjectException

    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.
    Since:
      0.7

  - ### findProject

    @Nullable ProjectDescriptor findProject(String path)

    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.
    Since:
      0.7

  - ### project

    ProjectDescriptor project(File projectDir) throws UnknownProjectException

    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.
    Since:
      0.7

  - ### findProject

    @Nullable ProjectDescriptor findProject(File projectDir)

    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.
    Since:
      0.7

  - ### getStartParameter

    StartParameter getStartParameter()

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

    Returns:
      The parameters. Never returns null.
    Since:
      0.7

  - ### getProviders

    ProviderFactory getProviders()
    Provides access to methods to create various kinds of `Provider` instances.
    Since:
      6.8

  - ### service

    @Incubating <T extends SettingsService> T service(Class<T> serviceType)
    Looks up a service provided by Gradle for use in this build.

    The services available for lookup are the Gradle types that implement `SettingsService`.

    This method does not provide access to `shared build services`; use `Gradle.getSharedServices()` to access those.

    Type Parameters:
      `T` - the service type
    Parameters:
      `serviceType` - the type of the service to look up
    Returns:
      the service instance. Never returns null.
    Throws:
      `InvalidUserDataException` - when the given type is not one of the services available in this scope
    Since:
      9.8.0

  - ### getGradle

    Gradle getGradle()
    Returns the `Gradle` instance for the current build.
    Returns:
      The Gradle instance. Never returns null.
    Since:
      0.9

  - ### includeBuild

    void includeBuild(Object rootProject)
    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

    void includeBuild(Object rootProject, Action<ConfigurableIncludedBuild> configuration)
    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

    void buildCache(Action<? super BuildCacheConfiguration> action)
    Configures build cache.
    Since:
      3.5

  - ### pluginManagement

    void pluginManagement(Action<? super PluginManagementSpec> pluginManagementSpec)
    Configures plugin management.
    Since:
      3.5

  - ### getPluginManagement

    PluginManagementSpec getPluginManagement()
    Returns the plugin management configuration.
    Since:
      3.5

  - ### sourceControl

    void sourceControl(Action<? super SourceControl> configuration)
    Configures source control.
    Since:
      4.4

  - ### getSourceControl

    SourceControl getSourceControl()
    Returns the source control configuration.
    Since:
      4.4

  - ### enableFeaturePreview

    void enableFeaturePreview(String name)
    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

    @Incubating ToolchainManagement getToolchainManagement()
    Returns the toolchain management configuration.
    Since:
      7.6

  - ### getCaches

    @Incubating CacheConfigurations getCaches()
    Returns the configuration for caches stored in the user home directory.
    Since:
      8.0

  - ### caches

    @Incubating void caches(Action<? super CacheConfigurations> cachesConfiguration)
    Configures the settings for caches stored in the user home directory.
    Parameters:
      `cachesConfiguration` - the configuration
    Since:
      8.0

  - ### getDefaults

    @Incubating SharedModelDefaults getDefaults()
    Returns the model defaults object for this build. This is an experimental feature.
    Since:
      8.10

  - ### defaults

    @Incubating void defaults(Action<? super SharedModelDefaults> action)
    Configures the model defaults for this build. This is an experimental feature.
    Parameters:
      `action` - the configuration to apply
    Since:
      8.10