artifactproperty

Sets an ant property for each dependency artifacts previously resolved.

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).

The property name and value are generated using the classical pattern concept, all artifact tokens and ivy variables being available.

Attribute	Description	Required
name	a pattern used to generate the name of the properties to set	Yes
value	a pattern used to generate the value of the properties to set	Yes
conf	a comma separated list of the configurations for which properties should be set	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)

Example

Suppose we have one dependency called mydep in revision 1.0 publishing two artifacts: foo.jar and bar.jar.
Then:

will set two properties:

artifactreport

since 1.4
The artifactreport task generates an xml report of all artifacts dependencies resolved by the last resolve task call during the same build.

This report is different from the standard report which reports all modules and artifacts, whle this report is much simpler and focuses only on artifacts, and gives more information on artifacts, such as the original location and the retrieve location.

It is thus easy to use to generate things like a classpath file for an IDE.

See this article by Johan Stuyts (who contributed this task) to see how he uses this task.

Here is an example of generate file:

Attributes

Attribute	Description	Required
tofile	the file to which the report should be written	Yes
pattern	the retrieve pattern to use to fill the retrieve location information about the artifacts	No. Defaults to ${ivy.retrieve.pattern}.
conf	a comma separated list of the configurations to use to generate the report	No. Defaults to the configurations resolved by the last resolve call
haltonfailure	true to halt the build on ivy failure, false to continue	No. Defaults to true

Examples

Generates the artifact report for all configurations resolved during the last resolve call (in the same build).

Generates the artifact report for only the default configuration resolved during the last resolve call.

buildlist

The buildlist task enable to obtain a filelist of files (usually build.xml files) ordered according to ivy dependency information from the least dependent to the most one, or the inverse. (since 1.2)

This is particularly useful combined with subant, to build a set of interelated projects being sure that a dependency will be built before any module depending on it.

since 1.3 A root attribute can also be used to include, among all the modules found, only the one that are dependencies (either direct or transitive) of a root module. This can also be used with the excluderoot attribute, which when set to true will exclude the root itself from the list.

since 1.4.1 A leaf attribute can also be used to include, among all the modules found, only the one that have dependencies (either direct or transitive) on a leaf module. This can also be used with the excludeleaf attribute, which when set to true will exclude the leaf itself from the list.

since 1.4 The ivy.sorted.modules property is set in the ant at the end of the task with a comma separated list of ordered modules. This can be useful for debug or information purpose.

Attribute	Description	Required
reference	the reference of the path to set	Yes
ivyfilepath	the relative path from files to order to corresponding ivy files	No. Defaults to ${ivy.buildlist.ivyfilepath}
root	since 1.3 the name of the module which should be considered as the root of the buildlist	No. Defaults to no root (all modules are used in the build list)
excluderoot	since 1.3 true if the root defined should be excluded from the list	No. Defaults to false
leaf	since 1.4.1 the name of the module which should be considered as the leaf of the buildlist	No. Defaults to no leaf (all modules are used in the build list)
excludeleaf	since 1.4.1 true if the leaf defined should be excluded from the list	No. Defaults to false
haltonerror	true to halt the build when an invalid ivy file is encountered, false to continue	No. Defaults to true
skipbuildwithoutivy	true to skip files of the fileset with no corresponding ivy file, false otherwise. If false the file with no corresponding ivy file will be considered as independent of the other and put at the beginning of the built filelist.	No. Defaults to false
reverse	true to obtain the list in the reverse order, i.e. from the most dependent to the least one	No. Defaults to default false

Parameters specified as nested elements

fileset

FileSets are used to select sets of files to order.

Examples

Builds a list of build.xml files sorted according to the ivy.xml files found at the same level (the default value for ivyfilepath is ivy.xml).

This list can then be used like that:

---

Builds a list of build.xml files sorted according to the ivy.xml files found in an ivy directory relative to those build files. The list is sorted from the most dependent to the least one.

