Ivy: Settings & Resolvers

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This page covers the settings file of Apache Ivy 2.6.0 (ivysettings.xml): how Ivy finds it, how it is structured, how variables work, how the cache is configured, and above all the resolvers that decide where modules come from. It is the third of six Ivy pages. The Ivy Overview explains what Ivy is and shows the built-in default settings and the layout of the cache; Module Descriptors & Configurations covers ivy.xml; Conflicts & Versions covers what happens once the resolvers have found several candidates; Ivy Ant Tasks covers the tasks that use the settings. None of that is repeated here.

How the examples were run. Every example was executed on 2026-10-16 with Apache Ant 1.10.18, Apache Ivy 2.6.0 (from Maven Central, org.apache.ivy:ivy:2.6.0, SHA-1 11a76d2e1d439170c61b47a7a13110a78c6c0824, checked against the published .sha1 file) and JDK 26 on macOS, each in its own scratch directory with its own Ivy cache, so nothing touched the real ~/.ivy2. Ant was started with ant -lib lib -Divy.default.ivy.user.dir=<scratch>/build/ivy-user, where lib holds the Ivy JAR (and, from the page’s TTL section on, the Apache ORO JAR that the glob matcher needs). Output is shown as printed, with the scratch directory shortened to .. Left out are the Buildfile: and target-name lines, the Ivy banner line, the :: resolving dependencies :: line, the progress dots that Ivy prints while it downloads, BUILD SUCCESSFUL and the Total time line; nothing else is edited. Where a run needed a server, it was a throwaway Python HTTP server on localhost (one that requires HTTP Basic authentication, one that forwards to Maven Central and logs each request, plain ones for settings and a mirror). These servers are test aids and are not shown. The only password in the examples is the placeholder local-test-only, passed on the command line. The two SSH-based resolvers need a real SSH daemon and were not run here; their section says so. Local repositories were written by a small helper script that creates ivy.xml and a JAR in the layout shown; the trees are listed where they matter.

How Ivy finds its settings

Ivy needs a settings file before it can do anything. From Ant there are two ways to load one: ivy:settings, a type that is read lazily, when the first task needs it, and ivy:configure, a task that is read at once, so a broken file fails at that line. Both take file or url (file wins if both are given), and configure also has override, which says what to do when a settings with the same id is already loaded. When neither attribute is given, or when a task runs with no settings or configure at all, Ivy picks in this order: the file named by the variable ivy.settings.file (default ivysettings.xml in the project directory) if it exists; the URL named by ivy.settings.url; and finally the built-in default settings. The configure page documents the URL fallback as available since 2.3; the settings page does not mention it, and the runs below show that the implicit settings of an ivy:resolve honour it as well.

The first run has no ivysettings.xml next to the build file, and the Ant property ivy.settings.url points at a settings file served by a local HTTP server. The build file only contains an ivy:resolve and an echo of the variable. The served settings file is the url example from the section on url resolvers further down:

build-implicit.xml
<project name="implicit-demo" default="resolve" xmlns:ivy="antlib:org.apache.ivy.ant">
  <target name="resolve">
    <ivy:resolve file="ivy.xml"/>
    <echo>ivy.settings.url=${ivy.settings.url}</echo>
  </target>
</project>
[ivy:resolve] :: loading settings :: url = http://localhost:8766/ivysettings.xml
[ivy:resolve] 	confs: [default]
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in http-repo
[ivy:resolve] downloading http://localhost:8765/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] io.tidepool#tidepool-model;1.0.0!tidepool-model.jar (5ms)
[ivy:resolve] :: resolution report :: resolve 39ms :: artifacts dl 6ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      default     |   1   |   1   |   1   |   0   ||   1   |   1   |
	---------------------------------------------------------------------
     [echo] ivy.settings.url=http://localhost:8766/ivysettings.xml

The same with an explicit <ivy:configure/> before the resolve; only the name of the task that loads the settings differs:

[ivy:configure] :: loading settings :: url = http://localhost:8766/ivysettings.xml
[ivy:resolve] 	confs: [default]
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in http-repo
[ivy:resolve] downloading http://localhost:8765/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] io.tidepool#tidepool-model;1.0.0!tidepool-model.jar (4ms)
[ivy:resolve] :: resolution report :: resolve 34ms :: artifacts dl 5ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      default     |   1   |   1   |   1   |   0   ||   1   |   1   |
	---------------------------------------------------------------------
     [echo] ivy.settings.url=http://localhost:8766/ivysettings.xml

loading settings :: url = ... is the line to look for when a build does not pick up the settings you expected. The ivy.settings.url variable is also set by Ivy once it has loaded settings from a file or from a URL, and ivy.settings.dir (the directory of the file, or the part of the URL before the last slash) is what lets a settings file refer to its neighbours. When there is no file and no URL, Ivy uses its built-in settings, described in the Ivy Overview: a module that exists in none of the default repositories gets a module not found after the three places that were tried (local, shared, public) are listed.

Source: Ivy documentation: settings

Source: Ivy documentation: configure

Source: Ivy documentation: Settings Files

Several settings can coexist in one build: give each ivy:settings an id and point each task at one with settingsRef. Every variable the file defines is also exposed as an Ant property, under its own name and under the name suffixed with a dot and the settings id, which is how two settings files can be told apart. ivy:settings and ivy:configure can also carry nested credentials elements; see the credentials section below.

A complete settings file

The smallest useful file names a default resolver and defines it. A real project wants more: variables kept outside the file, a cache location it controls, and the resolvers in a file of their own. This one is the base for the first runs on this page. The ivysettings.xml:

<ivysettings>
  <properties file="${ivy.settings.dir}/ivysettings.properties" override="false"/>
  <property name="central.root" value="https://repo1.maven.org/maven2/" override="false"/>
  <settings defaultResolver="main"/>
  <caches defaultCacheDir="${ivy.cache.dir}" resolutionCacheDir="${ivy.cache.dir}/resolution" useOrigin="${use.origin}" lockStrategy="artifact-lock-nio"/>
  <include file="${ivy.settings.dir}/resolvers.xml"/>
</ivysettings>

Its properties file, next to it:

ivy.cache.dir=${basedir}/build/ivy-cache
local.repo=${basedir}/repo
use.origin=false

The included resolvers.xml, a chain that asks a local file repository first and Maven Central second:

<ivysettings>
  <resolvers>
    <chain name="main" returnFirst="true">
      <filesystem name="local" m2compatible="false">
        <ivy pattern="${local.repo}/[organisation]/[module]/[revision]/ivy.xml"/>
        <artifact pattern="${local.repo}/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
      </filesystem>
      <ibiblio name="central" m2compatible="true" root="${central.root}"/>
    </chain>
  </resolvers>
</ivysettings>

The descriptor, the build file and the layout of the local repository (written by the helper script; tidepool-model is the part of tidepool that is "published" here):

