Using from Ant
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:org.apache.ivy.ant"attribute of your project tag), and you can call ivy tasks.
If you want to make your build handle ivy.jar in either ant lib dir or a local lib dir, you can use a taskdef like this:
<path id="ivy.lib.path">Combined with the antlib definition in the project namespace, it will load Ivy classes either from your ant lib or a local directory (path/to/dir/with/ivy/jar in this example).
<fileset dir="path/to/dir/with/ivy/jar" includes="*.jar"/>
</path>
<taskdef resource="org/apache/ivy/ant/antlib.xml"
uri="antlib:org.apache.ivy.ant" classpathref="ivy.lib.path"/>
If you use ant 1.5.1 or superior, you have to define the tasks you use in your build file. For instance:
<taskdef name="ivy-configure" classname="org.apache.ivy.ant.IvyConfigure"/>Note: the tasks listed above are non exhaustive. For a complete list of tasks with the corresponding classes, see the antlib.xml file in svn or the version you use.
<taskdef name="ivy-resolve" classname="org.apache.ivy.ant.IvyResolve"/>
<taskdef name="ivy-retrieve" classname="org.apache.ivy.ant.IvyRetrieve"/>
<taskdef name="ivy-deliver" classname="org.apache.ivy.ant.IvyDeliver"/>
<taskdef name="ivy-publish" classname="org.apache.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 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:
<target name="resolve">Those 3 tasks follow the 3 main steps of ivy retrieving dependencies process:
<ivy:configure />
<ivy:resolve file="${ivy.dep.file}" conf="${ivy.configurations}" />
<ivy:retrieve pattern="${ivy.retrieve.pattern}" conf="${ivy.configurations}" />
</target>
- 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.
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.resolver.default.check.modified = false
ivy.default.always.check.exact.revision = true
ivy.configurations = *
ivy.resolve.default.type.filter = *
ivy.status = integration
ivy.dep.file = ivy.xml
ivy.settings.file = ivysettings.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.report.output.pattern = [organisation]-[module]-[conf].[ext]
ivy.buildlist.ivyfilepath = ivy.xml
ivy.checksums=sha1,md5
For the latest version of these properties, you can check the svn version.Ivy tasks attributes : generalities
Some tasks attributes values may be given through different places. The three possible places are :- task attribute
- ivy instance
- project property
The ivy instance considered here is an instance of the class Ivy, which is setup by a call to the configure task, and then reused for other tasks. Because most of the tasks need an ivy instance, they first check if one is available (i.e. configure has been called), and if none is available, then a default configure is called and the resulting ivy instance is used in the remaining tasks (unless another configure is called).
It isn't generally necessary to understand this, but it can lead to some issues if you forget to call configure before another task and if the configure step was required in your environment.
Usual cycle of main tasks
Example
Here is a more complete example of build file using ivy:<project xmlns:ivy="antlib:org.apache.ivy.ant" name="sample" default="resolve">All ivy tasks are documented in the following pages.
<target name="resolve">
<ivy:configure file="../ivysettings.xml" />
<ivy:resolve file="my-ivy.xml" conf="default, myconf" />
</target>
<target name="retrieve-default" depends="resolve">
<ivy:retrieve pattern="lib/default/[artifact]-[revision].[ext]" conf="default" />
</target>
<target name="retrieve-myconf" depends="resolve">
<ivy:retrieve pattern="lib/myconf/[artifact]-[revision].[ext]" conf="myconf" />
</target>
<target name="retrieve-all" depends="resolve">
<ivy:retrieve pattern="lib/[conf]/[artifact]-[revision].[ext]" conf="*" />
</target>
<target name="deliver" depends="retrieve-all">
<ivy:deliver deliverpattern="distrib/[artifact]-[revision].[ext]"
pubrevision="1.1b4" pubdate="20050115123254" status="milestone" />
</target>
<target name="publish" depends="deliver">
<ivy:publish resolver="internal"
artifactspattern="distrib/[artifact]-[revision].[ext]"
pubrevision="1.1b4" />
</target>
</project>