Main Concepts

A dependency resolver is a pluggable class in Ivy which is used to:

The notion of artifact "downloading" is large: an artifact can be on a web site, or on the local file system of your machine. The download is thus the act of bring a file from a repository to the Ivy cache.

Moreover, the fact that it is the responsibility of the resolver to find Ivy files and download artifacts helps to implement various resolving strategies.

As you see, a dependency resolver can be thought of as a class responsible for describing a repository.

If you want to see which resolvers are available in Ivy, you can go to the resolvers configuration page.

Module configurations are described in the terminology page as a way to use or construct a module. Configurations being a central part of Ivy, they need more explanations as a concept.

When you define a way to use or construct a module, you are able to define which artifacts are published by this module in this configuration, and you are also able to define which dependencies are needed in this configuration.

Moreover, because dependencies in Ivy are expressed on modules and not on artifacts, it is important to be able to define which configurations of the dependency are required in the configuration you define of your module. That’s what is called configuration mapping.

If you use only simple modules and do not want to worry about configurations, you don’t have to worry about them. They’re still there under the hood because Ivy can’t work without configurations. But most of the time if you declare nothing, Ivy assumes that the artifacts of your module are published in all configurations, and that all the dependencies' configurations are required in all configurations. And it works in simple cases. But whenever you want to separate things within a module, or get more control over things published and get better dependencies resolution, configurations will meet most of your needs.

For details on how to declare your module configurations, how to declare in which configuration your artifacts are published, and how to declare configuration mapping, please refer to Ivy file documentation. The configurations tutorial is also a good place to go to learn more about this concept.

During configuration, Ivy allows you to define what are called Ivy variables. Ivy variables can be seen as Ant properties, and are used in a very similar way. In particular, you use a properties tag in the settings file to load a properties file containing Ivy variables and their values.

But the main differences between Ant properties and Ivy variables are that Ivy variables can be overridden, whereas Ant properties can’t, and that they are defined in separate environments.

Actually all Ant properties are imported into Ivy variables when the configuration is done (if you call Ivy from Ant). This means that if you define an Ant property after the call to configure, it will not be available as an Ivy variable. On the other hand, Ivy variables are NOT exported to Ant, thus if you define Ivy variables in Ivy, do not try to use them as Ant properties.

To use Ivy variables, you just have to follow the same syntax as for Ant properties: ${variablename} where variablename is the name of the variable.

Finally, it’s also important to be aware of the time of substitution of variables. This substitution is done as soon as possible. This means that when Ivy encounters a reference to a variable, it tries to substitute it if such a variable is defined. Consequently, any later modification of the variable will not alter the value already substituted.

Moreover, in an Ant environment, a bunch of variables are going to be set by default via the Ant property file loading mechanism (actually they are first loaded as Ant properties and then imported as Ivy variables, see Ant Tasks), and even in the Ant properties themselves there is going to be eager substitution on loading, effectively making it impossible to override some variable purely via the ivysettings.properties file. Some variables will really only be able to be overridden via Ant properties because of this.

Moreover, it’s also important to understand the difference between Ivy variables and Ivy pattern tokens. See the Patterns chapter below for what pattern tokens are.

Ivy patterns are used in many dependency resolvers and Ivy tasks, and are a simple way to structure the way Ivy works.

First let’s give an example. You can, for instance, configure the file system dependency resolver by giving it a pattern to find artifacts. This pattern can be like this: myrepository/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]

This pattern indicates that the repository we use is in a directory called myrepository.

In this directory we have directories having for name the name of the organisation of the module we look for. Then we have a directory per module, each having for name the name of the module. Then in module directories we find a directory per artifact type (jars, wars, ivys, …​), in which we find artifacts named by the artifact id, followed by a hyphen, then the revision, a dot, and the artifact extension. Not too difficult to understand is it? That’s it, you have understood the pattern concept!

To give a bit more explanation, a pattern is composed of tokens, which are replaced by actual values when evaluated for a particular artifact or module. Those tokens are different from variables because they are replaced differently for each artifact, whereas variables are usually given the same value.

You can mix variables and tokens in a pattern: ${repository.dir}/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]

The tokens available depends on where the pattern is used (will it be evaluated with artifacts or modules, for instance). But here are all the tokens currently available:

The difference between type and extension is explained in the Ivy file documentation.

(since 1.2) [organization] can be used instead of [organisation].

(since 1.3) Optional parts can be used in patterns.

This provides the possibility to avoid some input when a token is not defined, instead of having only the token as blank. Parenthesis are used to delimit the optional part, and only one token can be found inside the parenthesis.

So if you surround a token with ( and ), any other text which is between the parenthesis will be ignored if the token has no value.

For instance, suppose the pattern: abc(def[type]ghi)

A more real life example: The pattern [artifact](-[revision]).[ext] lets you accept both myartifact-1.0.jar when a revision is set, and myartifact.jar (instead of myartifact-.jar) when no revision is set. This is particularly useful when you need to keep control of artifact names.

(since 1.4) Extra attributes can be used as any other token in a pattern.

Ivy often needs to know which revision between two is considered the "latest". To know that, it uses the concept of latest strategy. Indeed, there are several ways to consider a revision to be the latest. You can choose an existing one or plug in your own.

But before knowing which revision is the latest, Ivy needs to be able to consider several revisions of a module. Thus Ivy has to get a list of files in a directory, and it uses the dependency resolver for that. So check if the dependency resolver you use is compatible with latest revisions before wondering why Ivy does not manage to get your latest revision.

Finally, in order to get several revisions of a module, most of the time you need to use the [revision] token in your pattern so that Ivy gets all the files which match the pattern, whatever the revision is. It’s only then that the latest strategy is used to determine which of the revisions is the latest one.

