Using Ivy

The main and most frequent way to use ivy is from an ant build file. However, ivy can also be called as a standalone application.

If you use ant version 1.6.0 or superior, you just have to add ivy namespace to your project (xmlns:ivy="antlib:fr.jayasoft.ivy.ant" attribute of your project tag), and you can call ivy tasks.

If you use ant 1.5.1 or superior, you have to define the tasks in your build file:

  <taskdef name="ivy-configure" classname="fr.jayasoft.ivy.ant.IvyConfigure"/>
  <taskdef name="ivy-resolve" classname="fr.jayasoft.ivy.ant.IvyResolve"/>
  <taskdef name="ivy-retrieve" classname="fr.jayasoft.ivy.ant.IvyRetrieve"/>
  <taskdef name="ivy-deliver" classname="fr.jayasoft.ivy.ant.IvyDeliver"/> 
  <taskdef name="ivy-publish" classname="fr.jayasoft.ivy.ant.IvyPublish"/> 

Then you can use the tasks, but check their name, following samples assume you use the ivy namespace (ivy:xxx tasks), whereas with ant 1.5 you cannot use namespace, and should therefore use ivy-xxx tasks if you have followed the taskdefs above.

If you use an ant version lower than 1.5.1, you can not use the ivy tasks... you should then call ivy as any external program.

Calling ivy as a standalone program

In the case you want to call ivy as a standalone program (outside from ant), you have to put commons-cli 1.0 and its dependencies in your classpath.

Then here is how to call it:

java fr.jayasoft.ivy.Main -?

It will indicate you what can be given as argument. Here are some examples:

java fr.jayasoft.ivy.Main

calls ivy with default configuration using ivy.xml in the current dir

java fr.jayasoft.ivy.Main -conffile path/to/myivyconf.xml -ivyfile path/to/myivy.xml

calls ivy with given ivyconf file using given ivy file

Calling ivy from ant: first steps

Once your build file is ok to call ivy tasks, the simplest way to use ivy is to call the ivy retrieve task with no parameters:

<ivy:retrieve />

This calls ivy with default values, which might be ok in several projects. In fact, it is equivalent to:

Those 3 tasks follow the 3 main steps of ivy retrieving dependencies process:

• First the configure task tells it how it can find dependencies giving it a path to an xml configuration file.
• Then the resolve task actually resolve dependencies described by an ivy file, and put those dependencies in the ivy cache (a directory configured in the configuration file).
• Finally the retrieve task copies dependencies from the cache to anywhere you want in your file system. You can then use those dependencies to make your classpath with standard ant paths.

To understand more accurately the behaviour of ivy tasks, one should know that a property file is loaded in ant by ivy at the beginning of the configure call. This property file contains the following properties:

ivy.project.dir = ${basedir}
ivy.lib.dir = ${ivy.project.dir}/lib
ivy.build.artifacts.dir = ${ivy.project.dir}/build/artifacts
ivy.distrib.dir = ${ivy.project.dir}/distrib
	
ivy.configurations = *
ivy.resolver.default.check.modified = false
ivy.status = integration
ivy.dep.file = ivy.xml
ivy.conf.file = ivyconf.xml
ivy.retrieve.pattern = ${ivy.lib.dir}/[artifact]-[revision].[ext]
ivy.deliver.ivy.pattern = ${ivy.distrib.dir}/[type]s/[artifact]-[revision].[ext]
ivy.publish.src.artifacts.pattern = ${ivy.distrib.dir}/[type]s/[artifact]-[revision].[ext]

ivy.ivyrep.default.ivy.root = http://www.jayasoft.fr/org/ivyrep/
ivy.ivyrep.default.ivy.pattern = [organisation]/[module]/ivy-[revision].xml
ivy.ivyrep.default.artifact.root = http://www.ibiblio.org/maven/
ivy.ivyrep.default.artifact.pattern = [module]/[type]s/[artifact]-[revision].[ext]

ivy.ibiblio.default.artifact.root = http://www.ibiblio.org/maven/
ivy.ibiblio.default.artifact.pattern = [module]/[type]s/[artifact]-[revision].[ext]

Example

Here is a more complete example of build file using ivy:

Tasks reference documentation

configure

The configure task is used to configure ivy with an xml configuration file.

See configuration for details about the configuration file itself.

Note for developers:
After the call to this task, a reference to the configured ivy instance used by all subsequent ant tasks is put in the ant project, under the id "ivy.instance".