---

Builds a list of build.xml files sorted according to the ivy.xml files found in an ivy directory relative to those build files. Only build.xml files of modules which are dependencies of myapp (either direct or transitive) are put in the result list.

---

Builds a list of build.xml files sorted according to the ivy.xml files found in an ivy directory relative to those build files. Only build.xml files of modules which have dependencies (direct or transitive) on mymodule are put in the result list.

buildnumber

since 1.4
The buildnumber task is similar to the ant buildnumber task, except that it uses ivy repository to find what is the latest version and calculate a new one for you.

When called it sets four properties according to what has been found.
These properties are:

• ivy.revision

the last revision found in the repository

• ivy.new.revision

the new revision calculated from the last one (see below)

• ivy.build.number

the build number found in the repository

• ivy.new.build.number

the new build number calculated from the last one, usually with +1

build numbers are always numbers (composed of digit characters only).
ivy.revision can be not set if no revision was found
ivy.build.number can be not set if no revision was found or if no number was found in it
ivy.new.build.number can be not set if the default new revision to use when no revision is found do not contain any number

The new revision is calculated using a somewhat complex to explain but very easy to use algorithm, depending on which latest version you asked.

Indeed you can ask for a new revision based upon the latest found for a particular prefix (the revision asked), then the new revision will be the one immediately after with only the prefix in common. If no prefix is set the very latest version is searched.

Examples (suppose the latest version of the module is 1.3.1):

revision asked	ivy.revision	ivy.new.revision	ivy.build.number	ivy.new.build.number
1.3	1.3.1	1.3.2	1	2
1	1.3.1	1.4	3	4
2	not set	2.0	not set	0
	1.3.1	1.3.2	1	2

Note that when asking for revision 1, you can get a revision 10.0. To avoid that you can use 1. as revision asked, but in this case ivy won't find revision 1 if its the latest one, and it will thus give 1.0 as new revision. The solution to this problem is to use versions with always the same number of parts (for instance 1.0.0 instead of 1).

Attribute	Description	Required
organisation	the organisation of the module for which a new build number should be calculated	Yes
module	the name of the module for which a new build number should be calculated	Yes
branch	the branch of the module for which a new build number should be calculated	No, defaults to the default branch for this module
revision	the revision prefix for which a new build number should be calculated	No, defaults to no prefix (will find the latest version)
default	the default revision to assume when no revision prefix is asked and no revision is found	No, defaults to 0
defaultBuildNumber	the default build number to use for the first revision	No, defaults to 0
revSep	the revision separator to use when no matching revision is found, to separate the revision prefix from the build number	No, defaults to '.'
prefix	the prefix to use for the property names set (will be prefix.revision, prefix.new.revision, ...)	No, defaults to ivy

Examples

Here is how it can be used (suppose 1.3.1 is the latest version of ivy in the repository):

will set 1.3.1 as revision, 1.3.2 as new revision, 1 as build number and 2 as new build number

---

will set 1.3.1 as revision, 1.3.2 as new revision, 1 as build number and 2 as new build number

---

will set 1.2 as revision, 1.2.1 as new revision, no build number and 1 as new build number

---

will set 1.3.1 as revision, 1.4 as new revision, 3 as build number and 4 as new build number

---

will set no revision, 3.0 as new revision, no build number and 0 as new build number

---

If called while no release candidate is in the repository, will set ivy.revision to 1.4-RC1. Then it will increment each time, 1.4-RC2, 1.4-RC3, and so on.

cachefileset

Constructs an ant fileset consisting of artifacts in ivy cache for a configuration (since 1.2).


This is a post resolve task, with all the behaviour and attributes common to all post resolve tasks. Note that this task
does not rely on retrieve, because built fileset 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 fileset is registered in ant with a given id, and can thus be used like any other ant fileset using
refid.