ivy.xml
<ivy-module version="2.0">
  <info organisation="io.tidepool" module="tidepool-engine" revision="1.0.0-SNAPSHOT"/>
  <configurations>
    <conf name="compile"/>
    <conf name="runtime" extends="compile"/>
  </configurations>
  <dependencies defaultconfmapping="compile->default;runtime->default">
    <dependency org="io.tidepool" name="tidepool-model" rev="1.0.0"/>
    <dependency org="org.apache.commons" name="commons-csv" rev="1.14.1"/>
  </dependencies>
</ivy-module>
build.xml
<project name="settings-demo" default="resolve" xmlns:ivy="antlib:org.apache.ivy.ant" basedir=".">
  <property name="settings.file" value="${basedir}/settings/ivysettings.xml"/>
  <ivy:settings file="${settings.file}"/>
  <target name="resolve">
    <ivy:resolve file="ivy.xml" conf="*"/>
    <ivy:cachepath pathid="cp" conf="runtime" log="quiet"/>
    <pathconvert property="cp.str" refid="cp" pathsep="${line.separator}"/>
    <echo>${cp.str}</echo>
  </target>
</project>
The local repository
./io.tidepool/tidepool-model/1.0.0/ivy.xml
./io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar

The first run, from an empty cache. tidepool-model is found in local, the Apache Commons CSV JAR and its two transitive dependencies in central:

[ivy:resolve] :: loading settings :: file = ./settings/ivysettings.xml
[ivy:resolve] 	confs: [compile, runtime]
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in local
[ivy:resolve] 	found org.apache.commons#commons-csv;1.14.1 in central
[ivy:resolve] 	found commons-io#commons-io;2.20.0 in central
[ivy:resolve] 	found commons-codec#commons-codec;1.19.0 in central
[ivy:resolve] downloading ./repo/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] io.tidepool#tidepool-model;1.0.0!tidepool-model.jar (1ms)
[ivy:resolve] downloading https://repo1.maven.org/maven2/org/apache/commons/commons-csv/1.14.1/commons-csv-1.14.1.jar ...
[ivy:resolve] 	[SUCCESSFUL ] org.apache.commons#commons-csv;1.14.1!commons-csv.jar (131ms)
[ivy:resolve] downloading https://repo1.maven.org/maven2/commons-io/commons-io/2.20.0/commons-io-2.20.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] commons-io#commons-io;2.20.0!commons-io.jar (166ms)
[ivy:resolve] downloading https://repo1.maven.org/maven2/commons-codec/commons-codec/1.19.0/commons-codec-1.19.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] commons-codec#commons-codec;1.19.0!commons-codec.jar (131ms)
[ivy:resolve] :: resolution report :: resolve 1574ms :: artifacts dl 431ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      compile     |   4   |   4   |   4   |   0   ||   4   |   4   |
	|      runtime     |   4   |   4   |   4   |   0   ||   4   |   4   |
	---------------------------------------------------------------------
     [echo] ./build/ivy-cache/io.tidepool/tidepool-model/jars/tidepool-model-1.0.0.jar
     [echo] ./build/ivy-cache/org.apache.commons/commons-csv/jars/commons-csv-1.14.1.jar
     [echo] ./build/ivy-cache/commons-io/commons-io/jars/commons-io-2.20.0.jar
     [echo] ./build/ivy-cache/commons-codec/commons-codec/jars/commons-codec-1.19.0.jar

The second run changes nothing in the inputs and does not touch the network. The module counts show search and dwnlded at 0, and the found lines still name the resolver that served each module, because the cache remembers it (see the ivydata file in the Ivy Overview):

[ivy:resolve] :: loading settings :: file = ./settings/ivysettings.xml
[ivy:resolve] 	confs: [compile, runtime]
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in local
[ivy:resolve] 	found org.apache.commons#commons-csv;1.14.1 in central
[ivy:resolve] 	found commons-io#commons-io;2.20.0 in central
[ivy:resolve] 	found commons-codec#commons-codec;1.19.0 in central
[ivy:resolve] :: resolution report :: resolve 84ms :: artifacts dl 4ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      compile     |   4   |   0   |   0   |   0   ||   4   |   0   |
	|      runtime     |   4   |   0   |   0   |   0   ||   4   |   0   |
	---------------------------------------------------------------------
     [echo] ./build/ivy-cache/io.tidepool/tidepool-model/jars/tidepool-model-1.0.0.jar
     [echo] ./build/ivy-cache/org.apache.commons/commons-csv/jars/commons-csv-1.14.1.jar
     [echo] ./build/ivy-cache/commons-io/commons-io/jars/commons-io-2.20.0.jar
     [echo] ./build/ivy-cache/commons-codec/commons-codec/jars/commons-codec-1.19.0.jar

Reading the file top to bottom:

  • properties loads ivysettings.properties as Ivy variables. ${ivy.settings.dir} is set by Ivy; ${basedir} inside the properties file is the Ant project directory, because Ant properties are visible to Ivy variables.

  • property with override="false" defines central.root only if nothing has defined it yet. That makes it a default that a command line, an environment variable or an earlier file can win over.

  • settings names the default resolver, the one used for every module that no modules rule matches.

  • caches fixes where the repository cache and the resolution cache live and how concurrent access is locked.

  • include pulls in resolvers.xml as if its content were written at that spot. The included file must itself be a complete ivysettings document.

flowchart TD D["dependency from ivy.xml"] --> M{"modules rule matches organisation and name?"} M -- "yes" --> R1["the resolver named by the rule"] M -- "no" --> R2["the defaultResolver of the settings element"] R1 --> K["resolver type"] R2 --> K K --> S["standard resolver: ibiblio, filesystem, url, sftp, ..."] K --> C["chain: ask each child in order"] K --> U["dual: descriptors from one child, artifacts from the other"] C --> S U --> S S --> CA[("Ivy cache")]

Source: Ivy documentation: Settings Files and resolvers

The elements of a settings file

The root element is ivysettings. Its children, as listed by the reference page:

Element What it does

property

Sets one variable: name, value, override (default true), and, since 2.4, ifset and unlessset, which set the variable only if another one is (or is not) defined.

properties

Loads a properties file (file) or the environment (environment="env", then ${env.PATH}, since 2.0) as variables; override defaults to true.

settings

Defaults: resolver, latest strategy, conflict manager, branch, resolve mode, circular dependency strategy, validation.

include

Includes another settings document by file or url; optional="true" (since 2.4) ignores a missing file.

classpath, typedef

Add locations to the class path used to load plug-ins and register new types (resolvers, conflict managers, latest strategies, parsers).

credentials

HTTP credentials for a host and optional realm.

signers

Detached signature generators (OpenPGP, pgp, since 2.2) used when publishing.

lock-strategies

Registers lock strategies; no-lock, artifact-lock and artifact-lock-nio (since 2.4) are built in.

caches

The cache system, with child cache elements and, inside them, ttl rules.

latest-strategies

Registers latest strategies; latest-time, latest-revision and latest-lexico are built in.

parsers, namespaces, macrodef

