Gradle Settings Script and Settings Instance

External

• https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html

Internal

• Gradle Concepts

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 initialization phase and updates the state of the delegate Settings instance. For single-project builds, this file is optional. However, it is required for multi-project builds: the root project of the multi-project build must declare this file.

Project Hierarchy

The sub-projects of a multi-project build are declared in the settings.gradle file of the root project with the "include" or "includeFlat" methods:

include 'subproject1', 'subproject2:child1'

includeFlat 'subproject1', 'subproject2'

The "include" method takes hierarchical project paths as arguments

The "includeFlat" expects a flat sibling structure.

Note that declaring a sub-project does not necessarily mean that anything will be built in that sub-project. A build.gradle with the appropriate plugins - which in turn contribute the necessary tasks - must also be added to the sub-project. Alternatively, the plugins may be applied in the root project's build.gradle with allprojects{...} or subprojects{...}. A build.gradle file is not necessary if the appropriate plugins are applied to subprojects from root.

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.

ProjectDescriptor - Access to Projects from Settings

https://docs.gradle.org/4.7/javadoc/org/gradle/api/initialization/ProjectDescriptor.html

Project information can be accessed from the settings.gradle file via ProjectDescriptor instances. Project instances are not accessible at this stage. ProjectDescriptor instances are created when a new project is added to the build from the settings script via include or includeFlat.

The ProjectDescriptor instances can be looked up in settings.gradle as follows:

project(':subproject-A')

findProject(':subproject-A')

The methods take a path as arguments and return the corresponding ProjectDescriptor instance. The ProjectDescriptor instance can be use to access and mutate state of the corresponding project.