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

[[artifact-resolution]]
= Artifact Resolution

After constructing a dependency graph, Gradle can perform *artifact resolution* on the resolved graph.

Gradle APIs can be used to influence the process of *artifact selection* -- the mapping of a graph to a set of artifacts.

Gradle can then expose the results of artifact selection as an `ArtifactCollection`.
More commonly, the results are exposed as a `FileCollection`, which is a flat list of files.

[[sec:artifact-selection]]
== Artifact selection

*Artifact selection* operates on the dependency graph on a node-by-node basis.
Each node in the graph may expose multiple sets of artifacts, but only one of those sets may be selected.
For example, the `runtimeElements` variant of the Java plugins exposes a `jar`, `classes`, and `resources` artifact set.
These three artifact sets represent the same distributable, but in different forms.

For each node (variant) in a graph, Gradle performs attribute matching over each set of artifacts exposed by that node to determine the best artifact set.
If no artifact sets match the requested attributes, Gradle will attempt to construct an <<artifact_transforms.adoc#artifact-transforms,artifact transform>> chain to satisfy the request.

For more details on the attribute matching process, see the <<variant_attributes.adoc#sec:attribute-matching,attribute matching>> section.

[[sec:implicit-artifact-selection]]
== Implicit artifact selection

By default, the attributes used for artifact selection are the same as those used for variant selection during graph resolution.
These attributes are specified by the link:{javadocPath}/org/gradle/api/attributes/HasAttributes.html#getAttributes()[`Configuration#getAttributes()`] property.

To perform artifact selection (and implicitly, graph resolution) using these default attributes, use the `FileCollection` and `ArtifactCollection` APIs.

NOTE: Files can also be accessed from the configuration's `ResolvedConfiguration`, `LenientConfiguration`, `ResolvedArtifact` and `ResolvedDependency` APIs.
However, these APIs are in maintenance mode and are discouraged for use in new development.
These APIs perform artifact selection using the default attributes.

=== Resolving files

To resolve files, we first define a task that accepts a `ConfigurableFileCollection` as input:

====
include::sample[dir="snippets/dependencyManagement/performingResolution-artifactResolution/kotlin",files="build.gradle.kts[tags=file-resolution-task]"]
include::sample[dir="snippets/dependencyManagement/performingResolution-artifactResolution/groovy",files="build.gradle[tags=file-resolution-task]"]
====

Then, we can wire up a resolvable configuration's files to the task's input.
The `Configuration` directly implements `FileCollection` and can be wired directly.
Alternatively, wiring through `Configuration#getIncoming()` is a more explicit approach:

====
include::sample[dir="snippets/dependencyManagement/performingResolution-artifactResolution/kotlin",files="build.gradle.kts[tags=implicit-file-resolution]"]
include::sample[dir="snippets/dependencyManagement/performingResolution-artifactResolution/groovy",files="build.gradle[tags=implicit-file-resolution]"]
====

Running both of these tasks, we can see the output is identical:

----
include::{snippetsPath}/dependencyManagement/performingResolution-artifactResolution/tests/resolve-files.out[]
----

=== Resolving artifacts

Instead of consuming the files directly from the implicit artifact selection process, we can consume the artifacts, which contain both the files and the metadata.

This process is slightly more complicated, as in order to maintain Configuration Cache compatibility, we need to split the fields of `ResolvedArtifactResult` into two task inputs:

====
include::sample[dir="snippets/dependencyManagement/performingResolution-artifactResolution/kotlin",files="build.gradle.kts[tags=artifact-resolution-task]"]
include::sample[dir="snippets/dependencyManagement/performingResolution-artifactResolution/groovy",files="build.gradle[tags=artifact-resolution-task]"]
====

This task is initialized similarly to the file resolution task:

====
include::sample[dir="snippets/dependencyManagement/performingResolution-artifactResolution/kotlin",files="build.gradle.kts[tags=implicit-artifact-resolution]"]
include::sample[dir="snippets/dependencyManagement/performingResolution-artifactResolution/groovy",files="build.gradle[tags=implicit-artifact-resolution]"]
====

Running this task, we can see that file metadata is included in the output:

----
include::{snippetsPath}/dependencyManagement/performingResolution-artifactResolution/tests/resolve-artifacts.out[]
----

[[sec:customizing-artifact-selection]]
== Customizing artifact selection

An `ArtifactView` operates on top of the resolved dependency graph (i.e., `ResolutionResult`) but allows you to apply _different attributes_.

When you call a configuration's `getFiles()`, Gradle selects artifacts based on the attributes used during graph resolution.
However, an `ArtifactView` is more flexible.
It allows you to resolve artifacts from the graph with _custom attributes_.

An `ArtifactView` allows you to:

1. *Query artifacts with different attributes*:
* Suppose the graph resolved a dependency's `runtime` variant. You can use an `ArtifactView` to extract artifacts from its `api` variant instead, even if they weren't originally part of the resolved graph.
2. *Extract specific types of artifacts*:
* You can request only the `.jar` files or a specific artifact type (e.g., sources, Javadoc) by specifying an attribute like `artifactType`.
3. *Avoid side effects*:
* Using an `ArtifactView` allows you to extract artifacts without changing the underlying dependency resolution logic or configuration state.

In the following example, a producer project creates a library with the following variants and their attributes:



[.text-right]
**Next Step:** <<artifact_views.adoc#artifact-views,Learn about Artifact Views>> >>
