# Chapter 55. The Build Lifecycle

We said earlier, that the core of Gradle is a language for dependency based programming. In Gradle terms this means that you can define tasks and dependencies between tasks. Gradle guarantees that these tasks are executed in the order of their dependencies, and that each task is executed only once. Those tasks form a Directed Acyclic Graph. There are build tools that build up such a dependency graph as they execute their tasks. Gradle builds the complete dependency graph before any task is executed. This lies at the heart of Gradle and makes many things possible which would not be possible otherwise.

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

## 55.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 projects are going to take part in the build, and creates a `Project` instance for each of these projects.

Configuration

  During this phase the project objects are configured. The build scripts of all projects which are part of the build are executed. Gradle 1.4 introduces an incubating opt-in feature called configuration on demand. In this mode, Gradle configures only relevant projects (see Section 56.1.1.1, “Configuration on demand”).

Execution

  Gradle determines the subset of the tasks, created and configured during the configuration phase, to be executed. The subset is determined by the task name arguments passed to the gradle command and the current directory. Gradle then executes each of the selected tasks.

## 55.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 file it is defined, which projects are taking part in the multi-project build (see Chapter 56, Multi-project Builds). For a single-project build, a settings file is optional. You might need it for example, to add libraries to your build script classpath (see Chapter 59, Organizing Build Logic). Let's first do some introspection with a single project build:

Example 55.1. Single project build

`settings.gradle`

    println 'This is executed during the initialization phase.'

`build.gradle`

    println 'This is executed during the configuration phase.'

    task configured {
        println 'This is also executed during the configuration phase.'
    }

    task test << {
        println 'This is executed during the execution phase.'
    }

Output of `gradle test`

    > gradle test
    This is executed during the initialization phase.
    This is executed during the configuration phase.
    This is also executed during the configuration phase.
    :test
    This is executed during the execution phase.

    BUILD SUCCESSFUL

    Total time: 1 secs

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 `Settings`.

## 55.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 56, Multi-project Builds).

### 55.3.1. Project locations

Multi-project builds are always represented by a tree with a single root. Each element in the tree represents a project. A project has a path which denotes the position of the project in the multi-project build tree. In majority of cases the project path is consistent with the physical location of the project in the file system. However, this behavior is configurable. 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.

### 55.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.

#### 55.3.2.1. Hierarchical layouts

Example 55.2. Hierarchical layout

`settings.gradle`

    include 'project1', 'project2:child', 'project3:child1'

The `include` method takes project paths as arguments. The project path is assumed to be equal to the relative physical file system path. For example a path 'services:api' by default is mapped to a folder 'services/api' (relative from the project root). You only need to specify the leafs of the tree. This means that the inclusion of path 'services:hotels:api' will result in creating 3 projects: 'services', 'services:hotels' and 'services:hotels:api'.

#### 55.3.2.2. Flat layouts

Example 55.3. Flat layout

`settings.gradle`

    includeFlat 'project3', 'project4'

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

### 55.3.3. Modifying elements of the project tree

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

Example 55.4. Modification of elements of the project tree

`settings.gradle`

    println rootProject.name
    println project(':projectA').name

Using this descriptor you can change the name, project directory and build file of a project.

Example 55.5. Modification of elements of the project tree

`settings.gradle`

    rootProject.name = 'main'
    project(':projectA').projectDir = new File(settingsDir, '../my-project-a')
    project(':projectA').buildFileName = 'projectA.gradle'

Have a look at `ProjectDescriptor` for more details.

## 55.4. Initialization

How does Gradle know whether to do a single or multiproject build? If 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. [20] 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 no `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 56, Multi-project Builds). 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 Section 56.4, “Running tasks by their absolute path”. 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 directory. Every project except the root project has a parent project and might have child projects.

## 55.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 equal 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 56, Multi-project Builds.

## 55.6. Responding to the lifecycle in the build script

Your build script can receive notifications as the build progresses through its lifecycle. These notifications generally take 2 forms: You can either implement a particular listener interface, or you can provide a closure to execute when the notification is fired. The examples below use closures. For details on how to use the listener interfaces, refer to the API documentation.

### 55.6.1. Project evaluation

You can receive a notification immediately before and after a project is evaluated. This can be used to do things like performing additional configuration once all the definitions in a build script have been applied, or for some custom logging or profiling.

Below is an example which adds a `test` task to each project with the `hasTests` property set to true.

Example 55.6. Adding of test task to each project which has certain property set

`build.gradle`

    allprojects {
        afterEvaluate { project ->
            if (project.hasTests) {
                println "Adding test task to $project"
                project.task('test') << {
                    println "Running tests for $project"
                }
            }
        }
    }

`projectA.gradle`

    hasTests = true

Output of `gradle -q test`

    > gradle -q test
    Adding test task to project ':projectA'
    Running tests for project ':projectA'

This example uses method `Project.afterEvaluate()` to add a closure which is executed after the project is evaluated.

It is also possible to receive notifications when any project is evaluated. This example performs some custom logging of project evaluation. Notice that the `afterProject` notification is received regardless of whether the project evaluates successfully or fails with an exception.

Example 55.7. Notifications

`build.gradle`

    gradle.afterProject {project, projectState ->
        if (projectState.failure) {
            println "Evaluation of $project FAILED"
        } else {
            println "Evaluation of $project succeeded"
        }
    }

Output of `gradle -q test`

    > gradle -q test
    Evaluation of root project 'buildProjectEvaluateEvents' succeeded
    Evaluation of project ':projectA' succeeded
    Evaluation of project ':projectB' FAILED

You can also add a `ProjectEvaluationListener` to the `Gradle` to receive these events.

### 55.6.2. Task creation

You can receive a notification immediately after a task is added to a project. This can be used to set some default values or add behaviour before the task is made available in the build file.

The following example sets the `srcDir` property of each task as it is created.

Example 55.8. Setting of certain property to all tasks

`build.gradle`

    tasks.whenTaskAdded { task ->
        task.srcDir = 'src/main/java'
    }

    task a

    println "source dir is $a.srcDir"

Output of `gradle -q a`

    > gradle -q a
    source dir is src/main/java

You can also add an `Action` to a `TaskContainer` to receive these events.

### 55.6.3. Task execution graph ready

You can receive a notification immediately after the task execution graph has been populated. We have seen this already in Section 6.13, “Configure by DAG”.

You can also add a `TaskExecutionGraphListener` to the `TaskExecutionGraph` to receive these events.

### 55.6.4. Task execution

You can receive a notification immediately before and after any task is executed.

The following example logs the start and end of each task execution. Notice that the `afterTask` notification is received regardless of whether the task completes successfully or fails with an exception.

Example 55.9. Logging of start and end of each task execution

`build.gradle`

    task ok

    task broken(dependsOn: ok) << {
        throw new RuntimeException('broken')
    }

    gradle.taskGraph.beforeTask { Task task ->
        println "executing $task ..."
    }

    gradle.taskGraph.afterTask { Task task, TaskState state ->
        if (state.failure) {
            println "FAILED"
        }
        else {
            println "done"
        }
    }

Output of `gradle -q broken`

    > gradle -q broken
    executing task ':ok' ...
    done
    executing task ':broken' ...
    FAILED

You can also use a `TaskExecutionListener` to the `TaskExecutionGraph` to receive these events.

[20] Gradle supports partial multiproject builds (see Chapter 56, Multi-project Builds).