Gradle Build Lifecycle

A Gradle build has three phases that always run in this order:

Source: Gradle User Manual: Build Phases

The figure also shows the consequence that matters most in practice. Because a configuration cache hit skips initialization and configuration, every line of the settings and build scripts (and every hook they registered) that runs in those phases does not run on the next build. The next sections show it with real output. For the cache itself see Configuration Cache & Isolated Projects.

Sources: Phase 1. Initialization, Phase 2. Configuration, Phase 3. Execution

The scripts below print a line from every place a script can run code: the settings file, the root build file, each subproject build file, a task configuration block, and the doFirst and doLast blocks of a task. The marker in front of each line says where it came from. This is the tidepool settings file and root build file:

Each subproject has a build file that applies java-library, prints [model] configuring ${project.path} (and the same with [engine] and [cli]), and registers a report task whose doLast prints a line. Running the root task hello gives (the output is the same for both DSLs):

Read the output as the three phases:

Run the same build with the configuration cache. The first run stores the entry and prints the same lines as above (preceded by Calculating task graph as no cached configuration is available for tasks: hello and followed by Configuration cache entry stored.). The second run reuses it:

Every [settings], [root], [cli], [engine] and [model] line printed during configuration is gone, because neither the settings file nor any build file ran. Only the execution phase ran. These scripts are compatible with the configuration cache (printing is allowed); the point is that code in the configuration phase is skipped on a hit, so it must never be the place where something needs to happen on every build.

Asking for a task of another project changes what is configured only a little, because all projects are configured unless configure on demand is on (see Configuration on demand). Here the same build, asked for the report task of the three subprojects at once (./gradlew --console=plain --configuration-cache report, first run) printed

(the first line, Calculating task graph as no cached configuration is available for tasks: report, is omitted). All three report tasks are configured first, and only then does the first one run. Output interleaving between phases is therefore never a sign that something ran "twice"; it is the phases.

Source: Gradle User Manual: The Phases in Build Scripts

The classic lifecycle bug is code that was meant to run when the task runs, written where it runs when the task is configured. The task below should print its message when it is run as part of a deployment. It prints the message whenever the task is configured, and it does nothing at execution time:

The message appears before the > Task :deploy header, which is the tell, and the task itself is UP-TO-DATE, because it has no action to run. Running ./gradlew deployFixed prints

Because register is lazy, ./gradlew help did not print the message at all in the same project: the deploy block runs only when something requests the task. The bug is therefore intermittent, which makes it worse: a task that was never requested stays quiet until a script, a report or an IDE import realizes it. Older eager APIs make it visible on every build. In the Groovy DSL, task eagerDeploy { println ... } creates the task at once and runs the block on every build, for every command, including help:

(./gradlew help, trimmed after the > Task :help header.) In the Kotlin DSL the equivalents tasks.create(...) and val x by tasks.creating { } are deprecated in Gradle 9.8.1: the compiler reports them as deprecated, the warning for creating says to use registering, and others point to the Gradle 9.6 upgrading guide. The old task name << { ... } shorthand, which wrapped the whole body in an action, was removed in Gradle 5.0 (use doLast and tasks.register). The rule is the same as before: anything that must happen at execution belongs in doFirst, doLast, an @TaskAction method, or a task input/output declaration, never in the configuration block.

Both DSL versions of deploy and deployFixed were run with Gradle 9.8.1 and print the same output; the println calls are compatible with the configuration cache.

Sources: Gradle User Manual: Task Configuration Avoidance, Phase 2. Configuration

During configuration Gradle turns the dependsOn relationships of the requested tasks (and the ones that plugins declare) into a directed acyclic graph of tasks across all projects, and it builds this graph completely before the first task runs. That is what makes --dry-run possible. The example below declares three tasks with dependencies, a task that is always skipped, and a finalizedBy cleanup task:

A dry run walks the graph without running any task action:

A real run, ./gradlew --console=plain publishDemo, prints:

Four facts follow from the output:

For Java projects the graph is what the plugins declare. In the same project (with the java-library plugin applied to the three subprojects, and the [graph] lines of the previous script still present),

lists the tasks that assemble of the command-line project needs, in execution order, with the library tasks of the two projects it depends on:

The Maven reactor builds modules in dependency order and runs the same phases in each (see Maven Build Lifecycle); Gradle computes the graph of tasks across all projects instead, so a task of one project can run before or alongside tasks of another.

Sources: Gradle User Manual: Task Graphs, Command-Line Interface: execution options (dry run)

The manual lists every point at which Gradle evaluates a script or fires a hook, in order, when the configuration cache and Isolated Projects are off. The table keeps the entries that matter for build logic; the numbers are the manual’s.

Source: Gradle User Manual: Build Lifecycle Timeline