Module descriptor parsers, name translation between repositories, and macro resolvers.

resolvers

The dependency resolvers, each with a unique name.

conflict-managers

Registers conflict managers beyond the built-in ones (see Conflicts & Versions).

modules

Rules that map module sets to a resolver, conflict manager, branch or resolve mode.

outputters, statuses, triggers

Report formats, the list of module statuses (release, milestone, integration by default), and handlers for Ivy events.

version-matchers, timeout-constraints

Version matchers beyond the built-in ones, and named connect/read timeouts that resolvers can reference.

Source: Ivy documentation: Settings Files, structure

The settings element

The settings element has the attributes that most often differ between projects. All are optional:

Attribute Meaning

defaultResolver

Name of the resolver used when no modules rule matches. Required in practice unless every module is covered by a rule.

defaultLatestStrategy

Default latest-revision.

defaultConflictManager

Default latest-revision; nearest is available from 2.6.0.

defaultBranch

The branch assumed for every module without its own; default none (since 1.4).

defaultResolveMode

default unless changed (since 2.0).

circularDependencyStrategy

warn (default), error or ignore (since 1.4).

validate

Validate ivy.xml files against the Ivy schema; default true. A resolver’s own validate wins.

httpRequestMethod

HEAD (default) or GET for probing URLs; the reference suggests switching it when a firewall or proxy dislikes HEAD (since 2.0).

useRemoteConfig

Load the ivyrep and ibiblio layouts from a remote settings file; default false (since 1.2). Leave it alone.

defaultCache, checkUpToDate, cacheIvyPattern, cacheArtifactPattern

Deprecated; use the same-named attributes of caches, or overwriteMode of retrieve.

Source: Ivy documentation: settings

Variables, properties and the override trap

Everything in a settings file is expanded with Ivy variables. They come from five places: Ant properties (every Ant property, including -D values, is visible), Java system properties (since 1.4), property and properties elements in the file, the environment through <properties environment="env"/>, and variables Ivy itself defines such as ivy.settings.dir. The rule that bites is the one on override: both property and properties default to override="true", so a file can silently replace a value that was given on the command line.

The base settings above load ivysettings.properties, which says use.origin=false. Run with -Duse.origin=true and with the same file but the attribute override="false" removed from the properties line, and the command line loses. The last three entries of the classpath are from the cache, as they would be with the default, and the first entry (tidepool-model) is also from the cache, although useOrigin was asked for:

     [echo] ./build/ivy-cache/io.tidepool/tidepool-model/jars/tidepool-model-1.0.0.jar
     [echo] ./build/ivy-cache/org.apache.commons/commons-csv/jars/commons-csv-1.14.1.jar
     [echo] ./build/ivy-cache/commons-io/commons-io/jars/commons-io-2.20.0.jar
     [echo] ./build/ivy-cache/commons-codec/commons-codec/jars/commons-codec-1.19.0.jar

With override="false" (the file shown earlier) the same command line wins, and tidepool-model is used straight from the repository, because a filesystem resolver is local:

     [echo] ./repo/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar
     [echo] ./build/ivy-cache/org.apache.commons/commons-csv/jars/commons-csv-1.14.1.jar
     [echo] ./build/ivy-cache/commons-io/commons-io/jars/commons-io-2.20.0.jar
     [echo] ./build/ivy-cache/commons-codec/commons-codec/jars/commons-codec-1.19.0.jar

The environment works the same way. The enterprise section below uses <property name="repo.root" value="${env.TIDEPOOL_REPO_ROOT}" override="false" ifset="env.TIDEPOOL_REPO_ROOT"/> so that an environment variable is the first choice and a literal is the fallback. The example on the include reference page spells the attribute overwrite; the reference for property says override, which is what these runs used.

Source: Ivy documentation: property and include

Caches, lock strategies and TTL

The caches element configures the two parts of the cache described in the Ivy Overview. These are its attributes:

Attribute Meaning

default

Name of the cache used by resolvers that do not name one. Without it, an instance called default-cache is created.

defaultCacheDir

Base directory for both caches; default .ivy2/cache in the user’s home.

resolutionCacheDir, repositoryCacheDir

Separate directories for the two caches. The reference recommends setting both instead of defaultCacheDir when you want them apart. The repository cache must not point at a directory used as a repository.

ivyPattern, artifactPattern

Where descriptors and artifacts go in the cache; defaults in Ivy 2.6.0 (DefaultRepositoryCacheManager) [organisation]/[module](/[branch])/ivy-[revision].xml and [organisation]/[module](/[branch])/[type]s/[artifact]-[revision](-[classifier])(.[ext]); the reference page still lists the older forms without branch and classifier. Change only to read the cache from another tool, which the reference does not recommend.

useOrigin

Do not copy artifacts of local resolvers (the filesystem resolver) into the cache; use their original location. Descriptors are still copied. Default false.

lockStrategy

no-lock (default), artifact-lock (file locks via createNewFile) or artifact-lock-nio (java.nio.FileLock, since 2.4). Use a locking one when several processes share a cache.

checkUpToDate

Deprecated.

A cache child defines another repository cache with its own basedir, patterns, useOrigin, lockStrategy, memorySize (parsed descriptors kept in memory, default 150) and defaultTTL. A resolver picks one with its cache attribute, which is how one cache per repository is set up. The settings above chose artifact-lock-nio; the cache then contained one small .lck file beside each module’s data, next to ivydata-<revision>.properties.

Source: Ivy documentation: caches

Source: Ivy documentation: cache

Source: Ivy documentation: lock-strategies

TTL: how long a dynamic revision is trusted

When a dependency says latest.integration (or a range, or 1.0.+), Ivy has to ask the repositories which revision that is. To avoid doing it on every resolve, it stores the answer for a time to live. The default is ivy.cache.ttl.default = 10s, set in the properties file inside the Ivy JAR (read from the 2.6.0 JAR). A ttl element inside cache sets rules, evaluated in order against the revision before resolution (latest.integration, not 1.1.0), and the first match wins; otherwise defaultTTL of the cache applies. The duration syntax is Xd Xh Xm Xs Xms, for example 2h 5m; eternal keeps the answer until a refresh; 0ms switches the caching off. The ttl attributes are organisation, module, revision, any extra attribute, matcher (default exact) and duration.

This cache sets the default to eternal and a one-hour rule, from a variable, for modules of io.tidepool whose name starts with tidepool-:

ivysettings.xml
<ivysettings>
  <property name="ttl" value="1h" override="false"/>
  <settings defaultResolver="local"/>
  <caches default="tidepool-cache">
    <cache name="tidepool-cache" basedir="${basedir}/build/cache" defaultTTL="eternal">
      <ttl organisation="io.tidepool" module="tidepool-*" matcher="glob" duration="${ttl}"/>
    </cache>
  </caches>
  <resolvers>
    <filesystem name="local">
      <ivy pattern="${basedir}/repo/[organisation]/[module]/[revision]/ivy.xml"/>
      <artifact pattern="${basedir}/repo/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
    </filesystem>
  </resolvers>
