View source for Gradle Settings Script and Settings Instance

=DEPLETE TO=
{{Internal|Gradle Settings|Gradle Settings}}

=Overview=

The settings.gradle file describes the build's project hierarchy. In the simplest case, there is no settings.gradle, and the build consists in just a single project, the root project. In more complex cases, various sub-project hierarchies can be specified. The file can also be used to add libraries to the build script classpath. The configuration file is executed during the [[Gradle_Concepts#Build_Initialization_Phase|initialization phase]] and updates the state of the delegate [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html Settings] instance. For single-project builds, this file is optional. However, it is required for [[Gradle_Project_and_Build_Script#Multi-Project_Builds|multi-project builds]]: the root project of the multi-project build must declare this file.

=Project Hierarchy=

<font color=darkgray>TODO: next time I am here, describe differences between 'include' and 'includeFlat'.</font>

The sub-projects of a [[Gradle_Multi-Project_Builds#Overview|multi-project build]] are declared in the settings.gradle file of the [[Gradle_Multi-Project_Builds#Root_Project|root project]] with the Settings [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String&#91;&#93;) include(...)] or [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:includeFlat(java.lang.String&#91;&#93;) includeFlat(...)] methods:

<syntaxhighlight lang='groovy'>
include 'subproject1', 'subproject2:child1'
</syntaxhighlight>

<span id='include'></span>The [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String&#91;&#93;) include(...)] method specifies a multi-project build [[Gradle_Multi-Project_Builds#Hierarchical_Layout|hierarchical layout]]. It takes hierarchical project paths as arguments.

<syntaxhighlight lang='groovy'>
includeFlat 'subproject1', 'subproject2'
</syntaxhighlight>

<span id='includeFlat'></span>The [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:includeFlat(java.lang.String&#91;&#93;) includeFlat(...)] method specifies a multi-project build [[Gradle_Multi-Project_Builds#Flat_Layout|flat layout]]. It expects a flat sibling structure.

=Resolution=

* Look at a directory called "master" on the same nesting level as the current directory.
* If not found, search parent directories.
* If not found, the build executes as a single project build.
* If found, Gradle checks if the current project is part of multi-project hierarchy defined in the found settings.gradle file. If not, the build is executed as a single project build. Otherwise, a multi project build executed.

=rootProject.name=

<syntaxhighlight lang='groovy'>
rootProject.name = 'some-name'
</syntaxhighlight>

More details:

{{Internal|Gradle_Project_Coordinates,_State_and_Configured_Properties#rootProject|rootProject}}