// 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]]
= Build Lifecycle

As a build author, you define tasks and specify dependencies between them.
Gradle guarantees that tasks will execute in the order dictated by these dependencies.

Your build scripts and plugins configure this task dependency graph.

For example, if your project includes tasks such as `build`, `assemble`, and `createDocs`, you can configure the build script so that they are executed in the order: `build` -> `assemble` -> `createDocs`.

== Task Graphs

Gradle builds the task graph *before* executing any task.

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]]
Both plugins and build scripts contribute to the task graph via the <<tutorial_using_tasks.adoc#sec:task_dependencies,task dependency mechanism>> and <<incremental_build.adoc#sec:task_inputs_outputs,annotated inputs/outputs>>.

[[sec:build_phases]]
== Build Phases

A Gradle build has three distinct phases.

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

Gradle runs these phases in order:

Phase 1. Initialization::
- Detects the `settings.gradle(.kts)` 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.
Phase 2. Configuration::
- Evaluates the build scripts, `build.gradle(.kts)`, of every project participating in the build.
- Creates a task graph for requested tasks.
Phase 3. Execution::
- Schedules and executes the selected tasks.
- Dependencies between tasks determine execution order.
- Execution of tasks can occur in parallel.

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

=== Example

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

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

The following command executes the `test` and `testBoth` tasks specified above.
Because Gradle only configures requested tasks and their dependencies, the `configured` task never configures:

[source.multi-language-sample,kotlin]
----
> gradle test testBoth
include::{snippetsPath}/buildlifecycle/basic/tests/buildlifecycle.out[]
----
[source.multi-language-sample,groovy]
----
> gradle test testBoth
include::{snippetsPath}/buildlifecycle/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` instances for each project.

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

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

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

In the *execution phase*, Gradle runs tasks.

Gradle uses the task execution graphs generated by the configuration phase to determine which tasks to execute.

[[sec:task_execution]]

[.text-right]
**Next Step:** <<writing_settings_files.adoc#writing_settings_files,Learn how to write Settings files>> >>
