Ivy: Overview

Ivy describes itself as a tool for managing (recording, tracking, resolving and reporting) project dependencies, characterized by flexibility and configurability and by tight integration with Ant. Three properties follow from that and shape everything else:

As of the date of this page Ivy is an active subproject of Apache Ant, not in the Attic, and 2.6.0 is the current release. The facts worth knowing before adopting it:

Source: Apache Ivy: home page

Source: Ivy documentation: Environment / Configuration Requirements

Source: Ivy 2.6.0 documentation: Release Notes

Source: Apache Ivy: Security

Source: Apache IvyDE: home page

Ivy has a small vocabulary and uses it strictly; the reference pages and every error message assume it. The table maps each word to its Maven and Gradle counterpart, because that is the translation you will do in your head most often.

Ivy writes a module coordinate as organisation#module;revision, which is what you see in every log line (io.tidepool#tidepool-engine;1.0.0). Maven writes the same thing as groupId:artifactId:version. In Ivy the pieces after the revision (branch, artifact type, extension) are separate attributes, not part of the coordinate string. The cross-tool table in Comparing Ant, Maven & Gradle adds the rest of the mapping.

Two differences from Maven are worth stating now because they surprise people. First, a dependency in Ivy is on a module, never on an artifact: you ask for commons-csv;1.14.1 and a mapping between configurations decides which of its files you get (the next page shows how that goes wrong with the default mapping). Second, the status of a revision is a first-class value that dynamic revisions such as latest.release use to choose; Maven has no counterpart.

Source: Ivy documentation: Terminology

Every use of Ivy is one or more of five steps. They are the same whether you drive them from Ant tasks, as this page does, or from the command line.

Source: Ivy documentation: How does it work? Configure

Source: Ivy documentation: How does it work? Resolve

Source: Ivy documentation: How does it work? Retrieve

Source: Ivy documentation: How does it work? Publish

Ivy is one JAR, ivy-2.6.0.jar, 1,413,973 bytes, 889 entries, published as org.apache.ivy:ivy:2.6.0 on Maven Central. Its only job at install time is to be on Ant’s classpath so that the antlib:org.apache.ivy.ant tasks exist. The JAR has optional dependencies, such as Apache HttpClient and Jsch (the compatibility page names both) and Commons Compress for pack200 (the 2.6.0 release notes); their versions are in Ivy’s own descriptor, and you add them only when you use the feature that needs them.

The smallest useful Ivy project is two files. ivy.xml says what the tidepool engine module needs; build.xml runs resolve and retrieve.

Reading ivy.xml: info identifies the module (organisation, module, revision). configurations declares two views of it; runtime extends compile, which means everything required in compile is also required in runtime. The one dependency is commons-csv at an exact revision, and conf="compile->default" reads "in my compile configuration I need the default configuration of that module". Because the Maven POM of commons-csv is converted to Ivy configurations on the fly, default there means its own JAR plus its runtime dependencies. The ivy:resolve task with no attributes reads ivy.xml from the project directory, and ivy:retrieve copies into the pattern, where [conf], [artifact], [revision] and [ext] are tokens Ivy replaces. The next page, Ivy: Module Descriptors & Configurations, explains every part of that file.

The first run, with an empty cache, using the JAR from -lib:

Reading the output, in order:

The second run changes only the report; nothing is downloaded and retrieve finds the files already in place:

Only the resolve and retrieve lines of the second run are shown; the banner and found lines are the same as before. That speed (43 ms instead of 1.5 s) is the cache. Ivy assumes by default that a revision never changes, so once it has a descriptor and its artifacts in the cache it does not query the repository at all. The exceptions (dynamic revisions, changing revisions, resolvers with checkmodified) are on the conflicts and versions page.

What retrieve created, with the pattern build/lib/[conf]/[artifact]-[revision].[ext]:

Each configuration has its own copy of its files, which is the point of the [conf] token: the application’s runtime directory and the compile classpath can differ. Retrieve also supports sync="true" (delete files in the target that are not part of the retrieve), symbolic links, and, new in 2.6.0, override children that change the revision of a transitive dependency when the task does its own resolve from nested dependency elements (shown on the next page). Those options are in Ivy Ant Tasks.

Source: Ivy documentation: ivy:resolve

Source: Ivy documentation: ivy:retrieve

Source: Ivy tutorial: Quick Start