Attribute	Description	Required
setid	the id to reference the built fileset	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
type	comma separated list of artifact types to accept in the path, * for all	No. Defaults to *

cachepath

Constructs an ant path consisting of artifacts in ivy cache (or origin location with depending on useOrigin setting) for a resolved module configuration.

This is a post resolve task, with all the behaviour and attributes common to all post resolve tasks.

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.

since 1.4 The behaviour is like this when 'useOrigin=true':

• if the artifact is not local, the location from within the cache is used
• if the artifact is a local artifact, it's original location is used

Note that if resolve has been called separately, the copy to the cache may have occur normally if useOrigin was not set when calling resolve. If resolve has not been called, it will be called automatically with useOrigin set to the value specified on this task.

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
type	comma separated list of artifact types to accept in the path, * for all (since 1.2)	No. Defaults to *
useOrigin	true to use original location of local artifacts, false to use only cache locations since 1.4	No. Defaults false

Examples

Construct an ant path composed of all artifacts being part of the default configuration obtained through the last resolve call.

---

Same as before but will use the original location for local artifacts, and the cache location for other artifacts.

---

Resolves the emma module in version 2.0.4217, constructs an ant path with the corresponding artifacts, and then define the emma tasks using this path.

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.

Since 1.4: It's also possible to configure authentication settings for multiple urls. This can be done with the <credentials> subelements. See the examples for more details.

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" />

Configure multiple URLs which require autentication

<ivy:configure file="path/to/my/ivyconf.xml">
  <credentials host="myhost.com" realm="My Realm" username="myuser" passwd="mypasswd" />
  <credentials host="yourhost.com" realm="Your Realm" username="myuser" passwd="myotherpasswd" />
</ivy:configure> 

deliver

Delivers a resolved ivy file of the current module, and possibly do recursive delivery of dependencies.
This task does two main things:

Generate a resolved ivy file

This task generates a resolved ivy file of the current module, based upon the last resolve done. The resolved ivy file contains updated information about the delivered module, such as revision and status.

Moreover, all included configurations files are included in the ivy file, and variables are replaced by their values.

Finally, in the resolved ivy file, dynamic revisions are replaced by the static ones that have been found during the resolve step, 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).

since 1.3 The replacement of dynamic revisions by static ones can be turned off, so that dynamic revisions are kept in the ivy file.

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 (via an antcall) 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 milestone or a release revision, deliver target will be called with each integration 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)

Both dependency.published.status and dependency.published.version can be either asked to the user through ant input tasks (default behaviour), or be always the same for the whole recursive delivery process if the following properties are set:

• recursive.delivery.status

set to the status to which all dependencies requiring to be delivered will be

• recursive.delivery.version

set to the version to which all dependencies requiring to be delivered will be

Usually the deliver target itself triggers an another ant build (using ant task) even if this is up to you to decide.

The delivered ivy file will update its dependency revisions with those given here.

deliver and publish

The deliver task is most of the time not called explicitly, but rather called automatically by the publish task. So, when shall the deliver task be called explictly? When you actually need to separate what is performed by the deliver task (see above), from what is performed by the publish task, i.e. upload a module to a repository.

And this can be particularly useful if you want to process the generated ivy file before uploading it (if you want to add automatically more information like an SCM tag used, the user who performed the release, ...).

It can also be useful if you want to trigger a recursive delivery and then ensure that you get the recursively delivered modules as dependencies. In this case your build order may look like this:
- ivy:configure
- ivy:resolve
- ivy:deliver with recursive delivery
- ivy:resolve again with the ivy file generated by the recursive delivery
- do your build stuff (compile, jar, whatever)
- ivy:publish

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 ${ivy.deliver.revision} if set, or the revision resolved if set, or a timestamp
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)
replacedynamicrev	true to replace dynmic revisions by static ones in the delivered file, false to avoid this replacement since 1.3	No. Defaults to true

findrevision

