Configuration

In order to work as you want, ivy need some configuration. Actually, ivy can work with no configuration at all, see the default configuration documentation for details about that. But ivy is able
to work in very different contexts. You just have to configure it properly.

Configuration is done through an xml file, usually called ivyconf.xml. To configure ivy from ant, you just have to call the configure task and pass it the path to your configuration file (see configure task documentation for details).

Here is an example of configuration file :

property

Tag: property

Defines an ivy variable. since 1.3

The optional override attribute enables to avoid overriding the previous value of the varable, which makes the definition behave like ant properties, which is particularly useful to define default values (values which are used only if they haven't been defined yet).

Attributes

Examples

Sets the variable myvar to the value myvalue.

Sets the variable myvar to the value myvalue only if myvar has not been set yet.

properties

Attributes

conf

Tag: conf

Configures some important ivy info: default cache, default resolver, ...

Note that this is not related at all with conf found in ivy files. This tag is only used to setup ivy.

Default cache is used whenever a cache is not provided. It usually points to a directory in your filesystem. This should not point to a directory used as a repository!

Default resolver is used whenever nothing elese is configured in the modules section of the configuration file. It should give the name of a dependency resolver defined in the resolvers section of the configuration file.

Default latest strategy and conflict manager can also be configured here.

validate indicates if ivy files should generally be validate against xsd or not. This setting is only a default value, and can be overriden :
1) in ant tasks
2) in resolvers
So if there is a setting in the resolver, it always win against all other settings.

checkUpToDate indicates to ivy if it must check date of artifacts before retrieving them (i.e. copying them from
cache to another place in your filesystem). Usually it is a good thing to check date to avoid unnecessary copy, even if it's most of the time a local copy.

cacheIvyPattern and cacheArtifactPattern are used to configure the way ivy stores ivy files and artifacts in the cache. Usually you do not have to change this, unless you want to use the cache directly from another tool, which is not recommended.

Attributes

include

Tag: include

Includes another ivyconf file as if it were part of this one. since 1.3

The included ivyconf file has to be a complete well formed ivyconf file, i.e. it does have to include the <ivyconf> tag.

Attributes

Examples

with ivyconf-default.xml:

The included ivyconf defines a resolver named default, which is an ivyrep resolver, with its root configured as being the value of myrepository variable. This variable is given the value path/to/rep in the included file, but because the attribute overwrite is set to false, it will not overide the value given in the main ivyconf including this one, so the value used for myrepository will be path/to/my/real/rep.

with ivyconf-macro.xml being the ivyconf example given on the macrodef documentation page.
This let reusing macro resolver easy.

classpath

Tag: classpath

Includes a jar in the classpath used to load plugins. since 1.4

This let you add ivy plugins without relying on ant classpath for instance, easing therefore the use of ivy in multiple execution environment (ant, standalone, IDE plugins, ...).

Attributes

Examples

Adds custom-resolver.jar found in the same directory as the ivyconf.xml file itself to the classpath, then define a custom resolver and use it.

Same as above, but find the jar on a web server.

typedef

Attributes

latest-strategies

Tag: latest-strategies

Defines a list of latest strategies usable in ivy. Each latest strategy is identified by its name, given as an attribute.
The child tag used for the latest strategy must be equal to a name of a latest strategy type (usually added with the typedef tag).

The latest strategies which are always included in ivy (and do not require anything in the configuration file) are:

• latest-time

compares the revisions date to know which is the latest. While this is often a good
strategy in terms of pertinence, it has the drawback to be costful to compute with distant repositories. If you use ivyrep,
for example, ivy has to ask the http server what is the date of each ivy file before knowing which is the latest.

• latest-revision

compares the revisions as string, using an algorithm close to the one used in the php version_compare function.
This algorithm takes into account special meaning of some text. For instance, with this strategy, 1.0-dev1 is considered
before 1.0-alpha1, which in turn is before 1.0-rc1, which is before 1.0, which is before 1.0.1.

• latest-lexico

compares the revisions as string, using lexicographic order (the one used by java string comparison).

Child elements

latest-revision

since 1.4 The latest-revision can now be configured to handle more words with special meanings than the one defined in php version_compare function.

Here is an example of how you can do so:

Knowing that the default special meaning words are the following:

You can even get rid or redefine the default special meanings by setting usedefaultspecialmeanings="false" on the latest-revision tag.
Example:

parsers

Tag: parsers

Defines a list of module descriptor parsers usable in ivy. Each parser defines which resources (which descriptor file) it accepts.
The child tag used for the parser must be equal to a name of a parser type (added with the typedef tag).

