Chapter 13
The Build Lifecycle

Your build scripts configure this DAG. Therefore they are strictly speaking build configuration scripts.

13.1 Build Phases

A Gradle build has three distinct phases.

Initialization

Gradle supports single and multi-project builds. During the initialization phase, Gradle determines which project(s) are going to take part in the build. Also during this phase, Gradle creates Project objects for every project taking part in the build.

Configuration

The build scripts of all projects which are part of the build are executed. This configures the project objects.

Execution

A subset of the tasks, created and configured during the configuration phase, is executed. The subset is determined by the task name arguments passed to the gradle command and the current directory.

13.2 Settings File

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.

13.3 Multi-Project Builds

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).

13.3.1 Project Locations

Multi-project builds are always represented by a tree with a single root. Each element in the tree represent a project. A project has a virtual and a physical path. The virtual path denotes the position of the project in the multi-project build tree. The project tree is created in the settings.gradle file. By default it is assumed that the location of the settings file is also the location of the root project. But you can redefine the location of the root project in the settings file.

13.3.2 Building the tree

In the settings file you can use a set of methods to build the project tree. Hierarchical and flat physical layouts get special support.

Hierarchical Layouts

The include method takes as an argument a relative virtual path to the root project. This relative virtual path is assumed to be equals to the relative physical path of the subproject to the root project. You only need to specify the leafs of the tree. Each parent path of the leaf project is assumed to be another subproject which obeys to the physical path assumption described above.

Flat Layouts

The includeFlat method takes directory names as an argument. Those directories need to exist at the same level as the root project directory. The location of those directories are considered as child projects of the root project in the virtual multi-project tree.

13.3.3 Modifying Elements of the Project Tree

The multi-project tree created in the settings file is made up of so called project descriptor object. You might modify those descriptor objects in the settings file at any time. To access such a descriptor object you can do:

Via this descriptor you can change the name and the directory of a project.

13.4 Initialization

How does Gradle know whether to do a single or multiproject build? In you trigger a multiproject build from the directory where the settings file is, things are easy. But Gradle also allows you to execute the build from within any subproject taking part in the build.¹ . If you execute Gradle from within a project that has no settings.gradle file, Gradle does the following:

• It searches for a settings.gradle in a directory called ’master’ which has the same nesting level as the current dir.
• If not settings.gradle is found, it searches the parent directories for the existence of a settings.gradle file.
• If no settings.gradle file is found, the build is executed as a single project build.
• If a settings.gradle file is found, Gradle checks if the current project is part of the multiproject hierarchy defined in the found settings.gradle file. If not, the build is executed as a single project build. Otherwise a multiproject build is executed.

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:

• a single project build, if the settings.gradle file does not define a multiproject hierarchy
• a multiproject build, if the settings.gradle file does define a multiproject hierarchy.

The auto search for a settings file does only work for multi-project builds with a physical hierarchical or flat layout. For a flat layout you must additionally obey to the naming convention described above. Gradle supports arbitrary physical layouts for a multiproject build. But for such arbitrary layouts you need to execute the build from the directory where the settings file is located. For how to run partial builds from the root see 14.4. In our next release we want to enable partial builds from subprojects by specifying the location of the settings file as a command line parameter.
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 by default a name equals to the name of its top level folder. Every project except the root project has a parent project and might have child projects.

13.5 Configuration and Execution of a Single Project Build

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.