since 1.4
Finds the latest revision of a module matching a given version constraint.

A version constraint is what is used when declaring a dependency on a module.
If the module is not found the property is not set.

Attributes

Attribute	Description	Required
organisation	the organisation of the module to find	Yes
module	the the name of the module to find	Yes
branch	the branch of the module to find	No, defaults to the default branch for the given module
revision	the revision constraint to apply	Yes
property	the property to set with the found revision	No, defaults to ivy.revision

Examples

finds the latest version of ivy available in the repository and sets the property ivy.revision according to what was found.

---

same as above but only with 1.0 sub versions.

info

since 1.4
The info task ease the access to some essential data contained in an ivy file without performing a dependency resolution.

The information is retrieved by setting ant properties:

ivy.organisation	The organisation of the module, as found in the info tag of the ivy file parsed
ivy.module	The name of the module, as found in the info tag of the ivy file parsed
ivy.revision	The revision of the module, as found in the info tag of the ivy file parsed
ivy.configurations	A comma separated list of configurations of the module, as declared in the configurations section
ivy.public.configurations	A comma separated list of public configurations of the module, as declared in the configurations section

Attributes

Attribute	Description	Required
file	the ivy file to parse	Yes

Examples

Parses ${basedir}/path/to/ivy.xml and set properties as described above accordingly.

install

Installs a module and all its dependencies in a resolver. since 1.3

The module to install should be available in a resolver, and will be installed in another resolver which should support publish.

This is particularly useful for users who only have a private repository, and want to benefit from public repositories from time to time. In this case, when a module is missing in the private repository, a call to install let download the module from a public repository not usually used for dependency resolution, and install it and its dependencies in the private repository.

For more details about this task and its usage see the build repository tutorial

Attribute	Description	Required
from	the name of the resolver in which the module must be found	Yes
to	the name of the resolver in which the module must be installed	Yes
organisation	the name of the organisation of the module to install	Yes
module	the name of the module to install	Yes
revision	the revision of the module to install	Yes
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)
overwrite	true to override modules already present in the destination resolver, false otherwise	No, defaults to false
transitive	true to install the module and all its transitive dependencies, false to install only the module	No, defaults to false
matcher	the name of the matcher to use to find the modules to install	No, defaults to exact

Examples

Installs the module commons-lang from apache in revision 2.0 in the resolver myfsresolver. The module is found in the resolver named 'ivyrep'.

listmodules

since 1.4
Finds the list of modules in the repository matching some criteria and set a corresponding list of properties in ant.

The criteria is set by given patterns matching the organisation, name branch and revision of the modules to find.

To know if a module matches the criteria ivy will use the configured pattern matcher.

Attributes

Attribute	Description	Required
organisation	the pattern matching the organisation of the modules to list	Yes
module	the pattern matching the name of the modules to list	Yes
branch	the pattern matching the branch of the modules to list	No, defaults to '*'
revision	the pattern matching the revision of the modules to list	Yes
matcher	the name of the pattern matcher to use for matching the modules fields	No. Defaults to exactOrRegexp.
property	the pattern of the property to set when a module is found	Yes
value	The pattern of the value to set when a module is found	Yes

Examples

will find all revisions of the module ivy in the org jayasoft, and create one property for each revision found, the name of the property depending on the revision, the value being always 'found'

---

use the glob matcher to find all modules which name starts with ivy with revision 1.0, and sets for each a property with module name found and organisation for value.
Example:
modules.ivy=jayasoft
modules.ivyde=jayasoft
modules.ivytools=ivytools

post resolve tasks

Several tasks in Ivy are considered as post resolve task and share a common behaviour and settings accordingly.

These tasks are:

• retrieve
• cachefileset
• cachepath

All these tasks will trigger automatically a resolve if:

• none has already been called in the current build with the attribute keep set to true (see below)
• organisation and module are not set