Note that when looking for a parser, ivy queries the parsers list in the reverse order. So the last parser in the list will be queried first. Consequently, if the last parser accepts all resources, the other parsers will never have a chance to parse the resource.

Two parsers are available by default and thus do not need to be declared in this section:

• ivy file parser

this is the parser used for ivy xml files. This parser is used for resources that aren't accepted by any other parser.

• pom parser

this parser is able to parse maven2 pom files

Child elements

namespaces

Tag: namespaces

Namespaces are an advanced feature of Ivy which let you use resolvers in which module names and organisations are not consistent between each other.

For instance, if you want to use maven2 repository and ivyrep collectively, you will face some naming issues. For example all apache commons projects are declared to be part of the organisation apache in ivyrep whereas in maven2 ibiblio repository, they are declared to be part of the organisation of the same name of the module.

So if you try to use both maven2 and ivyrep repositories, you will face some issues like:

How do I declare a dependency on commons-lang ?
I have an error while trying to resolve module xxx. It says that it depends on [commons-httpclient commons-httpclient] ant that it isn't available.
...

Ivy has an answer to give to this kind of troubles, and this answer is called namespaces. In short, you can affect a namespace to each dependency resolver in Ivy, and each namespace defines rules to convert names from the system namespace to the defined namespace itself, and vice versa.

This very powerful feature is thoroughly used in the build your own repository tutorial, and this is a good place to have examples of what can be done with namespaces.

Child elements

macrodef

Tag: macrodef

Defines a new dependency resolver type based upon an other one. This definition is very similar to the macrodef feature of ant for defining macro tasks. since 1.3

This task eases the lot the process of creating new dependency resolver, because it avoid writing java code.

It is generally used in combination with the include feature to help reusing macro at several places.

A macro is defined by writing the resolver it is equivalent to as if it were written in the resolver place, except that you can use attributes to pass parameters to the newly defined resolver type. Attributes are defined with a name and sometimes a default value, and are used using the following syntax: @{attributename}.

Attributes

Child elements

Examples

Defining a simple macro:

Using it:

resolvers

Tag: resolvers

Defines a list of dependency resolvers usable in ivy. Each dependency resolver is identified by its name, given as an attribute.

The child tag used for the dependency resolver must be equal to a name of a dependency resolver type (either built-in or added with the typedef tag).

since 1.3 Once defined, resolvers can be referenced by their name, using the following syntax:

Note that this works only if the resolver has been already defined, and not if it is defined later in the ivyconf file.

Child elements

Built-in Resolvers

Ivy comes with a set of built-in dependency resolvers able to answer to the most common needs.

If you don't find the one you want here, you can also check if some one has not contributed it in the links page, or even write your own.

There are basically two types of resolver in Ivy: composite and standard resolvers. A composite resolver is a resolver which delegates the work to other resolvers. The other resolvers are standard resolvers.

Here is the list of built-in resolvers:

Common attributes

All resolvers of the same type share some common attributes detailed here:

Examples

Defines a filesystem resolver, named '1', which is then used in two chains, the first which seconds the filesystem resolver with an ivyrep resolver, and second which seconds the filesystem resolver with an ibiblio resolver, and which returns the first module found, and uses the whole chain to download artifacts (see corresponding resolvers documentation for details about them).

conflict-managers

Tag: conflict-managers

Defines a list of conflicts managers usable in ivy. Each conflict manager is identified by its name, given as an attribute.
The child tag used for the conflict manager must be equal to a name of a conflict manager type (either built-in
or added with the typedef tag).

Here is a list of predefined conflicts managers (which do not require anything in the configuration file):

• all

this conflicts manager resolve conflicts by selecting all revisions. Also called NoConflictManager, it does evict any module.

• latest-time

this conflict manager selects only the 'latest' revision, latest being defined as the latest in time. Note that latest in time is costly to compute, so prefer latest-revision if you can.

• latest-revision

this conflict manager selects only the 'latest' revision, latest being defined by a string comparison of revisions.

• strict

this conflict manager throws an exception (i.e. causes a build failure) whenever a conflict is found.

The two "latest" conflict managers also take into account the force attribute of the dependencies.
Indeed direct dependencies can declare a force attribute (see dependency), which indicates the the revision given in the direct dependency should be prefered over indirect dependencies.

Here is a list of conflict manager types available, which can be used to define your own custom conflict managers:

• latest-cm

The latest conflict manager uses a latest strategy to select the latest revision among several ones. Both latest-time and latest-revision conflict managers are based on this conflict manager type. It takes 'latest' as attribute to define which latest strategy should be used. Example:
<latest-cm name="mylatest-conflict-manager" latest="my-latest-strategy"/>