The default configuration is not a single resolver. It is five small files inside the JAR that are included in turn, and reading them explains the word public in the log and where local and shared come from. This is their content, read from the 2.6.0 JAR:

The other files define a filesystem resolver shared rooted at ${ivy.default.ivy.user.dir}/shared, a filesystem resolver local rooted at ${ivy.default.ivy.user.dir}/local, a chain named main with dual="true" that tries shared then public, and a chain named default with returnFirst="true" and checkmodified="true" that tries local then main. So, in plain words, a dependency is looked up in the local repository (the repository the Ivy tutorials publish to, a rough counterpart of Maven’s local repository for your own builds), then in a shared file repository, then in Maven Central, and the first hit wins. The ibiblio resolver with no root attribute points at Maven Central, as the principle page says. That is the whole reason a descriptor with a Maven coordinate works with no settings.

ivy.default.ivy.user.dir is the variable that points at the Ivy home directory; unless set it is .ivy2 in the user’s home directory (confirmed here by running with a different user.home, which created .ivy2/cache under it). The cache is in its cache subdirectory. All the examples on these pages set -Divy.default.ivy.user.dir=<scratch>/ivyuser on the command line, because Ant properties are imported as Ivy variables, so that nothing was written to the real ~/.ivy2 and the examples start from a known cache. That variable is used by the default settings but is not described on the settings reference page; treat setting it from the command line as a convenience, not a contract. For a project you would write your own settings file (and set the cache there with the caches element). The settings and resolvers page covers that.

Source: Ivy documentation: How does it work? Configure

Source: Ivy documentation: caches

Ivy’s cache has two parts, and the difference matters for sharing it and for cleaning it:

The default location for both is .ivy2/cache in the user’s home directory. After the first run above, the cache directory contained (the .original copies of each descriptor and the report stylesheets omitted):

How to read it:

The ivydata file for commons-csv shows the bookkeeping, and why the resolver is named in the logs:

The converted descriptor in the cache is what a POM looks like to Ivy, including the configurations Ivy invents for Maven scopes. A fragment (the Maven properties and the long lists of overrides are elided), read from ivy-1.14.1.xml in the cache:

That conversion is the key to using Maven Central from Ivy, and to the traps in it, and it is worked through on the next page. It is also why the cache is not a Maven repository layout and cannot be used by Maven or Gradle directly; the three tools' caches are compared in Repositories & Publishing Across Tools.

To start over, delete the cache directory, or run the cleancache task (see Ivy Ant Tasks). The release notes of 2.6.0 recommend this after upgrading from an older Ivy, because some fixes only apply to descriptors parsed afresh.

Source: Ivy documentation: Cache and Change Management

Source: Ivy documentation: caches

Ivy answers the same question as Maven’s dependency mechanism and Gradle’s dependency resolution, with a different split of responsibilities. The Apache Ivy project has its own comparison page with Maven; the table puts its points next to what is known on this site for the other two tools.

Three points from the Ivy side of the comparison are still true, and one is not. Still true: Ivy is far more configurable, since resolvers, conflict managers, version matchers and parsers are all plug-in points, and it can split metadata and artifacts into different repositories; the Maven comparison page notes that Maven has no repository chaining. Still true: Ivy’s reference documentation is extensive and covers every feature with examples. No longer true as stated: the comparison page says that in Maven "none of your dependencies will ever manage to get foo 1.1" without a change in your own declaration, as if that were a limitation. That is Maven’s nearest-wins rule, which Ivy can now apply itself with the nearest conflict manager, and which Maven has long complemented with dependencyManagement and BOMs (Maven dependencies, scopes and mediation). Gradle can also consume Ivy repositories and modules, which is the common bridge when a company has an Ivy repository and a Gradle build (Gradle repositories and content filtering).

When to choose Ivy today: you have an Ant build you do not want to migrate, you need configurations richer than Maven’s scopes, or you run a repository with a layout or a metadata format that Maven’s resolver cannot read. When not to: a new project with no Ant legacy will be better served by Maven or Gradle, and an Ant build that only needs to download a few JARs from Maven Central may be simpler with the Maven Resolver Ant Tasks, whose model is the same as Maven’s. The migration directions (Ant and Ivy to Maven or Gradle) are in Migrating Between Tools and in Deprecations & Migration.

Source: Apache Ivy / Apache Maven comparison

Source: Apache Ivy: Features