Since Ivy 1.4, there are two ways to run a resolve: with an ivy file, or with the inline mode.
When you call resolve with an ivy file, the default for it is to keep the resolved data for use by the subsequent post resolve tasks. When you run an inline resolve, the default is not to keep the data. Youo can override this behaviour by setting the keep attribute as you like.

If you want to to reuse the resolved data obtained through a call to resolve in another build (i.e. not the current one), then you have to set the organisation and module attributes. This work only if the cache was not cleaned since your last resolve call. This does not work with inline calls, which must be performed in the same build.

The attributes listed are then mostly used only if a resolve is triggered automatically.

Attributes

Attribute	Description	Required
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
inline	true to use inline mode, false to resolve an ivy file since 1.4	No. defaults false
organisation	the organisation of the module to retrieve. This usually doesn't need to be set since it defaults to the last resolved one, except for inline mode where it is required.	Yes in inline mode, otherwise no, it then defaults to last resolved module name
module	the name of the module to retrieve. This usually doesn't need to be set since it defaults to the last resolved one, except for inline mode where it is required.	Yes in inline mode, otherwise no, it then defaults to last resolved module name
revision	the revision constraint of the module to retrieve. Used only in inline mode. since 1.4	No. Defaults to latest.integration
transitive	true to resolve dependencies transitively, false otherwise since 1.4	No. Defaults to true
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)

Examples

Resolves the emma module in version 2.0.4217, constructs an ant path with the corresponding artifacts, and then define the emma tasks using this path.

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 or if forcedeliver is set to true. That's why this task takes some parameters useful only for delivery.

since 1.4.1
The source artifact pattern can be specified either as an attribute on the task (artifactspattern) or using a list of nested artifacts element (see examples below).

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}
forcedeliver	true to force the implicit call to deliver, false to do it only if the ivy file to publish doesn't exist yet since 1.4	No. Defaults to false
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)
replacedynamicrev	true to replace dynmic revisions by static ones in the delivered file, false to avoid this replacement since 1.3	No. Defaults to true
publishivy	True to publish delivered ivy file, false otherwise	No. Defaults to true
conf	A comma separated list of configurations to publish. Note that the ivy file won't be published in this case, publishivy must be set to false. since 1.4.1	No. Defaults to all configurations published
overwrite	True to overwrite files in repository if the revision already exist, false to let it as is	No. Defaults to false
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
srcivypattern	the pattern to use to find ivy file to publish, and even deliver if necessary (since 1.2)	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

Examples

Publishes the last resolved module in the local resolver with revision 1.0, looking for artifacts in directories 1 and 2.

repreport

Generates reports about dependencies among several modules in the repository (repreport stands for repository report).since 1.4

This task is similar to the report task, except that instead of working on a single module you just resolved, it works with a set of modules in your repository.

Note that the set of modules for which you generate the report is determined by setting organisation module and revision and using a matcher, but also by the dependencies of these modules. No dependency is excluded.

Usually the most useful report is a graph, you can generate either a graphml file that you can then easily layout using yEd, or a dot file which is the format recognized by graphviz, which is a free tool which does automatic graph layout, and can thus be used to generate automatically a GIF or PNG of the dependencies between all your modules.

Attribute	Description	Required
organisation	A pattern matching the organisation of the modules for which the report should be generated	No, defaults to '*'
module	A pattern matching the name of the modules for which the report should be generated	No, defaults to '*'
branch	The name of the branch of the modules for which the report should be generated	No, defaults to no branch specified
revision	The revision of the modules for which the report should be generated. Only one revision per module will be used, so most of the time keeping the default (latest.integration) is the best thing to do, because it's not very easy to specify only one revision for several modules.	No, defaults to 'latest.integration'
todir	the directory to which reports should be generated	No, defaults to execution directory
outputname	the name to use for the generate file (without extension)	No, defaults to ivy-repository-report
xml	true to generate a xml report, false otherwise	No, defaults to true
xsl	true to generate a report using xslt, false otherwise	No, defaults to false
xslfile	indicates which xsl file should be used to generate the report	Yes if you want to use xsl transformation
xslext	indicates the extension to use when generating report using xsl	No defaults to 'html'
graph	true to generate graphml file, false otherwise	No, defaults to false
dot	true to generate graphviz dot format file, false otherwise	No, defaults to false
matcher	the name of the matcher to use for matching modules names and organisations in your repository	No. Defaults to exactOrRegexp
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)

