// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[build_lifecycle]]
= Gradle Build Lifecycle

The build lifecycle is the sequence of phases Gradle executes to turn your build scripts, source code, and more, into completed work.
From initializing the build environment to configuring projects and finally executing tasks.

image::gradle-basic-10.png[]

++++
<p>
  <div style="position:relative;padding-top:56.25%;">
    <iframe src="https://www.youtube-nocookie.com/embed/AryTb7QxgfA?si=yxiubs7URE4LRg-J&rel=0" frameborder="0" allowfullscreen
      style="position:absolute;top:0;left:0;width:100%;height:100%;"></iframe>
  </div>
</p>
++++

[[sec:build_phases]]
== Build Phases

A Gradle build has three distinct phases.

image::author-gradle-1.png[]

Gradle runs these phases in order:

[cols="1,1,1", options="header"]
|===
|Phase 1. Initialization
|Phase 2. Configuration
|Phase 3. Execution

| - Detects the *settings file* +
- Creates a link:{groovyDslPath}/org.gradle.api.initialization.Settings.html[`*Settings*`] instance +
- Evaluates the *settings file* to determine which projects (and included builds) make up the build +
- Creates a link:{groovyDslPath}/org.gradle.api.Project.html[`*Project*`] instance *for every project*

| - Evaluates the *build files of every project* participating in the build +
- Evaluates the *configuration* (input/output) of *tasks* +
- Creates a *task graph* for requested tasks

| - Schedules and *executes* the selected *tasks*
|===

image::build-lifecycle-example.png[]

The following example shows which parts of settings and build files correspond to various build phases:

====
include::sample[dir="snippets/fundamentals/authoring-builds/basic/kotlin",files="settings.gradle.kts[];build.gradle.kts[]"]
include::sample[dir="snippets/fundamentals/authoring-builds/basic/groovy",files="settings.gradle[];build.gradle[]"]
====

The following command executes the `test` task and `testBoth` task specified above.
Because Gradle only configures the tasks that are required to run (i.e., the requested task and its dependencies), the `configured` task will not be configured or executed:

====
[.multi-language-text.lang-kotlin]
=====
[source,bash]
----
$ ./gradlew test testBoth
----
[source,text]
----
include::{snippetsPath}/fundamentals/authoring-builds/basic/tests/buildlifecycle.out[]
----
=====
[.multi-language-text.lang-groovy]
=====
[source,bash]
----
$ ./gradlew test testBoth
----
[source,text]
----
include::{snippetsPath}/fundamentals/authoring-builds/basic/tests/buildlifecycle.out[]
----
=====
====

[[sec:initialization]]
=== Phase 1. Initialization

In the *initialization phase*, Gradle detects the set of projects (root and subprojects) and included builds participating in the build.

Gradle first evaluates the settings file, `settings.gradle(.kts)`, and instantiates a `Settings` object.

Then, Gradle instantiates `Project` object instances for each project included in the build (using `includeBuild()` or `include()` in the settings file).

[[sec:configuration]]
=== Phase 2. Configuration

In the *configuration phase*, Gradle adds tasks and other properties to the projects found by the initialization phase.

Gradle constructs the <<#sec:task_graph,task graph>> by understanding the dependencies between tasks.

[[sec:project_evaluation]]
[[sec:execution]]
[[sec:task_execution]]
=== Phase 3. Execution

In the *execution phase*, Gradle runs tasks.

Gradle uses the <<#sec:task_graph,task execution graphs>> generated by the configuration phase to determine which tasks to execute.
Gradle can execute tasks in parallel.

[[sec:task_graph]]
== Task Graphs

As a build author, you write build logic by defining tasks and declaring how they depend on one another.
Gradle uses this information to construct a **task graph** during the *configuration phase* that models the relationships between these tasks.

For example, if your project includes tasks such as `buildHtml`, `assembleDocs`, and `createDocs`, and you declare that `assembleDocs` depends on `buildHtml`, and `createDocs` depends on `assembleDocs`, Gradle constructs a graph with this order: `buildHtml` → `assembleDocs` → `createDocs`.

Gradle builds the task graph *before* executing any task(s).

Across all projects in the build, tasks form a http://en.wikipedia.org/wiki/Directed_acyclic_graph[Directed Acyclic Graph^] (DAG).

This diagram shows two example task graphs, one abstract and the other concrete, with dependencies between tasks represented as arrows:

image::task-dag-examples.png[]

[[build_lifecycle_events]]
*Your build scripts and plugins are responsible for declaring this task dependency graph*, either explicitly via the <<writing_tasks_intermediate.adoc#sec:task_dependencies,task dependency mechanism>> (e.g., `dependsOn`) or implicitly using <<incremental_build.adoc#sec:task_inputs_outputs,task annotation>> (e.g., by wiring task inputs and outputs).

[.text-right]
**Next Step:** <<writing_build_scripts_intermediate.adoc#writing_build_scripts,Learn how to write Build Scripts>> >>

== Hooking into the Build Lifecycle

As your build logic becomes more advanced, you might need to execute custom actions during specific build phases. Gradle exposes several APIs that let you listen to or react to key events in the lifecycle.

For a detailed guide on available callbacks and listeners, refer to <<build_lifecycle.adoc#sec:lifecycle_api, Lifecycle API>>.