Attribute	Description	Required
file	path to the configuration file to use	No. If a file is provided, url is ignored. If none are provided, then it attempts to find a file at ${ivy.conf.file}, and if this file does not exist, it uses a default configuration file
url	url of the configuration file to use
host	http authentication host	No, unless authentication is required
realm	http authentication realm
username	http authentication user name
passwd	http authentication password

HTTP Authentication

Note: HTTP Authentication can be used only if commons-httpclient.jar is in your classpath If any of the url you use in ivy (especially in dependency resolvers) need http authentication, then you have to provide the host, realm, username and passwd attributes of the configure task. These settings will then be used in any further call to ivy tasks.

Examples

Simplest configuration

<ivy:configure />

Use either ${ivy.conf.file} if it exists, or the default configuration file

Configure with a file

<ivy:configure file="myconffile.xml" />

Configure with an url

<ivy:configure url="http://mysite.com/myconffile.xml" />

resolve

The resolve task actually resolve dependencies described in an ivy file, and put the resolved dependencies in the ivy cache.
If configure has not been called before resolve is called, a default configuration will be used (equivalent to call configure with no attributes).

After the call to this task, four properties are set in ant:
ivy.organisation: set to the organisation name found in the ivyfile which was used for resolve
ivy.module: set to the module name found in the ivyfile which was used for resolve
ivy.revision: set to the revision name found in the ivyfile which was used for resolve, or a generated revision name if no revision was specified in the file
ivy.resolved.configurations: set to the comma separated list of configurations resolved

Note for developers:
After the call to this task, a reference to the module descriptor resolved is put in the ant project under the id "ivy.resolved.descriptor".

Attribute	Description	Required
file	path to the ivy file to use for resolution	No. Defaults to ${ivy.dep.file}
conf	a comma separated list of the configurations to resolve	No. Defaults to ${ivy.configurations}
haltonfailure	true to halt the build on ivy failure, false to continue	No. Defaults to true
showprogress	true to show dots while downloading, false otherwise	No. Defaults to true
validate	true to force ivy files validation against ivy.xsd, false to force no validation	No. Defaults to default ivy value (as configured in configuration file)

retrieve

The retrieve task copies resolved dependencies anywhere you want in your file system.
If no resolve has been called before retrieve is called, a default resolve is called (equivalent to a call to resolve with no attributes).

Attribute	Description	Required
pattern	the pattern to use to copy the dependencies	No. Defaults to ${ivy.retrieve.pattern}
conf	a comma separated list of the configurations to retrieve	No. Defaults to the configurations resolved by the last resolve call, or * if no resolve was explicitly called
haltonfailure	true to halt the build on ivy failure, false to continue	No. Defaults to true
validate	true to force ivy files validation against ivy.xsd, false to force no validation	No. Defaults to default ivy value (as configured in configuration file)

deliver

Delivers a resolved ivy file of the current module, and possibly do recursive delivery of dependencies.
This task does two main things:
- deliver a resolved ivy file of the current module, based upon the last resolve done. In the resolved ivy file, no latest version of any kind subsist, so the ivy file can be used later safely to obtain the same dependencies (providing that a revision uniquely identifies a module, which should be the case for proper ivy use). - do recursive delivery. This is done only if a deliver target is given to the deliver task.
If a deliver target is set, then it is called for each dependency which has not a suffisant status compared to the deliver status set for this task. This means that if you deliver an integration revision, no recursive delivery will be done. If you deliver a milestione revision, deliver target will be called with each integration dependency. Finally, if you deliver a release revision, then deliver target will be called with each integration and milestone dependency.

The deliver target is called with the following properties available:
* dependency.name : the name of the dependency to recursively deliver
* dependency.published.status : the status to which the dependency should be delivered
* dependency.published.version : the revision to which the dependency should be delivered
* dependency.version : the revision of the dependency that should be delivered (the one that was retrieved during last resolve)
Note that both dependency.published.status and dependency.published.version are in fact asked to the user via standard ant input. the delivered ivy file will update its dependency revisions with those given here.

Attribute	Description	Required
deliverpattern	the pattern to use for ivy file delivery	No. Defaults to ${ivy.deliver.ivy.pattern}
pubrevision	the revision to use for the publication	No. Defaults to the ${ivy.deliver.revision}
pubdate	the publication date to use for the publication. This date should be either 'now', or a date given with the following pattern: yyyyMMddHHmmss	No. Defaults to 'now'
status	the status to use for the publication	No. Defaults to ${ivy.status}
delivertarget	the target to call for recursive delivery	No. No recursive delivery is done by default
validate	true to force ivy files validation against ivy.xsd, false to force no validation	No. Defaults to default ivy value (as configured in configuration file)

