////
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     https://www.apache.org/licenses/LICENSE-2.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.
////

Now that you have been introduced to the main Ivy terminology and concepts, it is time to give some explanation of how Ivy works.

== Usual cycle of modules between different locations

image::images/main-tasks.png[]

More details on ant tasks link:ant{outfilesuffix}[here].

== Configure

Ivy needs to be configured to be able to resolve your dependencies. This configuration is usually done with a settings file, which defines a set of dependency resolvers. Each resolver is able to find Ivy files and/or artifacts, given simple information such as organisation, module, revision, artifact name, artifact type and artifact extension.

The configuration is also responsible for indicating which resolver should be used to resolve which module. This configuration is dependent only on your environment, i.e. where the modules and artifacts can be found.

A default configuration is used by Ivy when none is given. This configuration uses an link:resolver/ibiblio{outfilesuffix}[ibiblio resolver] pointing to https://repo1.maven.org/maven2/ to resolve all modules.

== Resolve

The resolve time is the moment when Ivy actually resolves the dependencies of one module. It first needs to access the Ivy file of the module for which it resolves the dependencies.

Then, for each dependency declared in this file, it asks the appropriate resolver (according to settings) to find the module (i.e. either an Ivy file for it, or its artifacts if no Ivy file can be found). It also uses a filesystem based cache to avoid asking for a dependency if it is already in cache (at least if possible, which is not the case with latest revisions).

If the resolver is a composite one (i.e. a chain or a dual resolver), several resolvers may actually be called to find the module.

When the dependency module has been found, its Ivy file is downloaded to the Ivy cache. Then Ivy checks if the dependency module has dependencies, in which case it recursively traverses the graph of dependencies.

All over this traversal, conflict management is done to prevent access to a module as soon as possible.

When Ivy has traversed the whole graph, it asks the resolvers to download the artifacts corresponding to each of the dependencies which are not already in the cache and which have not been evicted by conflict managers. All downloads are made to the Ivy cache.

Finally, an XML report is generated in the cache, which allows Ivy to easily know what are all the dependencies of a module, without traversing the graph again.

After this resolve step, two main steps are possible: either build a path with artifacts in the cache, or copy them to another directory structure.

== Retrieve

What is called retrieve in Ivy is the act of copying artifacts from the cache to another directory structure. This is done using a pattern, which indicates to Ivy where the files should be copied.

For this, Ivy uses the XML report in the cache corresponding to the module it should retrieve to know which artifacts should be copied.

It also checks if the files are not already copied to maximize performances.

== Building a path from the cache

In some cases, it is preferable to use artifacts directly from the cache. Ivy is able to use the XML report generated at resolve time to build a path of all artifacts required.

This can be particularly useful when building plug-ins for IDEs.

== Reports

Ivy is also able to generate readable reports describing the dependencies resolution.

This is done with a simple XSL transformation of the XML report generated at resolve time.

== Publish

Finally, Ivy can be used to publish a particular version of a module in your repository, so that it becomes available for future resolving. This task is usually called either manually or from a continuous integration server.