</ivysettings>

The glob matcher needs the Apache ORO library. Without it on the class path (only the Ivy JAR was there for this run) the whole settings file fails to load:

BUILD FAILED
./build.xml:4: impossible to configure ivy:settings with given file: ./ivysettings.xml : java.text.ParseException: failed to load settings from file:./ivysettings.xml: impossible to add configured child for cache on class org.apache.ivy.core.settings.IvySettings: java.lang.NoClassDefFoundError: org/apache/oro/text/regex/MalformedPatternException

Adding oro:oro:2.0.8 (SHA-1 5592374f834645c4ae250f4c9fbb314c9369d698, from Maven Central) with a second -lib fixes it. The scenario then publishes 1.0.0, resolves latest.integration, publishes 1.1.0, resolves again, resolves with refresh="true", and finally publishes 1.2.0 and resolves with the rule turned off (-Dttl=0ms):

### 1: only 1.0.0 is published
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in local
[ivy:resolve] 	[1.0.0] io.tidepool#tidepool-model;latest.integration
[ivy:resolve] downloading ./repo/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] io.tidepool#tidepool-model;1.0.0!tidepool-model.jar (2ms)
### 2: 1.1.0 published, ttl 1h
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in local
[ivy:resolve] 	[1.0.0] io.tidepool#tidepool-model;latest.integration
### 3: same, refresh=true
[ivy:resolve] 	found io.tidepool#tidepool-model;1.1.0 in local
[ivy:resolve] 	[1.1.0] io.tidepool#tidepool-model;latest.integration
[ivy:resolve] downloading ./repo/io.tidepool/tidepool-model/1.1.0/tidepool-model-1.1.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] io.tidepool#tidepool-model;1.1.0!tidepool-model.jar (2ms)
### 4: 1.2.0 published, ttl=0ms
[ivy:resolve] 	found io.tidepool#tidepool-model;1.2.0 in local
[ivy:resolve] 	[1.2.0] io.tidepool#tidepool-model;latest.integration
[ivy:resolve] downloading ./repo/io.tidepool/tidepool-model/1.2.0/tidepool-model-1.2.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] io.tidepool#tidepool-model;1.2.0!tidepool-model.jar (2ms)

Step 2 is the point: 1.1.0 was already in the repository, but the cached answer (1.0.0) was still inside its hour, so Ivy did not even look. refresh on ivy:resolve is the escape hatch for one run; 0ms is the setting for a cache where latest.integration must always be fresh.

Source: Ivy documentation: ttl

Source: Ivy documentation: version-matchers

Resolvers

A resolver is the object that knows where one repository is and what it looks like. The built-in resolvers, with their type from the reference page, are:

Tag Type Finds modules in

ibiblio

Standard

A Maven-style repository; with m2compatible="true" and no root, Maven Central.

filesystem

Standard

Directories, described by patterns. Fast, and it supports atomic publishing.

url

Standard

Any URL-accessible repository, described by patterns; publishing works over HTTP when the server allows it.

mirroredurl

Standard

A url repository from a list of mirrors (since 2.3).

sftp, ssh

Standard

Repositories reached over SSH; both can publish (since 1.4).

vfs

Standard

Anything Apache Commons VFS can read.

jar

Standard

A repository stored inside one JAR.

packager

Standard

Ivy files plus packaging instructions found by URL; it then builds the artifacts. Affected by CVE-2026-26032, fixed in Ivy 2.6.0 (see below).

obr, updatesite, osgiagg

Standard, standard, composite

OSGi repositories, Eclipse update sites and a chain of the two.

chain

Composite

Delegates to a list of resolvers.

dual

Composite

Delegates descriptors to one resolver and artifacts to another.

ivyrep

Standard

The defunct Ivyrep repository; see the section on dead resolvers.

bintray

Standard

Bintray, which has been shut down; see below.

Source: Ivy documentation: resolvers, built-in

Attributes every standard resolver shares

These attributes are the same on every standard resolver. They are what make a repository behave well or badly, so they are worth knowing before the individual resolvers:

Attribute Meaning

name

Unique name, used by defaultResolver, modules rules, chains and the found ... in <name> log lines.

validate, checkconsistency

Validate descriptors against the XSD (default: the task or settings value) and check that a descriptor describes the module that was requested (default true).

descriptor

optional (default) accepts a module without a descriptor, so an artifact alone is a module; required refuses it. allownomd is the deprecated spelling.

checksums

Comma-separated list of checksum algorithms used to verify downloads and to write them when publishing. The default is the variable ivy.checksums, which is sha1,md5 in the 2.6.0 properties file.

force

Use this resolver "in force mode": it looks for any revision of the module (it rewrites the request to latest.integration) and, if it finds one, that revision wins even in a chain with returnFirst="false". Put it first in a chain to prefer local developer builds (since 2.0).

checkmodified

Compare the last-modified date of the descriptor with the cached copy. Default from ivy.resolver.default.check.modified, which is false.

changingPattern, changingMatcher

Revisions matching the pattern are treated as changing, as if every dependency on them had changing="true". The default matcher is exactOrRegexp.

alwaysCheckExactRevision

Check the exact revision even for special ones such as latest.integration; default from ivy.default.always.check.exact.revision, false.

latest

The latest strategy for this resolver (see the Conflicts & Versions page).

cache

The name of the cache instance.

namespace

The namespace used to translate coordinates; default system.

signer

The detached signature generator used when publishing; by default published files are not signed (since 2.2).

timeoutConstraint

The name of a timeout-constraint (since 2.5): connect and read timeouts for this resolver.

Two properties change how resolvers that read POMs behave. A POM-reading resolver also probes for the -sources and -javadoc artifacts, which costs requests even if nothing downloads them. Since 2.5, ivy.maven.lookup.sources=false and ivy.maven.lookup.javadoc=false switch the probes off; the enterprise section below counts what that saves.

Source: Ivy documentation: resolvers, common features and attributes

ibiblio and Maven Central

ibiblio reads a Maven repository. Its attributes are root (default: Maven Central), pattern (default: the Maven layout), m2compatible (default false), usepoms (default true) and useMavenMetadata (default true). With m2compatible="true" Ivy converts dots in the organisation to slashes, reads POMs as module descriptors (translating Maven scopes into Ivy configurations) and uses maven-metadata.xml to list the available versions, which is what makes 1.16.+ and ranges work on a server that does not allow directory listings. usepoms="false" takes the JARs and ignores the POMs, so transitive dependencies are lost, and is rarely what you want. The limitation to know: in m2compatible mode Ivy cannot list organisations, so repreport and similar repository-wide tasks do not work.

The first run on this page already used it: <ibiblio name="central" m2compatible="true" root="${central.root}"/> found Commons CSV and its two dependencies on Maven Central. Because the default root is Maven Central, the attribute is only there so that the value can be overridden.

Source: Ivy documentation: ibiblio resolver

filesystem

