skip to content

Initialization Phase

6 roadmaps5 questions

Settings evaluation: deciding which projects exist, which builds are included, and constructing the Project hierarchy before any build script runs. Interviewers ask because everything structural must happen here or not at all.

on this pageshow

explore

questions

5

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…

open as a page

What is the difference between include and includeBuild in settings.gradle.kts?

level: middleimportance: must knowfreq 60%

basics

~10 s

include adds a subproject to the current build (one shared build hierarchy). includeBuild wires in a separate, standalone Gradle build as a composite build, substituting its outputs for matching external dependencies.

open as a page

How does Gradle build the project hierarchy from include() declarations, and how do nested project paths map to directories?

level: middleimportance: should knowfreq 35%

basics

~10 s

include(":web:api") creates intermediate projects (:web and :web:api), each a Project node under rootProject. By default a project path maps to a matching directory; you can override the location with project(":api").projectDir.

open as a page

What is the Settings object, and what kinds of build-wide configuration belong in settings.gradle.kts rather than in a build script?

level: middleimportance: should knowfreq 45%

basics

~10 s

The Settings object is the receiver of settings.gradle.kts. It declares build structure (include/includeBuild, rootProject.name) and build-wide concerns: pluginManagement repositories, dependencyResolutionManagement, and version catalogs — things that must apply before any build script runs.

open as a page

When does an init.gradle (initialization) script run relative to settings.gradle, and what is each responsible for?

level: seniorimportance: should knowfreq 30%

basics

~10 s

Init scripts run first, before settings.gradle is evaluated, against a Gradle object — used for machine/CI-wide setup (mirrors, credentials, global plugins). settings.gradle runs next, against the Settings object, defining the build's project structure.

open as a page