Ivy Configuration

In order to work as you want it work, ivy need some configuration. Actually, ivy can work with no configuration at all, but in this case it work only with the ivyrep repository. 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 :

Mainly, the configuration enables to configure the default cache directory used by ivy and the dependency resolvers that it will use to resolve dependencies.

Configuration file structure

The configuration file is structured in some parts and left other open. Indeed each resolver has its own structure, thus it's not the configuration file itself which define the structure for the resolvers.

ivyconf
    properties
    conf
    typedef
    latest-strategies
    resolvers
    conflict-managers
    modules
        module

ivyconf

Tag: ivyconf

Root tag of any ivyconf file.

Child elements

Element	Description	Cardinality
properties	loads properties file as ivy variables	0..n
conf	configures ivy with some defaults	0..1
typedef	defines new types in ivy	0..n
latest-strategies	defines latest strategies	0..n
resolvers	defines dependency resolvers	1..n
conflict-managers	defines conflicts managers	0..n
modules	defines rules between modules and dependency resolvers	0..n

properties

Tag: properties

Loads a properties file into ivy variables. See variables chapter above for details about ivy variables.

Attributes

Attribute	Description	Required
file	a path to a properties file to load	Yes

conf

Tag: conf

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

Default cache is used whenever a cache is not provided. It usually points to a directory in your filesystem.

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

Attribute	Description	Required
defaultCache	a path to a directory to use as default cache	No, defaults to .ivy-cache in user home
defaultResolver	the name of the default resolver to use	No, but all modules should be configured in the modules section if not provided
defaultLatestStrategy	the name of the default latest strategy to use	No, defaults to latest-revision
defaultConflictManager	the name of the default conflict manager to use	No, defaults to latest-revision
validate	Indicates if ivy files should be validated against ivy.xsd or not.	No, defaults to true
checkUpToDate	Indicates if date should be checked before retrieving artifacts from cache	No, defaults to true
cacheIvyPattern	a pattern to indicate where ivy files should be put in cache	No, defaults to [organisation]/[module]/ivy-[revision].xml
cacheArtifactPattern	a pattern to indicate where artifact files should be put in cache	No, defaults to [organisation]/[module]/[type]s/[artifact]-[revision].[ext]

typedef

Tag: typedef

Defines a new type in ivy. Useful to define new dependency resolvers, in particular, but also latest strategies. See how to write and plug your own dependency resolver for details.

Attributes

Attribute	Description	Required
name	the name of the type to define. This name is then used as an xml tag.	Yes
classname	the fully qualified class name of the type to define.	Yes

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

Element	Description	Cardinality
any latest strategy	adds a latest strategy to the list of available strategies	0..n

Dependency 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). See buit-in dependency resolvers chapter below for details on available dependency resolvers.

Child elements

Element	Description	Cardinality
any resolver	adds a resolver to the list of available resolvers	1..n

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.
- fixed: this conflict manager always select the same revision
- 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.

Child elements

Element	Description	Cardinality
any conflict manager	adds a conflict manager to the list of available conflict managers	0..n

modules

Tag: modules

Defines the rules on which resolvers should be used for which modules. The rules are given by defining a module set, using regexp for module organisation and name, and giving the name of the corresponding resolver to use.

Child elements

Element	Description	Cardinality
module	defines a module set rule	1..n

module

Tag: module

Define a resolver application rule. The tag defines a module set, by giving a regexp for organisation and name (for instance, you can use .* to specify all). It also gives the name of the resolver to use for this module set.

Attributes

Attribute	Description	Required
organisation	the name of the organisation to which apply the resolver. May be a regexp.	Yes
name	the name of the module to which apply the resolver. May be a regexp.	Yes
resolver	the name of the resolver to apply. The resolver must have been defined in the resolvers section of the configuration file.	Yes

Built-in dependency resolvers

First of all, if you think that ivy lacks THE dependency resolver you need in your development environment, you can write and plug your own. But first checks the following built-in resolvers to see if you don't find what you want here...

IvyRep resolver

Tag	ivyrep
Handle latest	yes, at least if the repository server is apache based
Handle publish	no

This resolver usually uses ivyrep to find ivy files and ibiblio to find artifacts. However it can be configured to use other similar repositories.

Note that if no ivy file is found on ivyrep, then this resolver behaves like ibiblio resolver. Thus it's always better to use this resolver instead of ibiblio one, which is provided mainly for compatibility reasons.

Attributes