Examples

To generate a xml report for all the latest versions of all the modules in your repository:

---

To generate a graphml report for all the latest versions of all the modules in your repository:

---

To generate a xml report for all the latest versions of the modules from the organisation foo in your repository:

---

To generate a xml report for all the versions on the 1.x stream of the modules named bar* from the organisation foo in your repository:

---

To generate an XML report using a custom stylesheet:

---

To generate an XML report using a custom stylesheet which needs some parameters:

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

An additional property is set to true if there are changes since the last resolve, and to false otherwise: ivy.deps.changed (since 1.2)

When ivy has finished the resolve task, it outputs a summary of what has been resolved. This summary looks like this:

---------------------------------------------------------------------
|                  |            modules            ||   artifacts   |
|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
|      default     |   4   |   0   |   0   |   0   ||   4   |   0   |
---------------------------------------------------------------------

This table gives some statistics about the dependency resolution. Each line correspond to a configuration resolved. Then the table is divided in two parts:

• modules
• number

This is the total number of dependency modules resolved in this configuration, including transitive ones

• search

This is the number of dependency modules that required a repository access. The repository access is needed if the module is not yet in cache, or if a latest version is required, or in some other cases (depending on checkModified, for instance)

• downlded

This is the number of dependency ivy files downloaded from the repository. This number can be less than the total number of modules even with a clean cache, if no ivy file is provided for some dependencies.

• evicted

This is the number of dependency module evicted by conflict managers.

• artifacts
• number

This is the total number of artifacts resolved in the given configuration.

• dwnlded

This is the number of artifacts actually downloaded from the repository.

since 1.4 A new inline mode allow to call a resolve without an ivy file, by setting directly the module which should be resolved from the repository. It is particularly useful to install released software, like a ant task for example. When inline is set to true, the organisation module and revision attributes are used to specify which module should be resolved from the repository.

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} or nothing in inline mode
conf	a comma separated list of the configurations to resolve	No. Defaults to ${ivy.configurations}
useOrigin	true to avoid the copy of local artifacts to the cache and use directly their original location, false otherwise since 1.4. To know if an artifact is local ivy asks to the resolver. Only filesystem resolver is considered local by default, but this can be disabled if you want to force the copy on one filesystem resolver and use the original location on another. Note that it is safe to use useOrigin even if you some no local resolvers, Ivy will behave as usual in this case. Note also that this only applies to artifacts, not to ivy files, which are still copied in the cache.	No. defaults to false
inline	true to use inline mode, false to resolve an ivy file since 1.4	No. defaults to false
organisation	the organisation of the module to resolve in inline mode since 1.4	Yes in inline mode, no otherwise.
module	the name of the module to resolve in inline mode since 1.4	Yes in inline mode, no otherwise.
revision	the revision constraint to apply to the module to resolve in inline mode since 1.4	No. Defaults to "latest.integration" in inline mode, nothing in standard mode.
type	comma separated list of accepted artifact types (since 1.2)	No. defaults to ${ivy.resolve.default.type.filter}
haltonfailure	true to halt the build on ivy failure, false to continue	No. Defaults to true
failureproperty	the name of the property to set if the resolve failed since 1.4	No. No property is set by default.
transitive	true to resolve dependencies transitively, false otherwise since 1.4	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)

Examples

Resolve all dependencies declared in path/to/ivy.xml file.

---

Same as above, but with transitive dependencies disabled.

