// 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.

[[dependency-resolution-basics]]
= Dependency Resolution

Dependency resolution in Gradle can largely be thought of as a two-step process.

First, the _graph resolution_ phase constructs the dependency graph based on declared dependencies.
Second, the _artifact resolution_ phase fetches the actual files (artifacts) for the resolved components:

1. **Graph resolution phase**:
- Driven by declared dependencies and their metadata
- Uses the request attributes defined by the configuration being resolved

2. **Artifact resolution phase**:
- Based on nodes in the resolved dependency graph
- Matches each node to a variant and an artifact

The outcome of these processes can be accessed via different APIs, each designed for specific use cases.

[[sec:graph-resolution]]
== 1. Graph Resolution

During the _graph resolution_ phase, Gradle downloads and analyzes component metadata (GMM, POM, or Ivy XML) for declared and transitive dependencies.
This information is used to construct a *dependency graph*, which models the relationships between different components and their variants.
You can learn about how the graph is constructed in <<dependency_resolution_model.adoc#understanding_dependency_resolution_model,Understanding the Dependency Resolution Model>>.

The link:{javadocPath}/org/gradle/api/artifacts/result/ResolutionResult.html[`ResolutionResult` API] represents the output of the graph resolution phase, providing access to the resolved dependency graph without triggering artifact downloads.
The graph itself focuses on component variants, not the artifacts (files) associated with those variants:

- link:{javadocPath}/org/gradle/api/artifacts/result/ResolvedComponentResult.html[`ResolvedComponentResult`] - Represents a resolved component in the raw dependency graph.
- link:{javadocPath}/org/gradle/api/artifacts/result/ResolvedVariantResult.html[`ResolvedVariantResult`] - Represents a resolved variant of a component in the raw dependency graph.

See <<dependency_graph_resolution.adoc#dependency-graph-resolution,Graph Resolution>> to learn more.

[[sec:artifact-resolution]]
== 2. Artifact Resolution

Once the *dependency graph* is resolved, the _artifact resolution_ phase determines which actual files (artifacts) need to be downloaded or retrieved.

An link:{javadocPath}/org/gradle/api/artifacts/ArtifactView.html[`ArtifactView`] operates on top of the resolved graph, defined by the link:{javadocPath}/org/gradle/api/artifacts/result/ResolutionResult.html[`ResolutionResult`].
It allows you to query for specific artifacts based on attributes.
The same attributes used during _graph resolution_ typically guide _artifact selection_.

The  link:{javadocPath}/org/gradle/api/artifacts/ArtifactView.html[`ArtifactView` API] provides flexible ways to access these resolved artifacts:

- link:{javadocPath}/org/gradle/api/file/FileCollection.html[`FileCollection`] - A flat list of files, which is the most commonly way to work with resolved artifacts.
- link:{javadocPath}/org/gradle/api/artifacts/ArtifactCollection.html[`ArtifactCollection`] - Offers access to both the metadata and the files of resolved artifacts, allowing for more advanced artifact handling.

See <<artifact_resolution.adoc#artifact-resolution,Artifact Resolution>> to learn more.

== Controlling Resolution

An link:{javadocPath}/org/gradle/api/artifacts/transform/package-summary.html[`ArtifactTransform`] modifies the content of an artifact during dependency resolution, such as converting JAR files into custom formats.

An link:{javadocPath}/org/gradle/api/artifacts/ArtifactView.html[`ArtifactView`] permits customizing the artifact selection process, for example filtering components or requesting attributes that trigger artifact transforms.

When used together:

1. Register a `ArtifactTransform` to process artifacts.
2. Configure an `ArtifactView` to select artifacts based on attributes that differ from the original graph.
3. Query the transformed artifacts via the `ArtifactView` to access or process the transformed files.

See <<artifact_views.adoc#artifact-views,Artifact Views>> and <<artifact_transforms.adoc#artifact-transforms,Artifact Transforms>> to learn more.

[.text-right]
**Next Step:** <<dependency_graph_resolution.adoc#dependency-graph-resolution,Learn about Graph Resolution>> >>
