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 <b>1.6.0</b> or superior, you just have to add ivy namespace to your project (<code>xmlns:ivy="antlib:org.apache.ivy.ant"</code> 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:
<code>
<path id="ivy.lib.path">
    <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"/>
</code>
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).

If you use ant <b>1.5.1</b> or superior, you have to define the tasks you use in your build file. For instance:
<code>
  <taskdef name="ivy-configure" classname="org.apache.ivy.ant.IvyConfigure"/>
  <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"/>
</code>
<em>Note: the tasks listed above are non exhaustive. For a complete list of tasks with the corresponding classes, see the [[svn:src/java/org/apache/ivy/ant/antlib.xml antlib.xml]] file in svn or the version you use.</em>

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.
<h1>Calling ivy from ant: first steps</h1>
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:
<code>
<ivy:retrieve />
</code>
This calls ivy with default values, which might be ok in several projects. In fact, it is equivalent to:
<code type="xml">
<target name="resolve">
    <ivy:configure />
    
    <ivy:resolve file="${ivy.dep.file}" conf="${ivy.configurations}" />
    
    <ivy:retrieve pattern="${ivy.retrieve.pattern}" conf="${ivy.configurations}" />
</target>
</code>

Those 3 tasks follow the 3 main steps of the ivy retrieving dependencies process:
<ul>
<li>First the configure task tells it how it can find dependencies giving it a path to an <a href="settings.html">xml settings file</a>.</li> 
<li>Then the resolve task actually resolves dependencies described by an <a href="ivyfile.html">ivy file</a>, and puts those dependencies in the ivy cache (a directory configured in the settings file).</li>
<li>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.</li>
</ul>

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:
<code>
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
</code>
<em>For the latest version of these properties, you can check the [[svn:src/java/org/apache/ivy/core/settings/ivy.properties svn version]].</em>

<span class="since">since 2.0</span> After calling the first Ivy task, the property ivy.version will be available and contains the version of the used Ivy library.

<h1>Ivy tasks attributes : generalities</h1>
Some tasks attributes values may be given through different places. The three possible places are :
<ol>
<li>task attribute</li>
<li>ivy instance</li>
<li>project property</li>
</ol>
The places are queried in this order, so anything set in task attribute will overwrite what would have been found in ivy instance, for example.

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.

<h1>Usual cycle of main tasks</h1>
<center><img src="images/main-tasks.png" /></center>
<h1>Example</h1>
Here is a more complete example of build file using ivy:

All ivy tasks are documented in the following pages.