• regexp-cm

This conflict manager is based on a regular expression and throw an exception (i.e. causes a build failure) when a conflict is found with versions with different matching group. For instance if a conflict is found between 1.2.x and 1.3.y it will throw an exception if the regular exception is (.*)\.\d, because the matching group will match different string (1.2 and 1.3). 1.2.1 and 1.2.2 won't throw an exception with the same regular expression. The regular expression is set using the 'regexp' attribute. A 'ignoreNonMatching' attribute can also be set to simply warrn when a version is found which does not match the regular expression, instead of throwing an exception.

Child elements

modules

Tag: modules

Defines per module or module set settings.

The rules are given by defining a module set, using pattern for module organisation and name, and giving some settings for the set, like the name of the corresponding resolver to use.

If no rule match a given module, the default setting will be used.

Even if not required, because the use of a default big resolver (chain, for instance) able to resolve all dependencies can answer all the needs, the configuration of smaller resolvers used for different cases can improve performances a lot. For instance, if you have a local repository for your modules and a distant repository for third party libraries, it is a good idea to have two separate resolvers, and configure ivy to use one for all your modules and another for the rest (the default one).

Child elements

outputters

Tag: outputters

Defines a list of report outputters usable in ivy.

A report outputter is used at the end of the resolve process to generate a report of how the resolve has been performed.

Two report outputters are registered by default:

• a log report outputter (LogReportOutputter)

which produces the output on the console at the end of the resolve, which looks like this:

        ---------------------------------------------------------------------
        |                  |            modules            ||  artifacts  |
        |      conf      | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default    |  1  |  1  |  0  |  0  ||  1  |  1  |
        ---------------------------------------------------------------------
• an xml report outputter (XmlReportOutputter)

which produces an xml report in the cache, which is mandatory for correct Ivy behaviour, since it's that report which is used when you do a post resolve step in a separate buid from the resolve itself. It's also this xml report which is processed to generate all the different reports available in the report task.

The child tag used for the parser must be equal to a name of a report outputter type (added with the typedef tag).

To see how to define your own report outputter see Extending Ivy documentation

Child elements

statuses

Tag: statuses

Defines the list of available statuses. since 1.4

By default, ivy has 3 statuses: release, milestone and integration. By adding a statuses section to your ivyconf file, you define the statuses you want to use. Note that in this case if you still want to have ivy default statuses you will have to declare them.

The integration property on each status is only used for recursive delivery, an integration dependency being delivered if the caller is not in integration state itself.

The default status is the one used when none is defined in a module descriptor. If not specified, it defaults to the last defined status.

The statuses order is important, the first is considered the more mature, the last the less mature. This is used to know if a status is compatible with a latest. version matcher.

Attributes

Child elements

Examples

Defines 3 statuses, gold, silver and bronze. The default status used when none is declared in an ivy file will be bronze.
It is also considered as an integration status, and thus doesn't trigger any recrusive delivery.

triggers

Tag: triggers
since 1.4

Defines a list of triggers to activate on some Ivy events.

A trigger is an action which is performed whenever a particular event occurs.
Ivy supports two type of triggers out of the box: ant-call and ant-build. The first calls a target in the same build as the original one whenever a particular event occurs, the second call an ant build which may be in another ant build script.

If you want to use a different trigger, you can implement your own.

The event available in Ivy are the following ones:

The child tag used for the dependency resolver must be equal to a name of a trigger type (either built-in or added with the typedef tag).

Child elements

Built-in Triggers

Ivy comes with two built-in triggers:

Common attributes

All triggers share some common attributes detailed here.

Among these attributes, you will find how to select when the trigger should be performed. You have to provide an event name, which is simple, but you can also use a filter expression. The syntax for this expression is very simple and limited:
you can use the = operator to compare an attribute (left operande) with a value (right operande).
you can use AND OR NOT as boolean operators
you cannot use parenthesis to change the precedence

Examples

Triggers an ant build of the ant file ${ivy.conf.dir}/[module]/build.xml (where [module] is replaced by the name of the dependency resolved) with the target "publish", just before resolving a dependency with a latest.integration revision.

Triggers an ant call of the target unzip just after downloading a zip artifact, prefixing all parameters to the target with 'dep'.
Here is how the target can look like:

version-matchers

Tag: version-matchers

Defines a list of version matchers. since 1.4

The child tag used for the version matcher must be equal to a name of a report outputter type (added with the typedef tag).

A version matcher is used to evaluate if a a dependency version contraint matches a dependency version.

See dependency doc for details about built-in version matchers.

Child elements