filesystem resolves from directories using ivy and artifact child elements, each with a pattern made of tokens such as [organisation], [module], [revision], [branch], [artifact], [type] and [ext]. There may be several of each, tried in order. Patterns must be absolute (since 2.0), which is why the examples build them from ${basedir}. It also has m2compatible (dots to slashes), local (default true, meaning artifacts are not copied into the cache when useOrigin is on) and transactional.

Atomic publishing, since 2.0, writes the new revision to a directory whose revision ends in .part and renames it into place, which needs the revision to be a directory in both patterns with the same prefix up to it, forbids overwriting and forbids revision names that end in .part. transactional="auto" (the default) uses it when the patterns allow, true demands it and fails otherwise, false never uses it. The local repository above follows the layout [organisation]/[module]/[revision]/[artifact]-[revision].[ext], which satisfies those rules.

Source: Ivy documentation: filesystem resolver, atomic publish

chain, and what returnFirst does

A chain holds other resolvers and tries them in order. returnFirst (default false) decides what "found" means: with false the whole chain is asked and, for a dynamic revision, the latest revision among all the answers is kept; with true the first resolver that has the module answers, and the rest are not asked. dual="true" makes it behave like a dual resolver: a module found by any child has its artifacts looked for in the whole chain, so descriptor and artifact may come from different children. returnFirst="true" is faster and is the right choice for "company repository first, then Central"; false is what you need when two repositories can hold different revisions of the same module and the newest must win.

The test has two file repositories, repo-a with tidepool-model 1.0.0 and repo-b with 1.1.0, in a chain of the two. The dependency is latest.integration. With returnFirst="false" the newest revision wins, and with true the first resolver that has any revision wins:

ivysettings.xml
<ivysettings>
  <settings defaultResolver="both"/>
  <caches defaultCacheDir="${basedir}/build/cache"/>
  <resolvers>
    <chain name="both" returnFirst="${chain.returnFirst}">
      <filesystem name="repo-a">
        <ivy pattern="${basedir}/repo-a/[organisation]/[module]/[revision]/ivy.xml"/>
        <artifact pattern="${basedir}/repo-a/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
      </filesystem>
      <filesystem name="repo-b">
        <ivy pattern="${basedir}/repo-b/[organisation]/[module]/[revision]/ivy.xml"/>
        <artifact pattern="${basedir}/repo-b/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
      </filesystem>
    </chain>
  </resolvers>
</ivysettings>
[ivy:resolve] 	found io.tidepool#tidepool-model;1.1.0 in repo-b
[ivy:resolve] 	[1.1.0] io.tidepool#tidepool-model;latest.integration
     [echo] ./build/cache/io.tidepool/tidepool-model/jars/tidepool-model-1.1.0.jar
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in repo-a
[ivy:resolve] 	[1.0.0] io.tidepool#tidepool-model;latest.integration
     [echo] ./build/cache/io.tidepool/tidepool-model/jars/tidepool-model-1.0.0.jar

The first listing is -Dchain.returnFirst=false, the second -Dchain.returnFirst=true.

Source: Ivy documentation: chain resolver

url, credentials and checksums

url is the generic resolver: ivy and artifact patterns that are URLs, and m2compatible. A repository on a web server needs nothing else, and one behind authentication needs the credentials element of the settings file (its host, optional realm, username and passwd), chosen by the host and the realm that the server announces in its WWW-Authenticate header. The password here is a variable, so it never appears in the file:

ivysettings.xml
<ivysettings>
  <property name="repo.url" value="http://localhost:8765" override="false"/>
  <credentials host="localhost" realm="Tidepool Repository" username="builder" passwd="${repo.password}"/>
  <settings defaultResolver="http-repo"/>
  <caches defaultCacheDir="${basedir}/build/cache"/>
  <resolvers>
    <url name="http-repo">
      <ivy pattern="${repo.url}/[organisation]/[module]/[revision]/ivy.xml"/>
      <artifact pattern="${repo.url}/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
    </url>
  </resolvers>
</ivysettings>

The module is served from the throwaway server on localhost:8765, which requires the user builder. With the right password the resolve succeeds:

[ivy:resolve] :: loading settings :: file = ./ivysettings.xml
[ivy:resolve] 	confs: [default]
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in http-repo
[ivy:resolve] downloading http://localhost:8765/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] io.tidepool#tidepool-model;1.0.0!tidepool-model.jar (8ms)
[ivy:resolve] :: resolution report :: resolve 61ms :: artifacts dl 10ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      default     |   1   |   1   |   1   |   0   ||   1   |   1   |
	---------------------------------------------------------------------

With a wrong one, Ivy does not say "unauthorized". The server answers 401 and Ivy reports a module that was not found, listing the URLs it tried, which is easy to misread as a missing module (the same output appears if no credentials were supplied for the host):

[ivy:resolve] :: loading settings :: file = ./ivysettings.xml
[ivy:resolve] 	confs: [default]
[ivy:resolve] :: resolution report :: resolve 51ms :: artifacts dl 0ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      default     |   1   |   0   |   0   |   0   ||   0   |   0   |
	---------------------------------------------------------------------
[ivy:resolve] :: problems summary ::
[ivy:resolve] :::: WARNINGS
[ivy:resolve] 		module not found: io.tidepool#tidepool-model;1.0.0
[ivy:resolve] 	==== http-repo: tried
[ivy:resolve] 	  http://localhost:8765/io.tidepool/tidepool-model/1.0.0/ivy.xml
[ivy:resolve] 	  -- artifact io.tidepool#tidepool-model;1.0.0!tidepool-model.jar:
[ivy:resolve] 	  http://localhost:8765/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar
[ivy:resolve] 		::::::::::::::::::::::::::::::::::::::::::::::
[ivy:resolve] 		::          UNRESOLVED DEPENDENCIES         ::
[ivy:resolve] 		::::::::::::::::::::::::::::::::::::::::::::::
[ivy:resolve] 		:: io.tidepool#tidepool-model;1.0.0: not found
[ivy:resolve] 		::::::::::::::::::::::::::::::::::::::::::::::
[ivy:resolve] :: USE VERBOSE OR DEBUG MESSAGE LEVEL FOR MORE DETAILS
BUILD FAILED
./build.xml:6: impossible to resolve dependencies:
	resolve failed - see output for details

The nested credentials of ivy:settings and ivy:configure do the same job from Ant; the settings reference notes that HTTP authentication through the attributes host, realm, username and passwd of those tasks needs HttpComponents HttpClient 4.5.3 or later on the class path. That variant was not run here; the credentials element in the settings file worked in the run above with only the Ivy and ORO JARs. Passwords belong in a variable fed from the environment or the command line, or in a file outside version control, never in the settings file itself.

Checksums are verified for every download. The server above has no .sha1 or .md5 files, so Ivy’s probes for them (visible as HEAD requests in the server’s log) were silently ignored. When a .sha1 file exists and does not match, the download is rejected. A .sha1 file with the wrong content was placed next to the JAR; the resolver was a dual of the two kinds (see the next section):

