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. These 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.
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.
- 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.
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 is executed during the initialization phase. A multi-project build must have a settings.gradle
file in the root project of the multi-project hierarchy. It is required because the settings file defines which projects are taking part in the multi-project build (see Authoring Multi-Project Builds). For a single-project build, a settings file is optional. Besides defining the included projects, you might need it to add libraries to your build script classpath (see Organizing Gradle Projects). Let’s first do some introspection with a single project build:
rootProject.name = 'basic'
println 'This is executed during the initialization phase.'
println 'This is executed during the configuration phase.'
tasks.register('configured') {
println 'This is also executed during the configuration phase, because :configured is used in the build.'
}
tasks.register('test') {
doLast {
println 'This is executed during the execution phase.'
}
}
tasks.register('testBoth') {
doFirst {
println 'This is executed first during the execution phase.'
}
doLast {
println 'This is executed last during the execution phase.'
}
println 'This is executed during the configuration phase as well, because :testBoth is used in the build.'
}
rootProject.name = "basic"
println("This is executed during the initialization phase.")
println("This is executed during the configuration phase.")
tasks.register("configured") {
println("This is also executed during the configuration phase, because :configured is used in the build.")
}
tasks.register("test") {
doLast {
println("This is executed during the execution phase.")
}
}
tasks.register("testBoth") {
doFirst {
println("This is executed first during the execution phase.")
}
doLast {
println("This is executed last during the execution phase.")
}
println("This is executed during the configuration phase as well, because :testBoth is used in the build.")
}
Output of gradle test testBoth
> gradle test testBoth
This is executed during the initialization phase.
> Configure project :
This is executed during the configuration phase.
This is executed during the configuration phase as well, because :testBoth is used in the build.
> Task :test
This is executed during the execution phase.
> Task :testBoth
This is executed first during the execution phase.
This is executed last during the execution phase.
BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed
> gradle test testBoth
This is executed during the initialization phase.
> Configure project :
This is executed during the configuration phase.
This is executed during the configuration phase as well, because :testBoth is used in the build.
> Task :test
This is executed during the execution phase.
> Task :testBoth
This is executed first during the execution phase.
This is executed last during the execution phase.
BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed
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. Look at the Settings class in the API documentation for more information.
Initialization
How does Gradle know whether to do a single or multi-project build?
If you trigger a multi-project build from a directory with a settings.gradle
file, Gradle uses it to configure the build.
Gradle also allows you to execute the build from within any subproject taking part in the build.[1]
If you execute Gradle from within a project with no settings.gradle
file, Gradle looks for a settings.gradle
file in the following way:
-
It looks for
settings.gradle
in parent directories. -
If not 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 multi-project hierarchy defined in the foundsettings.gradle
file. If not, the build is executed as a single project build. Otherwise a multi-project build is executed.
What is the purpose of this behavior? Gradle needs to determine whether the project you are in is a subproject of a multi-project build or not.
Of course, if it is a subproject, only the subproject and its dependent projects are built, but Gradle needs to create the build configuration for the whole multi-project build (see Configuration and Execution).
If the current project contains a settings.gradle
file, the build is always executed as:
-
a single project build, if the
settings.gradle
file does not define a multi-project hierarchy -
a multi-project build, if the
settings.gradle
file does define a multi-project hierarchy.
The automatic search for a settings.gradle
file only works for multi-project builds with a default project layout where project paths match the physical subproject layout on disk.
Gradle supports arbitrary physical layouts for a multi-project build, but for such arbitrary layouts you need to execute the build from the directory where the settings file is located.
For information on how to run partial builds from the root, see Executing tasks by their fully qualified name.
Gradle creates a Project object for every project taking part in the build. For a multi-project build these are the projects specified in the Settings object (plus the root project). Each project object has by default a name equal to the name of its top level directory, and every project except the root project has a parent project. Any project may have child projects.
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 Configuration and Execution.
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 two 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.
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 which has a hasTests
property value of true.
allprojects {
afterEvaluate { project ->
if (project.hasTests) {
println "Adding test task to $project"
project.task('test') {
doLast {
println "Running tests for $project"
}
}
}
}
}
hasTests = true
allprojects {
afterEvaluate {
if (extra["hasTests"] as Boolean) {
println("Adding test task to $project")
tasks.register("test") {
doLast {
println("Running tests for $project")
}
}
}
}
}
extra["hasTests"] = true
gradle -q test
> gradle -q test Adding test task to project ':project-a' Running tests for project ':project-a'
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.
gradle.afterProject { project ->
if (project.state.failure) {
println "Evaluation of $project FAILED"
} else {
println "Evaluation of $project succeeded"
}
}
gradle.afterProject {
if (state.failure != null) {
println("Evaluation of $project FAILED")
} else {
println("Evaluation of $project succeeded")
}
}
Output of gradle -q test
> gradle -q test
Evaluation of root project 'build-project-evaluate-events' succeeded
Evaluation of project ':project-a' succeeded
Evaluation of project ':project-b' FAILED
FAILURE: Build failed with an exception.
* Where:
Build file '/home/user/gradle/samples/project-b.gradle' line: 1
* What went wrong:
A problem occurred evaluating project ':project-b'.
> broken
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
* Get more help at https://help.gradle.org
BUILD FAILED in 0s
> gradle -q test
Evaluation of root project 'build-project-evaluate-events' succeeded
Evaluation of project ':project-a' succeeded
Evaluation of project ':project-b' FAILED
FAILURE: Build failed with an exception.
* Where:
Build file '/home/user/gradle/samples/project-b.gradle.kts' line: 1
* What went wrong:
broken
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
* Get more help at https://help.gradle.org
BUILD FAILED in 0s
You can also add a ProjectEvaluationListener to the Gradle to receive these events.
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.
tasks.whenTaskAdded { task ->
task.ext.srcDir = 'src/main/java'
}
tasks.register('a')
println "source dir is $a.srcDir"
tasks.whenTaskAdded {
extra["srcDir"] = "src/main/java"
}
val a by tasks.registering
println("source dir is ${a.get().extra["srcDir"]}")
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.
Task execution graph ready
You can receive a notification immediately after the task execution graph has been populated.
You can also add a TaskExecutionGraphListener to the TaskExecutionGraph to receive these events.
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.
tasks.register('ok')
tasks.register('broken') {
dependsOn ok
doLast {
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"
}
}
tasks.register("ok")
tasks.register("broken") {
dependsOn("ok")
doLast {
throw RuntimeException("broken")
}
}
gradle.taskGraph.beforeTask {
println("executing $this ...")
}
gradle.taskGraph.afterTask {
if (state.failure != null) {
println("FAILED")
} else {
println("done")
}
}
Output of gradle -q broken
> gradle -q broken
executing task ':ok' ...
done
executing task ':broken' ...
FAILED
FAILURE: Build failed with an exception.
* Where:
Build file '/home/user/gradle/samples/build.gradle' line: 6
* What went wrong:
Execution failed for task ':broken'.
> broken
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
* Get more help at https://help.gradle.org
BUILD FAILED in 0s
> gradle -q broken
executing task ':ok' ...
done
executing task ':broken' ...
FAILED
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':broken'.
> broken
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
* Get more help at https://help.gradle.org
BUILD FAILED in 0s
You can also use a TaskExecutionListener to the TaskExecutionGraph to receive these events.