Attribute	Description	Required
name	the name which identify the resolver	Yes
validate	indicates if resolved ivy files should be validated against ivy xsd	No, defaults to true
checkmodified	Indicates if this resolver should check lastmodified date to know if an ivy file is up to date.	No, defaults to ${ivy.resolver.default.check.modified}
ivyroot	the root of the ivy repository.	No, defaults to ${ivy.ivyrep.default.ivy.root}
ivypattern	a pattern describing the layout of the ivy repository.	No, defaults to ${ivy.ivyrep.default.ivy.pattern}
artroot	the root of the artifacts repository.	No, defaults to ${ivy.ivyrep.default.artifact.root}
artpattern	a pattern describing the layout of the artifacts repository.	No, defaults to ${ivy.ivyrep.default.artifact pattern}
latest	The name of the latest strategy to use.	No, defaults to 'default'

IBiblio resolver

Tag	ibiblio
Handle latest	yes, at least if the repository server is apache based
Handle publish	no

This resolver usually uses ibiblio to find artifacts.
Prefer the use of ivyrep resolver which adds ivy file handling to this resolver.

Attributes

Attribute	Description	Required
name	the name which identify the resolver	Yes
validate	indicates if resolved ivy files should be validated against ivy xsd	No, defaults to call setting
root	the root of the artifacts repository.	No, defaults to ${ivy.ibiblio.default.artifact.root}
pattern	a pattern describing the layout of the artifacts repository.	No, defaults to ${ivy.ibiblio.default.artifact.pattern}
latest	The name of the latest strategy to use.	No, defaults to 'default'

File System resolver

Tag	filesystem
Handle latest	yes
Handle publish	yes

This resolver uses the file system to resolve ivy files and artifacts. It presents the advantage to usually have very good performances. Moreover, it is easy to setup using basic OS file sharing mechanism.

The configuration of such a resolver is mainly done through ivy and artifact patterns, indicating where ivy files and artifacts can be found in the file system. You can indicate a list of pattern which will be checked one after the other.

Attributes

Attribute	Description	Required
name	the name which identify the resolver	Yes
validate	indicates if resolved ivy files should be validated against ivy xsd	No, defaults to call setting
checkmodified	Indicates if this resolver should check lastmodified date to know if an ivy file is up to date.	No, defaults to ${ivy.resolver.default.check.modified}
latest	The name of the latest strategy to use.	No, defaults to 'default'

Child elements

Element	Description	Cardinality
ivy	defines a pattern for ivy files, using the pattern attribute	0..n
artifact	defines a pattern for artifacts, using the pattern attribute	1..n

Url resolver

Tag	url
Handle latest	yes with http urls (and apache server) and with file urls, no with other urls
Handle publish	no

This resolver is one of the most generic, in fact most of the previous resolvers can be obtained by a particular configuration of this one. Indeed it uses urls to find ivy files and artifacts. The urls it uses are defined through ivy and artifact children, each giving a pattern to find ivy files or artifacts.

Attributes

Attribute	Description	Required
name	the name which identify the resolver	Yes
validate	indicates if resolved ivy files should be validated against ivy xsd	No, defaults to call setting
checkmodified	Indicates if this resolver should check lastmodified date to know if an ivy file is up to date.	No, defaults to ${ivy.resolver.default.check.modified}
latest	The name of the latest strategy to use.	No, defaults to 'default'

Child elements

Element	Description	Cardinality
ivy	defines a pattern for ivy files, using the pattern attribute	0..n
artifact	defines a pattern for artifacts, using the pattern attribute	1..n

Chain resolver

Tag	chain
Handle latest	depends on sub resolvers
Handle publish	delegates to first sub resolver in chain

This resolver is only a container of a chain of other resolvers. The sub resolvers can be any resolver, including a chain. An attribute enable to indicate if the chain must be iterated after the first found or not (at least when asking for a latest revision). If the chain is iterated, then it's the latest among the ones found that is returned. If the chain is not iterated, then it's the first found which is returned.

Attributes

Attribute	Description	Required
name	the name which identify the resolver	Yes
validate	indicates if resolved ivy files should be validated against ivy xsd	No, defaults to call setting
returnFirst	true if the first found should be returned.	No, defaults to false
latest	The name of the latest strategy to use.	No, defaults to 'default'

Child elements

Element	Description	Cardinality
any resolver	a sub resolver to use	1..n

Dual resolver

Tag	dual
Handle latest	depends on sub resolvers
Handle publish	delegates to ivy sub resolver if artifact to publish is of "ivy" type, to artifact sub resolver otherwise

This resolver delegates its job to one resolver for ivy files and another for artifacts.

Attributes

Attribute	Description	Required
name	the name which identify the resolver	Yes
validate	indicates if resolved ivy files should be validated against ivy xsd	No, defaults to call setting
latest	The name of the latest strategy to use.	No, defaults to 'default'

Child elements

Element	Description	Cardinality
any resolver	two resolvers, the first being the ivy resolver, the second the artifact resolver	2