Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

The Gradle Build Lifecycle: Initialization, Configuration, Execution

Understand Gradle's three build phases, why code in a task body runs later than code in the build script, and how this causes the most common beginner bugs.

Every Gradle build runs in three phases, always in the same order: initialization, configuration and execution. If you only remember one thing about Gradle's design, make it this. Nearly every confusing beginner moment ("why did my message print before the build started?", "why is this property empty?") comes from not knowing which phase a line of code runs in.

This lesson explains each phase, shows how to see them in action, and lists the habits that keep configuration code fast and correct. The Gradle snippets are read-only; a runnable Java stand-in reproduces the phase ordering so you can experiment.

The three phases

flowchart LR
  A["1. Initialization<br/>read settings.gradle(.kts)<br/>decide which projects exist"] --> B["2. Configuration<br/>run each build script<br/>build the task graph"]
  B --> C["3. Execution<br/>run the selected tasks<br/>in dependency order"]

Gradle decides what exists, then what to do, then does it.

1. Initialization

Gradle finds settings.gradle(.kts), evaluates it, and creates a Project object for each project listed with include. Settings is also where plugin repositories and dependency resolution management are declared. No tasks exist yet.

2. Configuration

Gradle evaluates every build script of every included project (unless configure-on-demand is on). Code at the top level of build.gradle.kts, and inside plugins {}, dependencies {}, tasks.register(...) { ... } configuration blocks, runs now. The result is a complete task graph with every task's inputs, outputs and dependencies set. Nothing has been compiled or tested yet.

3. Execution

Gradle looks at the tasks you asked for (build, test, ...), takes the needed part of the graph, and runs those tasks in order. Code in doFirst {}, doLast {} and the task's own action runs here.

Seeing the phases

Add println statements to a build script (Kotlin DSL shown, read-only):

Kotlin
println("configuration: top of the script")

tasks.register("hello") {
    println("configuration: inside the hello block")
    doFirst { println("execution: doFirst") }
    doLast  { println("execution: doLast") }
}

Run ./gradlew hello and the output order is:

TEXT
configuration: top of the script
configuration: inside the hello block

> Task :hello
execution: doFirst
execution: doLast

Both configuration lines appear before the task header, because they ran in phase 2. Only the two doFirst/doLast lines ran during the task itself.

Lifecycle messages help you see this too: run with --console=plain to print every task header, and add -i for more detail. You can also hook into phases from the settings or build file with gradle.beforeProject, gradle.taskGraph.whenReady { } and gradle.buildFinished-style listeners; modern builds prefer BuildService and flow actions, covered in later chapters.

Which phase is this code in?

Code Phase
rootProject.name = "x" in settings Initialization
plugins { ... }, dependencies { ... } Configuration
println directly in a build script Configuration
tasks.register("t") { description = "..." } (the block) Configuration
doFirst { } / doLast { } / @TaskAction Execution

A runnable stand-in: three phases in Java

The stand-in is not Gradle. Lambdas play the role of configuration blocks and task actions, and a small runner executes them in the same three phases. Notice where each println lands.

Java Stand-in: initialization, configuration, execution

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that task bye was configured even though it never ran. That is a real Gradle trait: configuration code runs for all tasks, whether or not they will execute. Slow code there slows every build, even ./gradlew --version-sized ones. That is why lazy task registration exists.

A runnable stand-in: a configuration-time mistake

A classic bug: reading a value in the configuration phase that is only produced in the execution phase.

Java Stand-in: reading a value too early

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The early copy stays null; the supplier sees the new value. Gradle's answer to this problem is the Provider type, which behaves like that supplier.

Good habits

  • Keep configuration code cheap: no network calls, no reading large files, no running processes.
  • Put real work inside task actions (doLast, @TaskAction), not in the configuration block.
  • Prefer tasks.register over tasks.create so unused tasks are not even configured.
  • Use ./gradlew help --task <name> and --dry-run (-m) to inspect the graph without executing anything.
  • If a build feels slow before any task header appears, the time is going into initialization or configuration; profile it (see the performance chapter).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In which phase does a println placed directly at the top of build.gradle.kts run?

    Top-level script code runs when Gradle evaluates the script, which is the configuration phase, before any task executes.
  2. 2. What is the job of the initialization phase?

    Initialization reads settings.gradle(.kts) and creates the Project instances.
  3. 3. A task is configured but you never request it. What happens to its configuration block?

    Eagerly created tasks are configured whether or not they execute. tasks.register avoids this by configuring only when needed.
  4. 4. Where should expensive work, such as processing files, be placed?

    Task actions run only when the task executes, so unrelated builds are not slowed down.

Summary

  • Gradle runs initialization, configuration, then execution, in that order.
  • Initialization decides which projects exist; configuration builds the task graph; execution runs tasks.
  • Top-level script code and task configuration blocks run at configuration time; doFirst/doLast and @TaskAction run at execution time.
  • Configuration code runs for every task, so keep it cheap.
  • Use lazy APIs (providers, tasks.register) to avoid reading values too early.

Next: Gradle Command-Line Basics