skip to content

What happens during Gradle's initialization phase, and how does it differ from the configuration phase?

level: juniorimportance: must knowfreq 70%

answer

  1. settings.gradle.kts evaluated
  2. Settings object + include()
  3. Project hierarchy built
  4. no build.gradle yet
  5. before configuration

basics

~10 s

Initialization runs first: Gradle evaluates settings.gradle(.kts) to learn which projects exist (via include), then creates a Project object for each. Configuration runs next, executing each project's build.gradle to register tasks.

solid answer

~40 s

A Gradle build has three phases: **initialization**, **configuration**, **execution**. Initialization is the first. Gradle finds and evaluates the `settings.gradle.kts` file, which produces a `Settings` object. The `include(...)` calls in settings declare which subprojects participate; from them Gradle instantiates a `Project` object for the root and each subproject, building the project hierarchy. No `build.gradle.kts` has run yet. Only after the hierarchy exists does **configuration** begin: every project's build script is evaluated, tasks are registered, and the task graph is assembled. The key distinction: initialization decides *which projects exist*; configuration decides *what each project contains*. A single-project build still has an initialization phase — settings is evaluated even when implicit.

code

kotlin · 5 lines
kotlin
// settings.gradle.kts — evaluated during initialization
rootProject.name = "my-app"
include("core", "web")
// At this point :core and :web Project objects are created,
// but their build.gradle.kts files have NOT run yet.

go deeper

for a junior

Recall the three phases in order and that settings.gradle is read first to learn which projects exist.

for a middle

Explain the Settings vs. Project distinction and that no build script runs until configuration.

for a senior

Connect initialization to settings-level features (pluginManagement, dependency management, version catalogs) applying before configuration.

for a principal

Frame how phase separation enables build-structure governance and composite builds across a large multi-module estate.

## The three lifecycle phases Every Gradle invocation moves through three ordered phases: 1. **Initialization** — determine the set of projects and build the `Project` hierarchy. 2. **Configuration** — evaluate each project's build script, registering tasks and wiring the task graph. 3. **Execution** — run the selected tasks' actions. ## What initialization actually does Gradle first locates the **settings file** (`settings.gradle.kts` in Kotlin DSL, `settings.gradle` in Groovy). This file is evaluated against a `Settings` object — the API for declaring the build's structure. The most important call is: ```kotlin rootProject.name = "my-app" include("core", "web", "data") ``` Each `include` string maps to a project path (`:core`, `:web`, `:data`). From these declarations Gradle instantiates one `Project` object per included project plus the `rootProject`. This is the **project hierarchy** — a tree rooted at `rootProject`. Crucially, during initialization the build scripts (`build.gradle.kts`) have **not** been evaluated; only `settings.gradle.kts` has run. ## Settings vs. Project - The `Settings` object is the receiver of `settings.gradle.kts`. It exposes `include`, `includeBuild`, `rootProject`, `pluginManagement`, `dependencyResolutionManagement`, and version-catalog declarations. - The `Project` object is the receiver of each `build.gradle.kts`, available only later in configuration. ## Why the separation matters Because the project set is fixed before any build script runs, Gradle can decide which build scripts to even read. It also lets settings-level features (plugin repositories, centralized dependency rules, version catalogs) apply uniformly before configuration. Composite builds are wired here too via `includeBuild("../other-build")`, which substitutes external dependencies with local builds. ## Single-project builds Even a build with no `settings.gradle.kts` has an initialization phase — Gradle synthesizes an implicit settings evaluation, creating just the `rootProject`. Adding a settings file is what unlocks multi-project structure.

  • Which file is evaluated during initialization, and what object is it evaluated against?
    settings.gradle.kts (or .gradle), evaluated against the Settings object.
  • Have build.gradle.kts scripts executed by the end of initialization?
    No. Build scripts run during the configuration phase; initialization only builds the project hierarchy from settings.

Initialization is the guest list (who's coming); configuration is each guest deciding what to bring; execution is the party itself.

saying these in an interview costs you the question

  • Saying tasks are registered during initialization (they're registered in configuration).
  • Claiming single-project builds skip initialization entirely.

context

resolving links…