Your build scripts configure this DAG. Therefore they are strictly speaking build configuration scripts.
A Gradle build has three distinct phases.
Beside the build script files, Gradle defines a settings file. The settings file is determined by Gradle via a naming convention. The default name for this file is settings.gradle. Later in this chapter we explain, how Gradle looks for a settings file.
The settings file gets executed during the initialization phase. A multiproject build must have a settings.gradle file in the root project of the multiproject hierarchy. It is required because in the settings.gradle file it is defined, which projects are taking part in the multi-project build (see chapter 14). For a single-project build, a settings.gradle file is optional. You might need it for example, to add libraries to your build script classpath (see chapter 15). Let’s first do some introspection with a single project build:
For a build script, the property access and method calls are delegated to a project object. Similarly property access and method calls within the settings file is delegated to a settings object. Have a look at org.gradle.api.Settings.
A multi-project build is a build where you build more than one project during a single execution of Gradle. You have to declare the projects taking part in the multiproject build in the settings file. There is much more to say about multi-project builds in the chapter dedicated to this topic (see chapter 14).
How does Gradle know whether to do a single or multiproject build? In particular as you may not just trigger a multiproject build from the root project, but also from within any subproject taking part in the build.1 . If you execute Gradle from within a project that has no settings.gradle file, Gradle does the following:
What is the purpose of this behavior? Somehow Gradle has to find out, whether the project you are into, is a subproject of a multiproject build or not. Of course, if it is a subproject, only the subproject and its dependent projects are build. But Gradle needs to create the build configuration for the whole multiproject build (see chapter 14). Via the -u command line option, you can tell Gradle not to look in the parent hierarchy for a settings.gradle file. The current project is then always build as a single project build. If the current project contains a settings.gradle file, the -u option has no meaning. Such a build is always executed as:
Gradle creates Project objects for every project taking part in the build. For a single project build this is only one project. For a multi-project build these are the projects specified in Settings object (plus the root project). Each project object has a name equals to the name of its top level folder. The projects form a tree according to there position in the file system. Thus every project except the root project has a parent project and might have child projects. There are no gaps in the project tree. This means every parent folder between a specified project folder and the project root is considered to be a project and is automatically part of the project tree. This means no additional work for you, as a project might have a build script but it is not mandatory (see chapter 14).
For a single project build, the workflow of the after initialization phases are pretty simple. The build script is executed against the project object that was created during the initialization phase. Then Gradle looks for tasks with names equals to those passed as command line arguments. If these task names exist, they are executed as a separate build in the order you have passed them. The configuration and execution for multi-project builds is discussed in chapter 14.