[ivy:resolve] :: loading settings :: file = ./dual/ivysettings.xml
[ivy:resolve] 	confs: [default]
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in descriptors
[ivy:resolve] downloading http://localhost:8765/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar ...
[ivy:resolve] :: resolution report :: resolve 62ms :: artifacts dl 26ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      default     |   1   |   1   |   1   |   0   ||   1   |   0   |
	---------------------------------------------------------------------
[ivy:resolve] :: problems summary ::
[ivy:resolve] :::: WARNINGS
[ivy:resolve] 		[FAILED     ] io.tidepool#tidepool-model;1.0.0!tidepool-model.jar: invalid sha1: expected=0000000000000000000000000000000000000000 computed=347e9f9657298abe8945fa06171763a8ea48cc8f (24ms)
[ivy:resolve] 		[FAILED     ] io.tidepool#tidepool-model;1.0.0!tidepool-model.jar: invalid sha1: expected=0000000000000000000000000000000000000000 computed=347e9f9657298abe8945fa06171763a8ea48cc8f (24ms)
[ivy:resolve] 	==== descriptors: tried
[ivy:resolve] 	==== binaries: tried
[ivy:resolve] 	  http://localhost:8765/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar
[ivy:resolve] 		::::::::::::::::::::::::::::::::::::::::::::::
[ivy:resolve] 		::              FAILED DOWNLOADS            ::
[ivy:resolve] 		:: ^ see resolution messages for details  ^ ::
[ivy:resolve] 		::::::::::::::::::::::::::::::::::::::::::::::
[ivy:resolve] 		:: io.tidepool#tidepool-model;1.0.0!tidepool-model.jar
[ivy:resolve] 		::::::::::::::::::::::::::::::::::::::::::::::
[ivy:resolve] :: USE VERBOSE OR DEBUG MESSAGE LEVEL FOR MORE DETAILS
BUILD FAILED
./build.xml:6: impossible to resolve dependencies:
	resolve failed - see output for details

Source: Ivy documentation: url resolver

Source: Ivy documentation: credentials

dual: descriptors here, artifacts there

dual takes exactly two child resolvers: the first finds descriptors, the second finds artifacts. Publishing delegates to the first for an ivy artifact and to the second for everything else. The use case is metadata on a fast or curated store and large binaries somewhere else. Here the descriptors come from a filesystem resolver and the JARs from the HTTP server:

dual/ivysettings.xml
<ivysettings>
  <property name="repo.url" value="http://localhost:8765" override="false"/>
  <credentials host="localhost" realm="Tidepool Repository" username="builder" passwd="${repo.password}"/>
  <settings defaultResolver="split"/>
  <caches defaultCacheDir="${basedir}/build/cache"/>
  <resolvers>
    <dual name="split">
      <filesystem name="descriptors">
        <ivy pattern="${basedir}/repo/[organisation]/[module]/[revision]/ivy.xml"/>
        <artifact pattern="${basedir}/repo/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
      </filesystem>
      <url name="binaries">
        <artifact pattern="${repo.url}/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
      </url>
    </dual>
  </resolvers>
</ivysettings>
[ivy:resolve] :: loading settings :: file = ./dual/ivysettings.xml
[ivy:resolve] 	confs: [default]
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in descriptors
[ivy:resolve] downloading http://localhost:8765/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] io.tidepool#tidepool-model;1.0.0!tidepool-model.jar (23ms)
[ivy:resolve] :: resolution report :: resolve 47ms :: artifacts dl 25ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      default     |   1   |   1   |   1   |   0   ||   1   |   1   |
	---------------------------------------------------------------------

The found line names the resolver that served the descriptor (descriptors); the downloading line shows where the artifact came from.

Source: Ivy documentation: dual resolver

mirroredurl: a list of mirrors

mirroredurl (since 2.3) reads the base URLs of mirrors from mirrorListUrl and tries each in turn; the patterns on it are relative to the mirror. The list file here has a dead mirror first (nothing listens on port 9) and the live server second:

mirrors.txt
http://localhost:9/dead-mirror/
http://localhost:8767/
ivysettings.xml
<ivysettings>
  <settings defaultResolver="mirrors"/>
  <caches defaultCacheDir="${basedir}/build/cache"/>
  <resolvers>
    <mirroredurl name="mirrors" mirrorListUrl="file:${basedir}/mirrors.txt">
      <ivy pattern="[organisation]/[module]/[revision]/ivy.xml"/>
      <artifact pattern="[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
    </mirroredurl>
  </resolvers>
</ivysettings>
[ivy:resolve] :: loading settings :: file = ./ivysettings.xml
[ivy:resolve] 	confs: [default]
[ivy:resolve] 	found io.tidepool#tidepool-model;1.0.0 in mirrors
[ivy:resolve] downloading http://localhost:8767/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] io.tidepool#tidepool-model;1.0.0!tidepool-model.jar (4ms)
[ivy:resolve] :: resolution report :: resolve 34ms :: artifacts dl 6ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      default     |   1   |   1   |   1   |   0   ||   1   |   1   |
	---------------------------------------------------------------------
[ivy:resolve] :: problems summary ::
[ivy:resolve] :::: ERRORS
[ivy:resolve] 	Server access error at url http://localhost:9/dead-mirror/io.tidepool/tidepool-model/1.0.0/ivy.xml (java.net.ConnectException: Connection refused)
[ivy:resolve] 	Server access error at url http://localhost:9/dead-mirror/io.tidepool/tidepool-model/1.0.0/tidepool-model-1.0.0.jar (java.net.ConnectException: Connection refused)
[ivy:resolve] :: USE VERBOSE OR DEBUG MESSAGE LEVEL FOR MORE DETAILS

The resolve succeeds, but the failure of the first mirror is not hidden: the ERRORS section of the problems summary lists both failed requests. A build that is meant to be quiet needs the dead mirror removed from the list.

Source: Ivy documentation: mirrored resolver

sftp and ssh (not run here)