---

Resolve the dependencies declared in the configuration default and test of the path/to/ivy.xml file.

---

Resolve all dependencies declared in path/to/ivy.xml file, but download only jar artifacts.

---

Resolve the commons-lang module revision 2+ from the repository, with its dependencies.

retrieve

The retrieve task copies resolved dependencies anywhere you want in your file system.

This is a post resolve task, with all the behaviour and attributes common to all post resolve tasks.

since 1.4 This task can even be used to synchronize the destination directory with what should actually be in according to the dependency resolution. This means that by setting sync="true", Ivy will not only copy the necessary files, but it will also remove the files which do not need to be there.

The synchronisation actually consists in deleting all filles and directories in the root destination directory which are not required by the retrieve.

The root destination directory is the the directory denoted by the first level up the first token in the destination pattern.
Example:
pattern: lib/[conf]/[artifact].[ext]
root: lib

since 1.4 The behaviour is like this when 'useOrigin=true':

• if the artifact is not local, the location from within the cache is used
• if the artifact is a local artifact, it's original location is used

Note that if resolve has been called separately, the copy to the cache may have occur normally if useOrigin was not set when calling resolve. If resolve has not been called, it will be called automatically with useOrigin set to the value specified on this task.

Attribute	Description	Required
pattern	the pattern to use to copy the dependencies	No. Defaults to ${ivy.retrieve.pattern}
ivypattern	the pattern to use to copy the ivy files of dependencies since 1.3	No. Dependencies ivy files are not retrieved by default.
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
sync	true to synchronize the destination, false to just make a copy since 1.4	No. Defaults to false
type	comma separated list of accepted artifact types since 1.4	No. All artifact types are accepted by default.
useOrigin	true to copy artifacts from their original location for local artifacts, false to use only cache locations since 1.4	No. Defaults to false

Examples

Retrieves dependencies using default parameters. This usually retrieves all the dependencies of the last resolve call to a lib directory.

---

Retrieves all dependencies of the last resolve call to a lib directory, dependencies being separated in directories named by configuration, each conf directory containing corresponding artifacts without the revision.
For instance, if the ivy file declares two configurations default and test, the resulting lib dir could look like this:

Note that if a dependency is required in the two configurations, it will be copied in the two directories. The download of the dependency is however only made once at resolve time.

---

Same as before, but with synchronisation enabled.

For instance, if the ivy file declares two configurations default and test, the resulting lib dir could look like this:

And now suppose commons-logging is no longer part of the dependencies of the default configuration, then a new call to retrieve will result in:

With no synchronisation, commons-logging would not have been removed by the call.

---

Retrieves only the dependencies of the runtime configuration in directories named by artifact type. The resulting lib dir could look like this:

---

Resolves and retrieve the latest version of the module bar and its dependencies in the directory pointed by ${my.install.dir}.

report

Generates reports of dependency 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.

If a custom XSL is specified, it's possible to specify additional parameters to the stylesheet.

Attribute	Description	Required
todir	the directory to which reports should be generated	No, defaults to ${ivy.report.todir}, or execution directory if not defined
outputpattern	the generated report names pattern	No, defaults to ${ivy.report.output.pattern}, or [organisation]-[module]-[conf].[ext] if not defined
xsl	true to generate a report (by default html report) using xslt, false otherwise since 1.3	No, defaults to true
xml	true to generate a xml report, false otherwise since 1.3	No, defaults to false
graph	true to generate graphml files, false otherwise	No, defaults to true
dot	true to generate dot files, false otherwise since 1.4	No, defaults to false
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)
xslfile	indicates which xsl file should be used to generate the report	No, defaults to ivy provided xsl which generates html report

Examples

To generate a HTML and graphml report:

---

To generate a HTML report only:

---

To generate an XML report using a custom stylesheet:

To generate an XML report using a custom stylesheet which needs some parameters:

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