Ivy has three built-in latest strategies:

See also how to configure new latest strategies here.

A conflict manager is able to select, among a list of module revisions in conflict, a list of revisions to keep. Yes, it can select a list of revisions, even if most conflict managers select only one revision. But in some cases you will need to keep several revisions, and load in separate class loaders, for example.

A list of revisions is said to be in conflict if they correspond to the same module, i.e. the same organisation/module name couple.

The list of available conflict managers is available on the conflict manager configuration page.

For more details on how to setup your conflict managers by module, see the conflicts section in the Ivy file reference.

(since 1.3) In several places Ivy uses a pattern to match a set of objects. For instance, you can exclude several modules at once when declaring a dependency by using a pattern matching all the modules to exclude.

Ivy uses a pluggable pattern matcher to match those object names. 3 are defined by default:

Note also that with any matcher, the character '*' has the special meaning of matching anything. This is particularly useful with default values which do not depend on the matcher.

(since 1.4) Several tags in Ivy XML files are extensible with what is called extra attributes. The idea is very simple: if you need some more information to define your modules, you can add the attribute you want and you will then be able to access it as any other attribute in your patterns.

(since 2.0) It’s possible and recommended to use XML namespaces for your extra attributes. Using an Ivy extra namespace is the easiest way to add your own extra attributes.

Example: here is an Ivy file with the attribute color set to blue:

Then you must use the extra attribute when you declare a dependency on foo. Those extra attributes will indeed be used as identifiers for the module like the org, the name and the revision:

And you can define your repository pattern as:

Note that in patterns you must use the unqualified attribute name (no namespace prefix).

If you don’t want to use XML namespaces, it’s possible but you will need to disable Ivy file validation, since your files won’t fulfill anymore the official Ivy XSD. See the settings documentation to see how to disable validation.

(since 1.4) Ivy allows the use of checksums, also known as digests, to verify the correctness of a downloaded file.

The configuration of using the algorithm can be done globally or by dependency resolver. Globally, use the ivy.checksums variable to list the check to be done. On each resolver you can use the checksums attribute to override the global setting.

The setting is a comma separated list of checksum algorithms to use. During checking (at download time), the first checksum found is checked, and that’s all. This means that if you have a "SHA-256, sha1, md5" setting, then if Ivy finds a SHA-256 file, it will compare the downloaded file SHA-256 against this SHA-256, and if the comparison is ok, it will assume the file is ok. If no SHA-256 file is found, it will look for an sha1 file. If that isn’t found, then it checks for md5 and so on. If none is found no checking is done. During publish, all listed checksum algorithms are computed and uploaded.

By default checksum algorithms are "sha1, md5".

If you want to change this default, you can set the variable ivy.checksums. Hence, to disable checksum validation you just have to set ivy.checksums to "".

(since 1.4) When Ivy performs the dependency resolution and some other tasks, it fires events before and after the most important steps. You can listen to these events using Ivy API, or you can even register a trigger to perform a particular action when a particular event occur.

This is a particularly powerful and flexible feature which allows, for example, you to perform a build of a dependency just before it is resolved, or follow what’s happening during the dependency resolution process accurately, and so on.

For more details about events and triggers, see the triggers documentation page in the configuration section of this documentation.

(since 1.4) Circular dependencies can be either direct or indirect. For instance, if A depends on A, it’s a circular dependency, and if A depends on B which itself depends on A, this is also a circular dependency.

Prior to Ivy 1.4 circular dependencies caused a failure in Ivy. As of Ivy 1.4, the behaviour of Ivy when it finds a circular dependency is configurable through a circular dependency strategy.

3 built-in strategies are available:

See the configuration page to see how to configure the circular dependency strategy you want to use.

Ivy heavily relies on local caching to avoid accessing remote repositories too often, thus saving a lot of network bandwidth and time.

As a dependency manager, Ivy has a lot of file related operations, which most of the time use paths or path patterns to locate the file on the filesystem.

These paths can obviously be relative or absolute. We recommend to always use absolute paths, so that you don’t have to worry about what is the base of your relative paths. Ivy provides some variables which can be used as the base of your absolute paths. For instance, Ivy has a concept of base directory, which is basically the same as for Ant. You have access to this base directory with the ivy.basedir variable. So if you have a path like ${ivy.basedir}/ivy.xml, you have an absolute path. In settings files, you also have a variable called ivy.settings.dir which points to the directory in which your settings file is located, which makes defining paths relative to this directory very easy.

If you really want to use relative paths, the base directory used to actually locate the file depends on where the relative path is defined:

Most of the artifacts found in a repository are jars. They can be downloaded and used as is. But some other kind of artifacts required some unpacking after being downloaded and before being used. Such artifacts can be zipped folders and packed jars. Ivy supports that kind of artifact with packaging.

A packaged artifact needs to be declared as such in the module descriptor via the attribute packaging. The value of that attribute defined which kind of unpacking algorithm must be used. Here are the list of currently supported algorithms:

So, if in an ivy.xml, there would be declared a such artifact:

A file mymodule-1.2.3.jar.pack.gz would be download into the cache, and also uncompressed in the cache to mymodule-1.2.3.jar. Then any post resolve task which supports it, like the cachepath, will use the uncompressed file instead of the original compressed file.

It is possible to chain packing algorithm. The attribute packaging of a artifact expects a comma separated list of packing types, in packing order. For instance, an artifact mymodule-1.2.3.jar.pack.gz can have the packaging jar,pack200, so it would be uncompressed as a folder mymodule-1.2.3.