sftp and ssh serve repositories on a host reachable over SSH; sftp is preferred when the server supports it, and both use the JSch library as the SSH client. The attributes are user, userPassword, keyFile, keyFilePassword, host, port (default 22) and sshConfig, the path of an OpenSSH-style config file. Anything written in the pattern URL (sftp://user@host:port/path/...) overrides the attributes. With no password and no key, Ivy prompts through a Swing dialog, which does not work headless; collect the credentials with Ant’s input task before calling Ivy, or use a key. A configuration with placeholders only:

<sftp name="release-repo" user="${repo.user}" keyFile="${repo.keyfile}" keyFilePassword="${repo.keypass}" host="repo.example.org">
  <ivy pattern="/srv/ivy/[organisation]/[module]/[revision]/ivy.xml"/>
  <artifact pattern="/srv/ivy/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
</sftp>

This was not run here: there is no SSH server in this environment, and starting one would open a login path to the machine. The values above are placeholders.

Source: Ivy documentation: sftp resolver

Source: Ivy documentation: ssh resolver

vfs, jar, packager and the OSGi resolvers

vfs reads anything Apache Commons VFS understands and jar a repository packed in one JAR; neither was run here. packager deserves a warning. It downloads online artifacts and repackages them with an Ant script that is stored under a buildRoot directory computed from the module coordinates. Until Ivy 2.5.3, a coordinate containing ../ could leave that directory and overwrite other files; CVE-2026-26032 (medium, path traversal) is fixed in Ivy 2.6.0. The attacker needs write access to a packager repository. If you use packager, use 2.6.0 or later and only trust repositories you control. obr, updatesite and osgiagg serve OSGi bundles and are outside the scope of these pages.

Source: Apache Ivy: Security

Source: Ivy documentation: packager resolver

Resolvers that no longer work

Two resolvers in the reference point at services that are gone. ivyrep used a repository modelled on the Ivyrep site, which the reference calls defunct. Because it is not maintained its ivyroot is mandatory, and the reference recommends a url resolver instead. bintray (since 2.4) retrieved artifacts from Bintray and JCenter, which their provider was decommissioning in 2021 and 2022, after which the resolver stops working. An old ivysettings.xml that names either needs a new resolver.

Source: Ivy documentation: ivyrep resolver

Source: Ivy documentation: bintray resolver

Module rules and branches

The modules element maps sets of modules to a resolver, a conflict manager, a default branch or a resolve mode. A module rule matches organisation, name, and optionally revision and extra attributes, with a pattern matcher chosen by matcher (default exactOrRegexp; exact, regexp and glob are the others). Rules are checked in order and the first match wins; modules that match none use the default resolver. The reference stresses the reason to have the rules: several small resolvers, each used for one set of modules, resolve much faster than one big chain, because Ivy does not ask every repository for every module.

The test repository keeps tidepool-model per branch: master has 1.0.0 and fix-103 has 1.0.1. The patterns carry a [branch] token:

./io.tidepool/tidepool-model/fix-103/1.0.1/ivy.xml
./io.tidepool/tidepool-model/fix-103/1.0.1/tidepool-model-1.0.1.jar
./io.tidepool/tidepool-model/master/1.0.0/ivy.xml
./io.tidepool/tidepool-model/master/1.0.0/tidepool-model-1.0.0.jar
ivysettings.xml
<ivysettings>
  <property name="tidepool.branch" value="master" override="false"/>
  <settings defaultResolver="central" defaultBranch="master"/>
  <caches defaultCacheDir="${basedir}/build/cache"/>
  <resolvers>
    <ibiblio name="central" m2compatible="true"/>
    <filesystem name="internal">
      <ivy pattern="${basedir}/repo/[organisation]/[module]/[branch]/[revision]/ivy.xml"/>
      <artifact pattern="${basedir}/repo/[organisation]/[module]/[branch]/[revision]/[artifact]-[revision].[ext]"/>
    </filesystem>
  </resolvers>
  <modules>
    <module organisation="io.tidepool" name="tidepool-.*" matcher="regexp" resolver="internal" branch="${tidepool.branch}"/>
  </modules>
</ivysettings>

The descriptor asks for latest.integration of tidepool-model and for Commons CSV 1.14.1 (the same ivy.xml content as the base example plus the latest.integration revision). With the default branch, master:

[ivy:resolve] 	found io.tidepool#tidepool-model#master;1.0.0 in internal
[ivy:resolve] 	[1.0.0] io.tidepool#tidepool-model#master;latest.integration
[ivy:resolve] 	found org.apache.commons#commons-csv#master;1.14.1 in central
[ivy:resolve] 	found commons-io#commons-io#master;2.20.0 in central
[ivy:resolve] 	found commons-codec#commons-codec#master;1.19.0 in central
[ivy:resolve] downloading ./repo/io.tidepool/tidepool-model/master/1.0.0/tidepool-model-1.0.0.jar ...

With -Dtidepool.branch=fix-103 the rule sends the tidepool- modules to the fix-103 branch, and Commons CSV stays on Maven Central with the default branch, which Maven Central, having no branches, ignores:

[ivy:resolve] 	found io.tidepool#tidepool-model#fix-103;1.0.1 in internal
[ivy:resolve] 	[1.0.1] io.tidepool#tidepool-model#fix-103;latest.integration
[ivy:resolve] 	found org.apache.commons#commons-csv#master;1.14.1 in central
[ivy:resolve] 	found commons-io#commons-io#master;2.20.0 in central
[ivy:resolve] 	found commons-codec#commons-codec#master;1.19.0 in central
[ivy:resolve] downloading ./repo/io.tidepool/tidepool-model/fix-103/1.0.1/tidepool-model-1.0.1.jar ...

The #master and #fix-103 parts of the module names in the log are Ivy’s way of writing the branch, as in organisation#module#branch;revision.

Source: Ivy documentation: modules

Source: Ivy documentation: module

An enterprise repository setup

Ivy’s own best-practice page recommends that a company does not build against Maven Central directly. The reasons it gives are control (a broken descriptor can be fixed in your repository), reliability, accuracy (only approved libraries), and security (a public repository is a way into your build), and it points at ivy:install for copying modules from a public repository into your own selectively. In settings terms the change is small: point ibiblio at the company repository manager and make the descriptors mandatory. The test stands in for a repository manager with a local server that forwards to Maven Central and logs every request; the password is not needed here, so no credentials element is shown (it would be the same one as above):

ivysettings.xml
<ivysettings>
  <properties environment="env"/>
  <property name="repo.root" value="${env.TIDEPOOL_REPO_ROOT}" override="false" ifset="env.TIDEPOOL_REPO_ROOT"/>
  <property name="repo.root" value="http://localhost:8768/maven-central/" override="false"/>
  <settings defaultResolver="enterprise"/>
  <caches defaultCacheDir="${basedir}/build/cache"/>
  <resolvers>
    <ibiblio name="enterprise" m2compatible="true" root="${repo.root}" descriptor="required"/>
  </resolvers>
</ivysettings>

ifset makes the environment variable the first choice if it exists, the literal is the fallback, and descriptor="required" makes a module without a descriptor an error instead of a silent no-dependencies module. The resolve of Commons CSV 1.14.1:

[ivy:resolve] :: loading settings :: file = ./ivysettings.xml
[ivy:resolve] 	confs: [default]
[ivy:resolve] 	found org.apache.commons#commons-csv;1.14.1 in enterprise
[ivy:resolve] 	found commons-io#commons-io;2.20.0 in enterprise
[ivy:resolve] 	found commons-codec#commons-codec;1.19.0 in enterprise
[ivy:resolve] downloading http://localhost:8768/maven-central/org/apache/commons/commons-csv/1.14.1/commons-csv-1.14.1.jar ...
[ivy:resolve] 	[SUCCESSFUL ] org.apache.commons#commons-csv;1.14.1!commons-csv.jar (390ms)
[ivy:resolve] downloading http://localhost:8768/maven-central/commons-io/commons-io/2.20.0/commons-io-2.20.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] commons-io#commons-io;2.20.0!commons-io.jar (451ms)
[ivy:resolve] downloading http://localhost:8768/maven-central/commons-codec/commons-codec/1.19.0/commons-codec-1.19.0.jar ...
[ivy:resolve] 	[SUCCESSFUL ] commons-codec#commons-codec;1.19.0!commons-codec.jar (471ms)
[ivy:resolve] :: resolution report :: resolve 3979ms :: artifacts dl 1315ms
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|      default     |   3   |   3   |   3   |   0   ||   3   |   3   |
	---------------------------------------------------------------------

The server’s log counted 54 requests for that run. The repository manager sees HEAD, GET and checksum requests for every POM, parent POM and JAR; six of the requests were for -sources and -javadoc JARs that were never downloaded:

HEAD org/apache/commons/commons-csv/1.14.1/commons-csv-1.14.1-sources.jar 200
HEAD org/apache/commons/commons-csv/1.14.1/commons-csv-1.14.1-javadoc.jar 200
HEAD commons-io/commons-io/2.20.0/commons-io-2.20.0-sources.jar 200
HEAD commons-io/commons-io/2.20.0/commons-io-2.20.0-javadoc.jar 200
HEAD commons-codec/commons-codec/1.19.0/commons-codec-1.19.0-sources.jar 200
HEAD commons-codec/commons-codec/1.19.0/commons-codec-1.19.0-javadoc.jar 200

With -Divy.maven.lookup.sources=false -Divy.maven.lookup.javadoc=false the same resolve made 48 requests. On a large graph, behind a slow proxy, that is worth setting.

Pointing the environment variable at a root that does not exist shows what a dead repository manager looks like in the log (the build fails; nothing falls back):

[ivy:resolve] 		module not found: org.apache.commons#commons-csv;1.14.1
[ivy:resolve] 	==== enterprise: tried
[ivy:resolve] 	  http://localhost:9/none/org/apache/commons/commons-csv/1.14.1/commons-csv-1.14.1.pom
[ivy:resolve] 		:: org.apache.commons#commons-csv;1.14.1: not found
[ivy:resolve] 	Server access error at url http://localhost:9/none/org/apache/commons/commons-csv/1.14.1/commons-csv-1.14.1.pom (java.net.ConnectException: Connection refused)

The same settings can be shared by publishing them. The best-practices page suggests putting the ivysettings.xml of a repository at a URL, so anyone can load it with ivy:settings url=... or include url=.... Loading settings from a URL was shown in the first section; a team that does so should serve the file over HTTPS and treat it like code, because the resolvers and credentials it names decide where every build downloads from.

Source: Ivy documentation: best practices, enterprise repository

Signers

signers registers detached signature generators; the only built-in one is pgp, which creates OpenPGP ASCII-armored signatures and needs the BouncyCastle OpenPGP library and its JCE provider on Ivy’s class path. Its attributes are name, secring (default ~/.gnupg/secring.gpg), keyId (default auto) and password. A resolver opts in with signer="name", and Ivy then signs what it publishes. This was not run here: signing needs a key ring and the extra libraries, and publishing is covered on Ivy: Publishing & Multi-Project Builds.

Source: Ivy documentation: signers

Settings in the other two tools

Maven and Gradle keep this information in different places and do not have a counterpart to the resolver abstraction:

Ivy Maven Gradle

ibiblio with m2compatible

<repository> in the POM or a profile

mavenCentral() or maven { url = ... } in repositories

url, filesystem

<repository> with a file: or https: URL

maven { url = ... }, ivy { ... }, flatDir

credentials

<server> in settings.xml, matched by the repository id

credentials { ... } inside the repository block, read from properties or the environment

chain, returnFirst

The order of repositories; there is no "latest of all of them"

The order of repositories, with content filtering to say which one may serve what

modules rules

<mirrorOf> rules, or repository manager groups

content { includeGroup(...) } filters

mirroredurl

<mirror> with <mirrorOf>

maven { url = ... } repositories, or a repository manager

caches, ttl, useOrigin

~/.m2/repository, -U or update policy per repository

~/.gradle/caches, --refresh-dependencies, cacheChangingModulesFor

The Maven side is on Repositories, Mirrors & Repository Managers and settings.xml & Password Encryption, the Gradle side on Repositories & Content Filtering, and the common vocabulary on Repositories & Publishing Across Tools. The other Ant dependency tool, the Maven Resolver Ant Tasks, reads the user’s Maven settings.xml for mirrors, proxies and credentials instead of having a settings file of its own.

Common problems

  • NoClassDefFoundError: org/apache/oro/text/regex/MalformedPatternException while loading the settings. A glob matcher needs Apache ORO (the run above used it in a ttl rule). Add oro:oro:2.0.8 next to the Ivy JAR.

  • A value from -D is ignored. A properties or property element with the default override="true" replaced it. Add override="false" to the ones that provide defaults.

  • module not found for a module that is certainly there. On a repository with authentication this can be a 401. Check the host and realm of the credentials, and the password. Look at the URLs under tried.

  • invalid sha1: expected=... computed=.... The repository’s checksum file does not match the file. Fix the repository; do not turn checksums off to make the error go away.

  • Dynamic revision does not move. The TTL (10 seconds by default) or an eternal rule is still holding the old answer; resolve with refresh="true", or set a shorter TTL.

  • Slow resolves through a repository manager. Disable the sources and javadoc probes with the two ivy.maven.lookup.* properties.

  • Two settings in one build use the wrong one. Give each an id and set settingsRef on every task.

  • A resolver silently picks the wrong revision. Look at returnFirst: with false, a newer revision in a later child beats an older one in an earlier child, which may not be what a "local first" intention meant.

  • Prompts for a password in a build job. sftp and ssh open a Swing dialog when they have no credentials; in a headless CI job this fails. Supply a key or collect the password with input.

Where the books and older build files are outdated

  • The names ivyconf.xml, <ivyconf> and ivy.conf.file belong to Ivy 1.x. The file is called settings since Ivy 2.0, with ivy:settings and ${ivy.settings.file}; the reference for configure still mentions the old name only to say what was renamed.

  • Examples that use ivyrep or bintray as the default resolver, or the public Ivyrep site, no longer work, as above.

  • Older material does not mention ifset/unlessset (2.4), artifact-lock-nio (2.4), optional on include (2.4), timeoutConstraint (2.5), the ivy.maven.lookup.* switches (2.5), or the XML parser limits introduced in 2.5.2, which turn DOCTYPE processing off except for Maven POMs (CVE-2022-46751).

  • The deprecated attributes defaultCache, checkUpToDate, cacheIvyPattern and cacheArtifactPattern of settings were superseded by the caches element in 2.0.

  • Material from the Ivy 1.x era describes a single cache directory. Since 2.0 there is a repository cache and a resolution cache and any number of named caches.

References