Table of Contents
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.
A Gradle build has three distinct phases.
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.
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 introduced an incubating opt-in feature called configuration on demand. In this mode, Gradle configures only relevant projects (see Section 24.1.1.1, “Configuration on demand”).
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.
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 multiproject build must have a
settings.gradle
file in the root project of the multiproject hierarchy. It is required because the
settings file defines which projects are taking part in the multi-project build (see
Chapter 24, 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 Chapter 41, Organizing Build Logic). Let's first do some introspection with a single project
build:
Example 20.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.' } task 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.' }
Output of gradle test testBoth
> gradle test testBoth This is executed during the initialization phase. This is executed during the configuration phase. This is also executed during the configuration phase. This is executed during the configuration phase as well. :test This is executed during the execution phase. :testBoth This is executed first during the execution phase. This is executed last 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. Look at
the Settings
class in the API documentation for more information.
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 24, Multi-project Builds).
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 most 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.
In the settings file you can use a set of methods to build the project tree. Hierarchical and flat physical layouts get special support.
Example 20.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' is mapped by default to a folder 'services/api'
(relative from the project root). You only need to specify the leaves of the tree.
This means that the inclusion of the path 'services:hotels:api' will result in creating 3 projects:
'services', 'services:hotels' and 'services:hotels:api'.
The includeFlat
method takes directory names as an argument. These directories
need to exist as siblings of the root project directory. The location of these directories
are considered as child projects of the root project in the multi-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:
Using this descriptor you can change the name, project directory and build file of a project.
Example 20.4. Modification of elements of the project tree
settings.gradle
println rootProject.name
println project(':projectA').name
settings.gradle
rootProject.name = 'main' project(':projectA').projectDir = new File(settingsDir, '../my-project-a') project(':projectA').buildFileName = 'projectA.gradle'
Look at the ProjectDescriptor
class in the API documentation for more information.
How does Gradle know whether to do a single or multiproject build? If you trigger a multiproject build
from a directory with a settings file, things are easy. But Gradle also allows you to execute the
build from within any subproject taking part in the build.
[9]
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 in a directory called master
which has the same nesting level
as the current dir.
If not found yet, it searches parent directories.
If not found yet, 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? Gradle needs to determine whether the project you are in is
a subproject of a multiproject 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 multiproject
build (see Chapter 24, Multi-project Builds). You can use the -u
command line option to tell Gradle not to look in the parent hierarchy for a settings.gradle
file. The
current project is then always built 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 automatic search for a settings.gradle
file only works for multi-project
builds with a physical hierarchical or flat layout. For a flat layout you must additionally follow the
naming convention described above (“master
”). 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 information on how to run partial builds from the root see
Section 24.4, “Running tasks by their absolute path”.
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.
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 24, Multi-project Builds.
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.
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.
Example 20.5. 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 20.6. 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.
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 20.7. Setting of certain property to all tasks
build.gradle
tasks.whenTaskAdded { task -> task.ext.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.
You can receive a notification immediately after the task execution graph has been populated. We have seen this already in Section 14.13, “Configure by DAG”.
You can also add a TaskExecutionGraphListener
to the
TaskExecutionGraph
to receive these events.
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 20.8. 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.