publish

Publishes the current modules artifacts.

This task is meant to publish the declared published artifacts of the current module to a repository.
The repository is given through the name of a resolver declared in current ivy configuration. See configuration for details about resolver supporting artifact publishing.
It also publishes the delivered ivy file (except if you don't want), and even deliver it if it has not been done with a previous deliver call. That's why this task takes some parameters useful only for delivery.

Attribute	Description	Required
artifactspattern	the pattern to use to find artifacts to publish	No. Defaults to ${ivy.publish.src.artifacts.pattern}
resolver	the name of the resolver to use for publication	Yes
pubrevision	the revision to use for the publication	No. Defaults to the ${ivy.deliver.revision}
validate	true to force ivy files validation against ivy.xsd, false to force no validation	No. Defaults to default ivy value (as configured in configuration file)
publishivy	True to publish delivered ivy file, false otherwise	No. Defaults to true
warnonmissing	True to warn when artifacts to be published are missing	No. Defaults to true
haltonmissing	True to halt build when artifacts to be published are missing	No. Defaults to true
deliverivypattern	the pattern to use for ivy file delivery, if necessary	No. Defaults to the value of artifactspattern
pubdate	the publication date to use for the delivery, if necessary. This date should be either 'now', or a date given with the following pattern: yyyyMMddHHmmss	No. Defaults to 'now'
status	the status to use for the delivery, if necessary	No. Defaults to ${ivy.status}
delivertarget	the target to call for recursive delivery	No. No recursive delivery is done by default

cachepath

Constructs an ant path consisting of artifacts in ivy cache for a configuration.

This task is usually used after a resolve, and can be used instead of retrieve. Note that this task does not rely on retrieve, because built path is made of artifacts direcly in ivy cache.

Please prefer the use of retrieve + standard ant path creation, which make your build more independent from ivy (once artifacts are properly retrieved, ivy is not required any more).

Built path is registered in ant with a given id, and can thus be used like any other ant path using refid.

Attribute	Description	Required
pathid	the id to reference the built path	Yes
conf	a comma separated list of the configurations to put in the created path	No. Defaults to the configurations resolved by the last resolve call, or * if no resolve was explicitly called
haltonfailure	true to halt the build on ivy failure, false to continue	No. Defaults to true
validate	true to force ivy files validation against ivy.xsd, false to force no validation	No. Defaults to default ivy value (as configured in configuration file)

report

Generates reports of dependecy resolving. One report per configuration is generated, but all reports generated together are hyperlinked one to each other.

This task should be used only after a call to resolve, even if the call was not done during the same ant build.
In fact, this task uses xml report generated by resolve in cache. So if you call resolve on a module for a given configuration, you can call report safely on this module and this configuration as long as you do not clean your ivy cache.

If you want to have an idea of what reports look like, check this very simple example. The task also generates a graphml file which can be loaded with the free yEd graph editor. Then following a few simple steps you can obtain a graph like this one.

Attribute	Description	Required
todir	the directory to which reports should be generated	Yes
graph	true top generates graphml files, false otherwise	No, defaults to true
conf	a comma separated list of the configurations for which a report should be generated	No. Defaults to the configurations resolved by the last resolve call (during same ant build), or ${ivy.resolved.configurations} if no resolve was called
organisation	the name of the organisation of the module for which report should be generated	No, unless no resolve was called during the build. Defaults to last resolved module organisation.
module	the name of the module for which report should be generated	No, unless no resolve was called during the build. Defaults to last resolved module.
validate	true to force ivy files validation against ivy.xsd, false to force no validation	No. Defaults to default ivy value (as configured in configuration file)

var

Sets a variable (by name and value), or set of variables (from file or url) in ivy.
Variables are case sensitive.

Contrary to ant properties, ivy variables are mutable. But a problem with this is that you do not control when variables are substituted, and usually it is done as soon as possible. So changing the value of a variable will have no effect if it has already been substituted. Consequently, using this task is NOT recommended. See reference page for details about ivy variables.

Attribute	Description	Required
name	the name of the variable to set	No
value	the value of the variable to set	Yes when using the name attribute
file	the filename of the property file to load as ivy variables	One of these, when not using the name attribute
url	the url from which to read ivy variables
prefix	Prefix to apply to variables. A "." is appended to the prefix if not specified.	No