The manual also warns that code that eagerly asks a configuration for its resolved state (configuration.files, resolvedConfiguration, iterating a configuration) triggers dependency resolution immediately, at that point of configuration. With the configuration cache on, graph and artifact resolution must complete during configuration anyway, because the result has to be serialized. Resolution itself is covered in Dependency Management Fundamentals.

Before the lifecycle API there were listeners: interfaces such as BuildListener, TaskExecutionListener and TaskExecutionGraphListener, and the matching gradle.addBuildListener(...), gradle.buildFinished { } and gradle.taskGraph.afterTask { } callbacks. They are created during configuration and called during execution, so the configuration cache cannot restore them. The manual’s table of the common ones in Gradle 9.8.1:

Source: Gradle User Manual: Build Listeners

Gradle.buildFinished was marked deprecated in Gradle 7 and buildStarted in Gradle 6 (per the lifecycle page); buildStarted was removed in Gradle 7.0, while in Gradle 9.8.1 buildFinished is still there. It works in a normal build:

The Kotlin DSL compiler reports it as deprecated ('fun buildFinished(action: Action<in BuildResult>): Unit' is deprecated); the Groovy DSL compiles it silently. Without the configuration cache the line is printed after the last task (./gradlew --console=plain -I bf.init.gradle.kts :tidepool-model:report):

With --configuration-cache the same callback fails the build, on a cache miss as well as a hit, because the cache refuses to store a registration it could not replay (the report links are omitted from the listing; the Groovy DSL init script gives the same message with a Where: line for its script):

The two supported replacements are a build service whose close() runs at the end of the build, and a flow action that receives the build result. Both are shown next. The manual names the same two: a build service that implements OperationCompletionListener replaces taskGraph.afterTask and observes each task completion, and its close() takes the place of buildFinished; for end-of-build logic that does not need to see each task, a dataflow action is the supported replacement.

Sources: Configuration Cache requirements: using build listeners, Replacing taskGraph.afterTask and buildFinished with a build service, Gradle Javadoc: Gradle

In a multi-project build every project is configured on every run, as the earlier hello output showed. Configuration on demand configures only the projects that the requested tasks need. The root project is always configured; the project of the current directory is configured when Gradle runs without tasks; and a project is configured when a requested task lives in it, when a task dependency of a requested task points at it by path, or when a standard project dependency makes it needed. The manual calls the feature incubating, and Gradle prints Configuration on demand is an incubating feature. when it is used (so, as an incubating feature, it can change); it works well for decoupled projects, which interact only through declared dependencies and task dependencies.

Enable it for one run with --configure-on-demand, or for every run with org.gradle.configureondemand=true in gradle.properties (see Build Environment & Properties). The same tidepool build, asked for :tidepool-model:report without and with the flag (the first lines of each output; these runs did not use the configuration cache):

With the flag, only the root project and tidepool-model were configured; the engine and the command-line project were not. Asking for :tidepool-cli:report configured the root project and tidepool-cli, and still not tidepool-engine, although tidepool-cli has an api(project(":tidepool-engine")) dependency: the report task does not use that dependency, so nothing pulled the engine in. A task that does need it pulls it in: ./gradlew --configure-on-demand :tidepool-cli:compileJava --dry-run configured the root project, tidepool-cli, tidepool-engine and tidepool-model.

The cost is the coupling rule. Gradle allows a project to read or change another project’s configuration, and that is what breaks configuration on demand: if tidepool-engine reads a property that only the build file of tidepool-model sets, the result depends on whether tidepool-model happened to be configured. Configuration injection with allprojects { } or subprojects { } is the usual source of coupling, which is one reason the manual steers toward convention plugins (see Convention Plugins & Sharing Build Logic). For the layout of such builds see Multi-Project Builds. Do not use configuration on demand and the configuration cache expecting the same behaviour: the cache skips configuration of all projects on a hit, whereas on-demand configuration only narrows which projects a miss configures.

Sources: Gradle User Manual: Enable configure-on-demand, Decoupled projects, Gradle’s feature lifecycle: incubating

Gradle 8.14.x was not available for these runs, so this section is not run here; it summarizes the release history and the official documentation:

On Gradle 8.14 every example on this page except the 9.x-only behaviour would be expected to run, since gradle.lifecycle, flow actions, configuration on demand and the configuration cache all exist there. Gradle 9 needs JVM 17 or newer to run Gradle itself, while projects can still compile with older JDKs through toolchains. For the full table see Gradle Versions, Compatibility & Release History.

Sources: Gradle User Manual: Build Listeners, Upgrading from Gradle 6.x to 7.0: Removal of BuildListener.buildStarted(Gradle), Gradle 8.1 release notes: New Dataflow Actions

The book Gradle in Action (Gradle 1.7) teaches the three phases and builds on Project and Task objects, and that part is still true. What changed:

Sources: Configuration Cache requirements, Gradle 9.0.0 release notes