Interface Settings

  • All Superinterfaces:
    PluginAware

    public interface Settings
    extends 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 Detail

      • DEFAULT_SETTINGS_FILE

        static final String DEFAULT_SETTINGS_FILE

        The default name for the settings file.

        See Also:
        Constant Field Values
    • Method Detail

      • include

        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.
      • includeFlat

        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.
      • getSettings

        Settings getSettings()

        Returns this settings object.

        Returns:
        This settings object. Never returns null.
      • getBuildscript

        @Incubating
        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.
      • 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.
      • 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.
      • 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.
      • getStartParameter

        StartParameter getStartParameter()

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

        Returns:
        The parameters. Never returns null.
      • getGradle

        Gradle getGradle()
        Returns the Gradle instance for the current build.
        Returns:
        The Gradle instance. Never returns null.
      • includeBuild

        @Incubating
        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

        @Incubating
        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