Groovy Documentation

org.gradle.api.initialization
Interface Settings


interface Settings

Settings declares the configuration required to instantiate and evaluate the hierarchy of org.gradle.api.Project 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(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 vaules 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:

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.
  • author:
    Hans Dockter


    Field Summary
    java.lang.String DEFAULT_SETTINGS_FILE

    The default name for the settings file.

     
    Method Summary
    void captureStandardOutput(LogLevel level)

    Starts redirection of standard output during to the logging system during settings evaluation.

    void disableStandardOutputCapture()

    Disables redirection of standard output during settings evaluation.

    ProjectDescriptor findProject(java.lang.String path)

    Returns the project with the given path.

    ProjectDescriptor findProject(File projectDir)

    Returns the project with the given project directory.

    java.lang.ClassLoader getClassLoader()

    Returns the classloader used to compile and execute the settings script.

    Logger getLogger()

    Returns the logger for this build.

    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.

    StartParameter getStartParameter()

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

    void include(java.lang.String[] projectPaths)

    Adds the given projects to the build.

    void includeFlat(java.lang.String[] projectNames)

    Adds the given projects to the build.

    ProjectDescriptor project(java.lang.String path)

    Returns the project with the given path.

    ProjectDescriptor project(File projectDir)

    Returns the project with the given project directory.

     

    Field Detail

    DEFAULT_SETTINGS_FILE

    java.lang.String DEFAULT_SETTINGS_FILE

    The default name for the settings file.


     
    Method Detail

    captureStandardOutput

    public void captureStandardOutput(LogLevel level)
    Starts redirection of standard output during to the logging system during settings evaluation. By default redirection is enabled and the output is redirected to the QUIET level. System.err is always redirected to the ERROR level. Redirection of output at execution time can be configured via the tasks. For more fine-grained control on redirecting standard output see org.gradle.api.logging.StandardOutputLogging.
    param:
    level The level standard out should be logged to.
    see:
    #disableStandardOutputCapture()


    disableStandardOutputCapture

    public void disableStandardOutputCapture()
    Disables redirection of standard output during settings evaluation. By default redirection is enabled.
    see:
    #captureStandardOutput(org.gradle.api.logging.LogLevel)


    findProject

    public ProjectDescriptor findProject(java.lang.String path)

    Returns the project with the given path.

    param:
    path The path
    return:
    The project with the given path. Returns null if no such project exists.


    findProject

    public ProjectDescriptor findProject(File projectDir)

    Returns the project with the given project directory.

    param:
    projectDir The project directory.
    return:
    The project with the given project directory. Returns null if no such project exists.


    getClassLoader

    public java.lang.ClassLoader getClassLoader()

    Returns the classloader used to compile and execute the settings script.

    return:
    The classloader. Never returns null.


    getLogger

    public Logger getLogger()
    Returns the logger for this build. You can use this in your settings script to write log messages.
    return:
    The logger. Never returns null.


    getRootDir

    public File getRootDir()

    Returns the root directory of the build. The root directory is the project directory of the root project.

    return:
    The root directory. Never returns null.


    getRootProject

    public ProjectDescriptor getRootProject()

    Returns the root project of the build.

    return:
    The root project. Never returns null.


    getSettings

    public Settings getSettings()

    Returns this settings object.

    return:
    This settings object. Never returns null.


    getSettingsDir

    public File getSettingsDir()

    Returns the settings directory of the build. The settings directory is the directory containing the settings file.

    return:
    The settings directory. Never returns null.


    getStartParameter

    public StartParameter getStartParameter()

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

    return:
    The parameters. Never returns null.


    include

    public void include(java.lang.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 heirarchy. As such, the supplied paths must use the ':' character as separator.

    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.

    As an example, the path a:b adds a project with path :a:b, name b and project directory $rootDir/a/b.

    param:
    projectPaths the projects to add.


    includeFlat

    public void includeFlat(java.lang.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.

    param:
    projectNames the projects to add.


    project

    public ProjectDescriptor project(java.lang.String path)

    Returns the project with the given path.

    param:
    path The path.
    return:
    The project with the given path. Never returns null.
    throws:
    UnknownProjectException If no project with the given path exists.


    project

    public ProjectDescriptor project(File projectDir)

    Returns the project with the given project directory.

    param:
    projectDir The project directory.
    return:
    The project with the given project directory. Never returns null.
    throws:
    UnknownProjectException If no project with the given path exists.


     

    Groovy Documentation