Ivy Documentation

Welcome to the official Ivy documentation.

What is Ivy?

Ivy is an agile dependency manager, primarily focused on managing java dependencies.
Ivy is open source and released under a very permissive BSD license.
Ivy has a lot of powerful features, the most popular and useful being its flexibily, integration with ant, and its strong transitive dependencies management engine.
The transitive dependencies management is a feature which let you get dependencies of your dependencies, transitively. In order to address this problematic ivy needs to find metadata about your modules, usually in an ivy file. To find these metadata and your dependencies artifacts (usually jars), Ivy can be configured to use a lot of different repositories.

About this doc

If you browse this documentation from your installation of ivy, you can also check the online version for latest updates and comments. To easily navigate to the online version, you will find a link to the corresponding online version on each page just after the title.

The online version of this documentation is updated periodically, especially when new features are added during development. So if you find something documented here not available in your version of ivy, it may be because it is available only with the latest download.

If you want to view the whole documentation in a single printer-friendly page, please use the printer-friendly link at the bottom of any documentation page in the online documentation.

Other places to go

Check Ivy features.
Read our FAQ.
Ask for help on our forum.
Report bug or feature request in our issue tracking system.
Check external tools and resources.

Overview

This documentation is decomposed in 3 main parts:

Tutorials

The best way to learn is to practice! That's what the ivy tutorials will help you to do, to discover some of the great ivy features.

Here is the very first tutorial, it doesn't even require to install Ivy, and should not take more than 30 seconds if you already have ant and a jdk properly installed:

If you have any trouble, check the FAQ, it may be related to your internet connection (proxy anyone?).

OK, you've seen how easy it is to make your first step with ivy? Go ahead with the other tutorials, but before make sure you have properly installed ivy and downloaded the tutorials sources (included in all ivy distributions, in the src/example directory).

The following tutorials are available:

Quick Start

In this example, we will see one of the easiest way to use ivy. No configuration or other complicated files to write, only the list of libraries the project will use.

If you have already followed the go-ivy tutorial on the tutorials home page, this tutorial will be already familiar. It is actually pretty much the same, except that it requires ivy to be installed in your ant lib, and the java source and the ivy dependencies are available in separate files. For the java source, it's definitly recommended to put it in a separate file. For ivy dependencies, it depends on your usage and is discussed on the best pratices page.

But enough introduction material, let's go with this simple tutorial!

You'll find this tutorial sources in the ivy distribution in the src/example/hello-ivy directory.

The ivy.xml file

This file is used to describe the dependencies of the project on other libraries.
Here is the sample:

<ivy-module version="1.0">
    <info organisation="jayasoft" module="hello-ivy" />
    <dependencies>
        <dependency org="apache" name="commons-lang" rev="2.0" />
    </dependencies>
</ivy-module>

The build.xml file

The build file corresponding to use it, contains only:

<project xmlns:ivy="antlib:fr.jayasoft.ivy.ant" name="hello-ivy" default="run">
   
    ...
   
    <!-- =================================
          target: resolve             
        ================================= -->
    <target name="resolve" description="--> retrieve dependencies with ivy">
        <ivy:retrieve />
    </target>
</project>

Running the project

To run the sample, open a dos (or shell) window, and go under the hello-ivy example directory.
Then, on the command prompt, just run ant :

I:\hello-ivy>ant
Buildfile: build.xml

resolve:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::
no configuration file found, using default...
:: resolving dependencies :: jayasoft/hello-ivy-working@xmen
        confs: [default]
downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-2.0.jar(2.0) ...
..................................... (165kB)
        [SUCCESSFUL ] apache/commons-lang-2.0/commons-lang.jar[jar] (4688ms)
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   1   |   1   |   0   |   0   ||   1   |   1   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/hello-ivy
        confs: [default]
        1 artifacts copied, 0 already retrieved

run:
    [mkdir] Created dir: I:\hello-ivy\build
    [javac] Compiling 1 source file to I:\hello-ivy\build
     [java] standard message : hello ivy !
     [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !

BUILD SUCCESSFUL
Total time: 8 seconds

What happened ?

Without any configuration, other than it's default configuration, ivy retrieve files from the maven ibiblio libraries repository. That's what happened here.
The resolve task has downloaded the commons-lang.jar file from ibiblio, then copied it to the ivy cache and then dispatch it in the default library directory of the project : the lib dir.
Some will say that the task was long to achieve. Yeah, it's true it was, but it has downloaded from the web the needed file. Let's try to run it again:

I:\hello-ivy>ant
Buildfile: build.xml

resolve:
:: resolving dependencies :: jayasoft/hello-ivy-null :: [default]
:: resolution report ::
        [default] jayasoft/hello-ivy-working@rahan: 1 artifacts (0 downloaded)
:: retrieving :: jayasoft/hello-ivy :: [default]

run:
     [java] standard message : hello ivy !
     [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !

BUILD SUCCESSFUL
Total time: 1 second

Great ! the cache was used, no download was needed and the build was instantaneous.

If you want to check the content of the cache, by default it is put in your user home in a .ivy/cache directory.

And now, if you want to generate a report detailing all the dependencies of your module, you can call the report target, and check the generated file in the build directory. You should obtain something looking like this.

You are now ready to go to the next tutorials to go one step beyond using ivy transitive dependencies management.

Using IvyRep

In this example, we will see the easiest way to use ivy and benefit from its transitive dependencies feature.
No configuration or other complicated files to write, only the list of libraries the project will use.

The ivy.xml file

This file is used to describe, the dependencies of the project on other libraries.
Here is the sample :

<ivy-module version="1.0">
    <info organisation="jayasoft" module="hello-ivy" />
    <dependencies>
        <dependency org="apache" name="commons-lang" rev="2.0" />
        <dependency org="apache" name="commons-cli" rev="1.0" />
    </dependencies>
</ivy-module>

The build file corresponding to use it, contains only :

<project xmlns:ivy="antlib:fr.jayasoft.ivy.ant" name="hello-ivy" default="run">
   
    ...
   
    <!-- =================================
          target: resolve             
        ================================= -->
    <target name="resolve" description="--> retreive dependencies with ivy">
        <ivy:retrieve />
    </target>
</project>

Running the project

To run the sample, open a shell window, and go under the ivyrep example directory.
Then, on the command prompt, just run ant :

I:\ivyrep>ant
Buildfile: build.xml

resolve:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::
no configuration file found, using default...
:: resolving dependencies :: jayasoft/ivyrep-example-working@xmen
        confs: [default]
downloading http://www.ibiblio.org/maven/commons-cli/jars/commons-cli-1.0.jar(1.0) ...
...... (31kB)
        [SUCCESSFUL ] apache/commons-cli-1.0/commons-cli.jar[jar] (1437ms)
downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-2.0.jar(2.0) ...
..................................... (165kB)
        [SUCCESSFUL ] apache/commons-lang-2.0/commons-lang.jar[jar] (5640ms)
downloading http://www.ibiblio.org/maven/commons-logging/jars/commons-logging-1.0.jar(1.0) ...
..... (21kB)
        [SUCCESSFUL ] apache/commons-logging-1.0/commons-logging.jar[jar] (1250ms)
:: resolution report ::
        :: evicted modules:
        apache/commons-lang-1.0 by [apache/commons-lang-2.0] in [default]
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   4   |   3   |   2   |   1   ||   3   |   3   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/ivyrep-example
        confs: [default]
        3 artifacts copied, 0 already retrieved

run:
    [mkdir] Created dir: I:\ivyrep\build
    [javac] Compiling 1 source file to I:\ivyrep\build
     [java] standard message : hello ivy !
     [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !

BUILD SUCCESSFUL
Total time: 16 seconds

What happened ?

Without any configuration, other than it's default configuration, ivy uses the ivyrep resolver. This resolver looks for ivy files on ivyrep, and for artifacts on ibiblio. That's what happened here.

The resolve task has found an ivy file on ivyrep for commons-cli 1.0.
This ivy file indicates that commons-cli 1.0 depends on commons-lang 1.0 and commons-logging 1.0.

The resolve task detects the conflict between the revision 2.0 of commons-lang that is asked in the ivy above, and the revision 1.0 required in commons-cli. With no particular conflict manager, the 2.0 is selected, and the 1.0 is evicted. The 1.0 being evicted, it is not downloaded at all.

The resolve task has then downloaded the commons-cli 1.0, commons-logging 1.0 and commons-lang.jar 2.0 files from ibiblioand put them to the ivy cache.
Then the retrieve task has copied them in the default library directory of the project: the lib dir.
Some will say that the task was long to achieve. Yes, it's true it was, but it has downloaded from the internet the needed files. Let's try to run it again:

I:\ivyrep>ant
Buildfile: build.xml

resolve:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::
no configuration file found, using default...
:: resolving dependencies :: jayasoft/ivyrep-example-working@xmen
        confs: [default]
:: resolution report ::
        :: evicted modules:
        apache/commons-lang-1.0 by [apache/commons-lang-2.0] in [default]
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   4   |   0   |   0   |   1   ||   3   |   0   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/ivyrep-example
        confs: [default]
        0 artifacts copied, 3 already retrieved

run:
     [java] standard message : hello ivy !
     [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !

BUILD SUCCESSFUL
Total time: 2 seconds

Great ! the cache was used, no download was needed and the build was almost instantaneous.

If you want to check the content of the cache, by default it is put in your user home in a .ivy/cache directory. Check the next tutorials to see how to configure this.

Configuring default resolver

Until Ivy 1.2a, the default resolver was a simple ivyrep resolver, with only a small number of possibilities of configuration. Whenever you wanted to do something slightly more complicated than looking for ivy files on ivyrep and artifacts on ibiblio, you had to write your own ivyconf file (see other tutorials and configuration reference for details about this).

Ivy 1.3 introduces a new default configuration, fully compatible pre 1.3 one, but a lot more configurable.

Concept

This default configuration mainly consists of 3 kind of repositories:

  • local
  • a repository which is private to the user.

  • shared
  • a repository which is shared between all the member of a team

  • public
  • a public repository on which most modules can be found

Note that if you work alone, the distinction between local and shared repository is not very important, but there are some things to know to distinguish them.

Now let's describe each of these repositories concept in more details. We will describe how they are setup physically later.

Local

The local repository is particularly useful when you want to do something without being disturb by anything else happening in the environment. This means that whenever ivy is able to locate a module in this repository it will be used, no matter of what is available in others.

For instance, if you have a module declaring a dependency on the module foo in revision latest.integration, then if a revision of foo is found in the local repository, it will be used, even if a more recent revision is available in other repositories.

This may be disturbing for some of you, but imagine you have to implement a new feature on a project, and in order to achieve that you need to modify two modules: you add a new method in module foo and exploit this new method in module bar. Then if you publish the module foo to your local repository, you will be sure to get it in your bar module, even if someone else publish a new revision of foo in the shared repository (this revision not having the new method you are currently adding).

But be careful, when you have finished your development and publish it on the shared you will have to clean your local repository to benefit from new versions published in the shared repository.

Note also that modules found in the local repository must be complete, i.e. they must provide both a module descriptor and the published artifacts.

Shared

As its name suggest, the shared repository is aimed to be shared among a whole development team. It is a place where you can publish your team private modules for instance, and it's also a place where you can put modules not available in the public repository (sun jars, for instance), or simply not accurate (bad or incomplete module descriptors for instance).

Note that modules can be split across the shared repository and the public one: you can have the module descritor in the shared repository and the artifacts in the public one, for instance.

Public

The public repository is the place where most modules can be found, but which sometimes lack the information you need. It's usually a repository available through an internet connection only, even if this is not mandatory.

Setting up the repositories

Now that we have seen the objective of each of the three repositories, let's see how they are setup and how to configure them to fit your needs.

First, several repositories uses the same root in your filesystem. Referenced as ${ivy.default.ivy.user.dir}, this is by default the directory .ivy in your user home.

Note that several things can be done by setting ivy variable. To set them without defining your own ivyconf.xml file, you can:

  • set an ant property before any call to ivy in your build file if you use ivy from ant
  • set an environment variable if you use ivy from the command line

For instance:

<target name="resolve">
  <property name="ivy.default.ivy.user.dir" value="/path/to/ivy/user/dir"/>
  <ivy:resolve />
</target>

Now we will show how to override default values for the different kind of repositories, note that you can find what are these default values below in the detail of the default configuration.

Local

By default, the local repository lies in ${ivy.default.ivy.user.dir}/local. This is usually a good place, but you may want to modify it however. No problem, you just have to set the following ivy variable to the directory you want to use: ivy.local.default.root. For instance:
ivy.local.default.root=/opt/ivy/repository/local.

If you already have something you would like to use as your local repository, you may also want to modify the layout of this repository. Once again, two variables are available for that:
ivy.local.default.ivy.pattern gives the pattern to find ivy files
ivy.local.default.artifact.pattern gives the pattern to find artifacts
For example:

ivy.local.default.root=/opt/ivy/repository/local
ivy.local.default.ivy.pattern=[module]/[revision]/ivy.xml
ivy.local.default.artifact.pattern=[module]/[revision]/[artifact].[ext]

Shared

By default, the shared repository lies in ${ivy.default.ivy.user.dir}/shared. This is fine if you work alone, but the shared repository is supposed to be, mmm, shared ! So changing this directory is often required, and it is usually modified to point to a shared directory. You can use ivy.shared.default.root variable to specify in a new directory. Moreover, you can also configure the layout with variables similar to the one for the local repository:
ivy.shared.default.ivy.pattern gives the pattern to find ivy files
ivy.shared.default.artifact.pattern gives the pattern to find artifacts
For example:

ivy.shared.default.root=/opt/ivy/repository/shared
ivy.shared.default.ivy.pattern=[organisation]/[module]/[revision]/ivy.xml
ivy.shared.default.artifact.pattern=[organisation]/[module]/[revision]/[artifact].[ext]

Public

By default, the public repository is ivyrep. To change the setting of this resolver, you can use the standard way to configure ivyrep:
ivy.ivyrep.default.ivy.root specify the root for ivy files
ivy.ivyrep.default.ivy.pattern specify the layout for ivy files
ivy.ivyrep.default.artifact.root specify the root for artifacts
ivy.ivyrep.default.artifact.pattern specify the layout for artifacts
For instance:

ivy.ivyrep.default.ivy.root=http://myserver/ivy/
ivy.ivyrep.default.artifact.root=http://myserver/ivy/

Going further

OK, so we have seen how to easily change the settings of the three main repositories. But what if I want my shared repository is on a web server ? What if the public repository is not compatible with ivyrep ? What if ...

Everything can be changed in the default configuration, for sure, you can even do your own configuration. But you can also benefit from a part of the default configuration without writing a complete one.

But before explaining how, you will need to have a quick overview of how ivy is configured by default.

By default, ivy is configured using an ivyconf.xml which is packaged in the ivy jar. Here is this ivyconf file:

<ivyconf>
  <conf defaultResolver="default"/>
  <include url="${ivy.default.conf.dir}/ivyconf-public.xml"/>
  <include url="${ivy.default.conf.dir}/ivyconf-shared.xml"/>
  <include url="${ivy.default.conf.dir}/ivyconf-local.xml"/>
  <include url="${ivy.default.conf.dir}/ivyconf-main-chain.xml"/>
  <include url="${ivy.default.conf.dir}/ivyconf-default-chain.xml"/>
</ivyconf>

OK, so not much info here, except a lot of inclusions. These inclusions have been done on purpose so that you can easily change only one part of the ivyconf and benefit of the rest easily. For example, if you want to define your own public resolver, you will just have to configure ivy with an ivyconf like that:

<ivyconf>
  <conf defaultResolver="default"/>
  <include url="http://myserver/ivy/myivyconf-public.xml"/>
  <include url="${ivy.default.conf.dir}/ivyconf-shared.xml"/>
  <include url="${ivy.default.conf.dir}/ivyconf-local.xml"/>
  <include url="${ivy.default.conf.dir}/ivyconf-main-chain.xml"/>
  <include url="${ivy.default.conf.dir}/ivyconf-default-chain.xml"/>
</ivyconf>

Note that only the ivyconf-public inclusion has changed to include a home made public resolver. Note also that this can be used like that thanks to the fact that ${ivy.default.conf.dir} is a variable which is always set to the place where ivy default configuration files are (i.e. packaged in the jar).
To finish this example, you for sure have to write your own ivyconf file for defining your own public resolver. For instance:

<ivyconf>
  <resolvers>
    <filesystem name="public">
      <ivy pattern="/path/to/my/public/rep/[organisation]/[module]/ivy-[revision].xml" />
      <artifact pattern="/path/to/my/public/rep/[organisation]/[module]/[artifact]-[revision].[ext]" />
    </filesystem>
  </resolvers>
</ivyconf>

No the last thing you will need in order to properly take advantage of the default configuration is the content of each included ivyconf file:
ivyconf-public.xml

<ivyconf>
  <resolvers>
    <ivyrep name="public"/>
  </resolvers>
</ivyconf>

ivyconf-shared.xml

<ivyconf>
  <property name="ivy.shared.default.root"            value="${ivy.default.ivy.user.dir}/shared" override="false"/>
  <property name="ivy.shared.default.ivy.pattern"      value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/>
  <property name="ivy.shared.default.artifact.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/>
  <resolvers>
    <filesystem name="shared">
      <ivy pattern="${ivy.shared.default.root}/${ivy.shared.default.ivy.pattern}" />
      <artifact pattern="${ivy.shared.default.root}/${ivy.shared.default.artifact.pattern}" />
    </filesystem>
  </resolvers>
</ivyconf>

ivyconf-local.xml

<ivyconf>
  <property name="ivy.local.default.root"            value="${ivy.default.ivy.user.dir}/local" override="false"/>
  <property name="ivy.local.default.ivy.pattern"      value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/>
  <property name="ivy.local.default.artifact.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/>
  <resolvers>
    <filesystem name="local">
      <ivy pattern="${ivy.local.default.root}/${ivy.local.default.ivy.pattern}" />
      <artifact pattern="${ivy.local.default.root}/${ivy.local.default.artifact.pattern}" />
    </filesystem>
  </resolvers>
</ivyconf>

ivyconf-main-chain.xml

<ivyconf>
  <resolvers>
    <chain name="main" dual="true">
      <resolver ref="shared"/>
      <resolver ref="public"/>
    </chain>
  </resolvers>
</ivyconf>

ivyconf-default-chain.xml

<ivyconf>
  <resolvers>
    <chain name="default" returnFirst="true">
      <resolver ref="local"/>
      <resolver ref="main"/>
    </chain>
  </resolvers>
</ivyconf>

Here you are, you have enough clues to configure that the way you want... check the configuration documentation to see if what you want to do is possible, and go ahead !

Multiple Resolvers

This example is an illustration of how artefacts can be retreived by multiple resolvers. Using multiple resolvers is very important when using continous integration. Indeed, in such environements, you can use multiple repositories and so multiple resolvers to retreive both released versions of projects than continous integrated versions produced for example with cruise-control. In our example, we will just show how to use two resolvers, one on a local repository and one using ibiblio repository.

project description

the project : chained-resolvers

The project is very simple and contains only one test class : example.Hello
It depends on two libraries apache commons-lang and a little test library (sources are included in jar file). The test library is used by the project to uppercase a string, and commons-lang is used to capitalize the same string.

Here is the content of the project:

  • build.xml : the ant build file for the project
  • ivy.xml : the ivy project file
  • src\example\Hello.java : the only class of the project

Take a look at it's ivy.xml file :

<ivy-module version="1.0">
    <info organisation="jayasoft" module="chained-resolvers" />
    <dependencies>
        <dependency org="apache" name="commons-lang" rev="2.0" />
        <dependency name="test" rev="1.0" />
    </dependencies>
</ivy-module>

As we expect, the ivy file declares to be dependent on the two libraries that the project use : apache commons-lang.jar and test.jar.

the ivy configuration

The ivy configuration is made in the config directory it contains only one file: ivyconf.xml.

Let's analyse it.

<ivyconf>
  <conf defaultResolver="chain-example" />
  <resolvers>
    <chain name="chain-example">
      <filesystem name="libraries">
        <artifact pattern="${ivy.conf.dir}/repository/[artifact]-[revision].[type]" />
      </filesystem>
      <ibiblio name="ibiblio" />
    </chain>
  </resolvers>
</ivyconf>

the conf tag

This tag initializes ivy with some parameters. Here only one is used, the name of the resolver to use by default.

the resolvers tag

Under this tag, we can find the description of the resolvers that ivy will use. In our example, we have only one resolver, called "chain-example", which is quite special as it defines a list (a chain) of resolvers.
The resolvers put in the chain are :

  • libraries : it is a file resolver. This one is configured to look for artefacts in the "repository" sub directory of the directory that contains the ivyconf.xml file.
  • ibiblio : this resolver is a special one. It looks in the ibiblio maven repository to retreive the libraries.

walkthrough

step 1 : preparation

Open a DOS or shell window, and go to the "chained-resolvers" directory.

step 2 : clean directory tree

On the prompt type : ant

This will clean up the entire project directory tree and ivy cache. You can do it each time you want to clean up this example.

step 3 : run the project

Goto chainedresolvers-project directory. And simply run ant.

I:\chained-resolvers\chainedresolvers-project>ant
Buildfile: build.xml

configure:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::

resolve:
:: resolving dependencies :: jayasoft/chained-resolvers-working@xmen
        confs: [default]
downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-2.0.jar(2.0) ...
.................................... (165kB)
        [SUCCESSFUL ] apache/commons-lang-2.0/commons-lang.jar[jar] (5390ms)
downloading file:/I:/chained-resolvers/config/repository/test-1.0.jar(1.0) ...
. (1kB)
        [SUCCESSFUL ] jayasoft/test-1.0/test.jar[jar] (16ms)
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   2   |   2   |   0   |   0   ||   2   |   2   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/chained-resolvers
        confs: [default]
        2 artifacts copied, 0 already retrieved

run:
    [mkdir] Created dir: I:\chained-resolvers\chainedresolvers-project\build
    [javac] Compiling 1 source file to I:\chained-resolvers\chainedresolvers-project\build
     [java] standard message :example world !
     [java] capitalized by org.apache.commons.lang.WordUtils : Example World !
     [java] upperCased by test.StringUtils : EXAMPLE WORLD !

BUILD SUCCESSFUL
Total time: 9 seconds

We can see in the log of the resolve task, that the two dependencies have been retrieved (2 artifacts) and copied to the ivy cache directory (2 downloaded). The run target succeed in using both commons-lang.jar comming from ibiblio repository and test.jar comming from the local repository.

Dual Resolver

This tutorial presents the use of the DualResolver, a feature introduced in the version 0.6 of Ivy.

Dual Resolver is used when ivy files can be found in a repository while artifacts are in another. It is especially useful to use full power of ivy (including transitive dependencies) with the ibiblio repository for artifacts. The problem with the maven ibiblio repository is that it does not contain ivy files. Since transitive dependencies are based upon ivy files, using the ibiblio resolver does not permit to use transitive dependencies.

The solution to this problem is to store your own repository only for ivy files, and use ibiblio for artifacts. That's what is done in this tutorial.

project description

Let's have a look at the src/example/dual directory in your ivy distribution.
It contains a build file and 3 directories:

  • config: contains the ivy configuration file
  • repository: a sample repository of ivy files
  • project: the project making use of ivy with dual resolver

the dual project

The project is very simple and contains only one test class : example.Hello
It depends on two libraries: apache commons-lang and apache commons-httpclient.

Here is the content of the project :

  • build.xml : the ant build file for the project
  • ivy.xml : the ivy project file
  • src\example\Hello.java : the only class of the project

Take a look at it's ivy.xml file:

<ivy-module version="1.0">
    <info organisation="jayasoft" module="hello-ivy" />
    <dependencies>
        <dependency org="apache" name="commons-httpclient" rev="2.0.2" />
        <dependency org="apache" name="commons-lang" rev="2.0" />
    </dependencies>
</ivy-module>

As you can see, nothing special here... Indeed, it's the philosophy of ivy to keep ivy files independent of the way dependencies are retrieved.

the ivy configuration

The ivy configuration is made in the config directory it contains only one file: ivyconf.xml.

Let's analyse it.

<ivyconf>
  <conf defaultResolver="dual-example" />
  <resolvers>
    <dual name="dual-example">
      <filesystem name="ivys">
        <ivy pattern="${ivy.conf.dir}/../repository/[module]-ivy-[revision].xml" />
      </filesystem>
      <ibiblio name="ibiblio" />
    </dual>
  </resolvers>
</ivyconf>

Here we configure one resolver, the default one, which is a dual resolver. This dual resolver has two sub resolvers : the first is what is called the "ivy" resolver of the dual resolver, and the second one is what is called the "artifact" resolver. It is important that the dual resolver exactly has two sub resolvers in this given order.
The ivy resolver, here a filesystem one, is used only to find ivy files. The configuration given in this resolver
says that all ivy files are in the same directory, named like that: [module]-ivy-[revision].xml. If we check the repository directory, we can confirm that it contains a file named commons-httpclient-ivy-2.0.2.xml. It fulfills the given pattern and will thus be find by this resolver.
The artifact resolver is simply an ibiblio one, and will thus try to find required artifacts in the maven ibiblio repository.

walkthrough

step 1 : preparation

Open a DOS or shell window, and go to the "dual" directory.

step 2 : clean up

On the prompt type : ant

This will clean up the entire project directory tree (compiled classes and retrieved libs) and ivy cache.
You can do it each time you want to clean up this example.

step 3 : run the project

Goto project directory. And simply run ant.

I:\dual\project>ant
Buildfile: build.xml

configure:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::

resolve:
:: resolving dependencies :: jayasoft/hello-ivy-working@xmen
        confs: [default]
downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-2.0.jar(2.0) ...
.....
.........
..........
...........
. (165kB)
        [SUCCESSFUL ] apache/commons-lang-2.0/commons-lang.jar[jar] (8032ms)
downloading http://www.ibiblio.org/maven/commons-httpclient/jars/commons-httpclient-2.0.2.jar(2.0.2) ...
...........
......
....
..........
............
........ (220kB)
        [SUCCESSFUL ] apache/commons-httpclient-2.0.2/commons-httpclient.jar[jar] (10031ms)
downloading http://www.ibiblio.org/maven/commons-logging/jars/commons-logging-1.0.4.jar(1.0.4) ...
......... (37kB)
        [SUCCESSFUL ] apache/commons-logging-1.0.4/commons-logging.jar[jar] (1469ms)
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   3   |   3   |   1   |   0   ||   3   |   3   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/hello-ivy
        confs: [default]
        3 artifacts copied, 0 already retrieved

run:
    [mkdir] Created dir: I:\dual\project\build
    [javac] Compiling 1 source file to I:\dual\project\build
     [java] standard message : hello ivy !
     [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !
     [java] head status code with httpclient: 200
     [java] now check if httpclient dependency on commons-logging has been realized
     [java] found logging class in classpath: interface org.apache.commons.logging.Log

BUILD SUCCESSFUL
Total time: 24 seconds



As you can see, ivy not only downloaded commons-lang and commons-httpclient, but also commons-logging. Indeed, commons-logging is a dependency of httpclient, as we can see in the httpclient ivy file found in the repository directory:

<ivy-module version="1.0">
    <info organisation="apache" module="commons-httpclient" revision="2.0.2" status="release" publication="20041010174300" />
    <dependencies>
        <dependency name="commons-logging" rev="1.0.4" conf="default" />
    </dependencies>
</ivy-module>



So everything worked well, ivy file has been found in the repository directory and artifacts have been downloaded from ibiblio. You now just have to write ivy files for the module you often use, and they will be much easier to use... And imagine a world in which each module delivers also an ivy file. Since it is independent of the way to retrieve dependencies, it would made all dependencies handling much easier, wouldn't it ?

Project dependencies

This example is an illustration of dependency between two project.

The dependant project declares that it uses the standalone one. We will illustrate two things :

  • public libraries declared by standalone project will automatically be recovered by the dependant project
  • the dependant project will retrieve the "latest" version of the standalone project

the projects used

the project : standalone

The standalone project is very simple. It depends on the apache library commons-lang and contains only one class: standalone.Main which provides two services:

  • return the version of the project
  • capitalize a string using org.apache.commons.lang.WordUtils.capitalizeFully

Here is the content of the project:

  • build.xml : the ant build file for the project
  • ivy.xml : the ivy project file
  • src\standalone\Main.java : the only class of the project

Take a look at it's ivy.xml file:

<ivy-module version="1.0">
    <info organisation="jayasoft" module="standalone" />
    <dependencies>
        <dependency org="apache" name="commons-lang" rev="2.0" />
    </dependencies>
</ivy-module>

The ivy dependency file declares only one dependency on apache commons-lang library which by default is a public dependency (see ivy file definition).

the project : depending

The project depending is very simple too. It declares only one dependency on the latest version of the standalone project and it contains only one class depending.Main which make 2 things:

  • getting the version of the standalone project throw a call to standalone.Main.getVersion()
  • transform a string throw a call to standalone.Main.capitalizeWords(str)

Take a look at it's ivy.xml file:

<ivy-module version="1.0">
    <info organisation="jayasoft" module="depending" />
    <dependencies>
        <dependency name="standalone" rev="latest.integration" />
    </dependencies>
</ivy-module>

the ivy configuration

The ivy configuration is made in the config directory wich contains 2 files :

  • ivyconf.properties : a property file
  • ivyconf.xml : the file containing the ivy configuration

Let's analyse the ivyconf.xml file.

<ivyconf>
        <properties file="${ivy.conf.dir}/ivyconf.properties" />
        <conf defaultCache="${ivy.conf.dir}/ivy-cache" defaultResolver="libraries" />
        <resolvers>
                <filesystem name="projects">
                        <artifact pattern="${repository.dir}/[artifact]-[revision].[ext]" />
                        <ivy pattern="${repository.dir}/[module]-[revision].xml" />
                </filesystem>
                <ivyrep name="libraries" />
        </resolvers>
        <modules>
                <module organisation="jayasoft" name=".*" resolver="projects" />
        </modules>
</ivyconf>

The file contains four main tags : properties, conf, resolvers and modules.

the properties tag

This tag only load some properties for the ivy process in the same manner as ant will do it.

the conf tag

This tag is in charge to initialize some parameters for ivy process. The directory that ivy will use to cache (to store) artifacts found will be in a sub directory called ivy-cache of the directory containing the ivyconf.xml file itself.
The second parameter, tells ivy to use a resolver called "libraries" as its default resolver. As a recall, a resolver is in charge to resolve an artifact from some information like : the organisation that provides the artifact, the name of the library and the version of the library. More information can be found in the configuration documentation.

the resolvers tag

This tag defines the resolvers to use. Here we have two resolvers defined: "projects" and "libraries".
The filesystem resolver called "projects" is able to resolve the internal dependencies wanted.
The ivyrep resolver called "libraries" is able to find dependencies on ivyrep.

the modules tag

The modules tag allows to configure which resolver should be use for which module. Here the configuration only tells to use the "projects" resolver for all modules having for organisation "jayasoft" and any module name (.* regexp matches any module name).
For other modules (i.e. all modules not from jayasoft), since there is no special configuration, the default resolver will be used: "libraries".

walkthrough

step 1 : preparation

Open a DOS or shell window, and go to the "dependance" directory.

step 2 : clean directory tree

On the prompt type : ant
This will clean up the entire project directory tree. You can do it each time you want to clean up this example.

step 3 : publication of standalone project

Goto standalone directory and publish the project

I:\standalone>ant publish
Buildfile: build.xml

configure:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::

resolve:
:: resolving dependencies :: jayasoft/standalone-working@xmen
        confs: [default]
downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-2.0.jar(2.0) ...
.................................... (165kB)
        [SUCCESSFUL ] apache/commons-lang-2.0/commons-lang.jar[jar] (6672ms)
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   1   |   1   |   0   |   0   ||   1   |   1   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/standalone
        confs: [default]
        1 artifacts copied, 0 already retrieved

compile:
    [mkdir] Created dir: I:\standalone\build\classes
    [javac] Compiling 1 source file to I:\standalone\build\classes

jar:
[propertyfile] Creating new property file: I:\standalone\build\classes\version.properties
      [jar] Building jar: I:\standalone\build\standalone.jar

publish:
:: delivering :: jayasoft/standalone-working@xmen :: 1 :: release :: Wed Apr 27 08:41:47 CEST 2005
        delivering ivy file to I:\standalone/build/ivy.xml
:: publishing :: jayasoft/standalone-working@xmen
        published standalone to I:\config\repository\standalone-1.jar
        published ivy to I:\config\repository\standalone-1.xml
     [echo] project standalone released with version 1

BUILD SUCCESSFUL
Total time: 10 seconds

What we see here:

  • the project depends on 1 library (1 artifact)
  • the library was not in the ivy cahe and so was downloaded (1 downloaded)
  • the project has been released under version number 1

To give more details on the publish, as you can see the call to the publish task has resulted in two main things:
- the delivery of a resolved ivy file to build/ivy.xml. This has been done because by default the publish task not only publishes artifacts but also ivy file. So it has looked to the path where the ivy file to publish should be, using the artifactspattern: ${build.dir}/[artifact].[ext].
For an ivy file, this resolves to build/ivy.xml. Because this file does not exist, it automatically make a call to the deliver task which delivers a resolved ivy file to this destination.
- the publication of artifact standalone and resolved ivy file to the repository. Both are mere copy of files found in the current project, more precisely in the build dir. This is because the artifactspattern has been set to ${build.dir}/[artifact].[ext], so standalone artifact is found in build/standalone.jar and ivy file in build/ivy.xml. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to repository\standalone-1.jar and to repository\standalone-1.xml, respecting the artifact and ivy patterns of our configuration (see above).

step 4 : running the depending project

Goto to directory depending and run ant

I:\depending>ant
Buildfile: build.xml

clean:

configure:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::

resolve:
:: resolving dependencies :: jayasoft/depending-working@xmen
        confs: [default]
        [1] jayasoft/standalone
downloading file:/I:/config/repository/standalone-1.jar(1) ...
. (1kB)
        [SUCCESSFUL ] jayasoft/standalone-1/standalone.jar[jar] (15ms)
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   2   |   2   |   2   |   0   ||   2   |   1   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/depending
        confs: [default]
        2 artifacts copied, 0 already retrieved

compile:
    [mkdir] Created dir: I:\depending\build\classes
    [javac] Compiling 1 source file to I:\depending\build\classes

run:
     [java] you are using version 1 of class standalone.Main
     [java] standard message : i am depending.Main and standalone.Main will do the job for me
     [java]     [standalone.Main] capitalizing string "i am depending.Main and standalone.Main will do the job for me" 
				     using org.apache.commons.lang.WordUtils
     [java] capitalized message : I Am Depending.main And Standalone.main Will Do The Job For Me

BUILD SUCCESSFUL
Total time: 3 seconds

What we see here :

  • the project depends on 2 libraries (2 artifacts)
  • one of the libraries was in the cache because there was only 1 download (1 downloaded)
  • ivy retreived the version 1 of the project standalone. The call to standalone.Main.getVersion() has returned 1. If you look in the depending/lib directory, you should see standalone-1.jar which is the artifact version 1 of the project standalone
  • the call to standalone.Main.capitalizeWords(str) succeed, what significate that the required library were in the classpath. If you look at the lib directory, you will see that the library commons-lang-2.0.jar was retreived. This library was declared to be used by the project "standalone", so ivy get it too for the dependant project.

step 5 : new version of standalone project

Like we did before in step 3, publish again the standalone project. This will result as a new version of the project.

I:\standalone>ant publish
Buildfile: build.xml

configure:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::

resolve:
:: resolving dependencies :: jayasoft/standalone-working@xmen
        confs: [default]
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   1   |   0   |   0   |   0   ||   1   |   0   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/standalone
        confs: [default]
        0 artifacts copied, 1 already retrieved

compile:

jar:
[propertyfile] Updating property file: I:\standalone\build\classes\version.properties
      [jar] Building jar: I:\standalone\build\standalone.jar

publish:
   [delete] Deleting: I:\standalone\build\ivy.xml
:: delivering :: jayasoft/standalone-working@xmen :: 2 :: release :: Wed Apr 27 09:17:13 CEST 2005
        delivering ivy file to I:\standalone/build/ivy.xml
:: publishing :: jayasoft/standalone-working@xmen
        published standalone to I:\config\repository\standalone-2.jar
        published ivy to I:\config\repository\standalone-2.xml
     [echo] project standalone released with version 2

BUILD SUCCESSFUL
Total time: 2 seconds

Now if you look in your repository folder, you must find 2 version published of the standalone project.
Let's look at it:

I:\dependence\standalone>dir ..\config\repository /w
 Le volume dans le lecteur I s'appelle DATA
 Le numéro de série du volume est 30E5-91BA

 Répertoire de I:\dependence\config\repository

[.]                [..]               standalone-1.jar   standalone-1.xml   standalone-2.jar   standalone-2.xml
               4 fichier(s)            3 936 octets
               2 Rép(s)   9 874 350 080 octets libres

I:\dependence\standalone>

Ok now our repository contains two versions of the project standalone, other projects can refer to both versions.

step 6 : depending got the new version

What do we expect about running again the depending project? Two major things are expected:

  • retrieve the version 2 as the latest.integration version of the standalone project
  • running the test must display version 2 of standalone project

Let's go!!!

I:\depending>ant
Buildfile: build.xml

clean:
   [delete] Deleting 3 files from I:\depending
   [delete] Deleted 4 directories from I:\depending

configure:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::

resolve:
:: resolving dependencies :: jayasoft/depending-working@xmen
        confs: [default]
        [2] jayasoft/standalone
downloading file:/I:/config/repository/standalone-2.jar(2) ...
. (1kB)
        [SUCCESSFUL ] jayasoft/standalone-2/standalone.jar[jar] (0ms)
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   2   |   2   |   2   |   0   ||   2   |   1   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/depending
        confs: [default]
        2 artifacts copied, 0 already retrieved

compile:
    [mkdir] Created dir: I:\depending\build\classes
    [javac] Compiling 1 source file to I:\depending\build\classes

run:
     [java] you are using version 2 of class standalone.Main
     [java] standard message : i am depending.Main and standalone.Main will do the job for me
     [java]     [standalone.Main] capitalizing string "i am depending.Main and standalone.Main will do the job for me" 
			     using org.apache.commons.lang.WordUtils
     [java] capitalized message : I Am Depending.main And Standalone.main Will Do The Job For Me

BUILD SUCCESSFUL
Total time: 3 seconds

Ok we have the result expected as the run target shows that we are using the version 2 of the main class of standalone project. If we take a look at the resolve target results, we can see that one artifact has been downloaded to the ivy cache. In fact this file is the version 2 of the standalone project that was taken from the repository, you can now retrieve it in the ivy-cache directory.

Using Ivy in multiple projects environment

Warning: tutorial in progress !

In the previous tutorial you have seen how to deal with dependencies between two simple projects.

This tutorial will guide you through the use of ivy in a more complete environment. All the sources of this tutorial are available in src/example/multi-project in ivy distribution (warning: the sources attached with ivy 1.3 contain an error in the common.xml file. Please use either latest build to find proper example sources or replace the common.xml file with this one).

Context

Here is a 10000ft overview of the projects involved in this tutorial:

  • version
  • helps to identify module by a version

  • list
  • gives a list of files in a directory (recursively)

  • size
  • gives the total size of all files in a directory, or of a collection of files

  • find
  • find files in a given dir or among a list of files which match a given name

  • sizewhere
  • gives the total size of files matching a name in a directory

  • console
  • give access to all other modules features through a simple console app

For sure this is not aimed to demonstrate how to develop a complex app or give indication of advanced algorithm :-)

But this gives a simple understanding of how ivy can be used to develop an application divided in multitple modules.

Now, here is how these modules relate to each other:
dependencies graph

click to enlarge

Modules in yellow are the modules described in this tutorial, and modules in blue are external dependencies (we will see how to generate this graph later in this tutorial).

As you can see, we have here a pretty interesting set of modules with dependencies between each other, each depending on the latest version of the others.

The example files

The sources for this tutorial can be found in src/example/multi-project in the ivy distribution. In this directory, you will find the following files:

  • build.xml
  • This a root build file which can be used to call targets on all modules, in the order of their dependencies (ensuring that a module is always built before any module depending on it, for instance)

  • common
    • common.xml
    • the common build file imported by all build.xml files for each project. This build defines the targets which can be used in all projects.

    • build.properties
    • some properties common to all projects

  • projects
  • contains a directory per module, with for each

    • ivy.xml
    • Ivy file of the module, describing its dependencies upon other modules and / or external modules.
      Example:

      <ivy-module version="1.0">
          <info
              organisation="jayasoft"
              module="find"
              status="integration"/>
          <configurations>
            <conf name="core"/>
            <conf name="standalone" extends="core"/>
          </configurations>
          <publications>
            <artifact name="find" type="jar" conf="core" />
          </publications>
          <dependencies>
            <dependency name="version" rev="latest.integration" conf="core->default" />
            <dependency name="list" rev="latest.integration" conf="core" />
            <dependency org="apache" name="commons-collections" rev="3.1" conf="core->default" />
            <dependency org="apache" name="commons-cli" rev="1.0" conf="standalone->default" />
          </dependencies>
      </ivy-module>
    • build.xml
    • The build file of the project, which consists mainly in an import of the common build file and of a module specific properties file:

      <project name="find" default="compile">
      <property file="build.properties"/>

      <import file="${common.dir}/common.xml"/>
      </project>

    • build.properties
    • Module specific properties + properties to find the common build file

      projects.dir = ${basedir}/..
      wkspace.dir = ${projects.dir}/..
      common.dir = ${wkspace.dir}/common
    • src
    • the source directory with all java sources

Note that this doesn't demonstrate good practice for software development in general, in particular you won't find any unit test in this samples, even if we think unit testing is very important. But this isn't the aim of this tutorial.

Now that you are a bit more familiar with the structure, let's have a look at the most important part of this example: the common build file. Indeed, as you have seen all modules build files only import the common build file, and defines their dependencies in their ivy files (with which you should begin to be familiar).

So, here are some aspects of this common build file:

ivy configuration

<target name="configure">
    <!-- setup ivy default configuration with some custom info -->
    <property name="ivy.local.default.root" value="${repository.dir}/local"/>
    <property name="ivy.shared.default.root" value="${repository.dir}/shared"/>

    <!-- here is how we would have configured ivy if we had our own ivyconf file
        <ivy:configure file="${common.dir}/ivyconf.xml" />
    -->
</target>

This target configures ivy only by setting two properties: the location for the local repository and the location for the shared repository. It's the only configuration done here, since ivy 1.3 is configured by default to work in a team environment (see default configuration tutorial for details about this). For sure in a real environment the shared repository location would rather be in a team shared directory (or in a more complex repository, again see the default configuration tutorial to see how to use something really different).
This target only indicates in comments how the configuration would have been done if the default configuration wasn't ok for our purpose.

resolve dependencies

<target name="resolve" depends="configure, clean-lib" description="--> retrieve dependencies with ivy">
    <mkdir dir="${lib.dir}"/> <!-- not usually necessary, ivy creates the directory IF there are dependencies -->
    <!-- this target is named resolve even if we do a retrieve:
        in fact a resolve will be called, and then the retrieve will simply copy files in the lib directory -->
    <ivy:retrieve pattern="${lib.dir}/[artifact].[ext]" />
</target>

Here we see that we only call a retrieve task, the resolve being done automatically with default parameters (which are ok in our case). So here nothing special, we simply use ivy to retrieve dependencies in the lib directory, putting artifacts without revision in their names (it's easier to use with an ide, for instance).

publish

<target name="publish" depends="clean-build, new-version, jar" description="--> publish this project in the ivy repository">
    <property name="revision" value="${version}"/>
    <ivy:publish artifactspattern="${build.dir}/[artifact].[ext]"
        resolver="shared"
        pubrevision="${revision}"
        status="release"
    />
    <echo message="project ${ant.project.name} released with version ${revision}" />
</target>

This target let publish the module in the shared repository, with the revision found in the version property, which is set by other targets. It can be used when a module reaches a specific milestone, or whenever you want the teeam to benefit from a new version of the module.

publish-local

<target name="publish-local" depends="local-version, jar" description="--> publish this project in the local ivy repository">
    <delete file="${build.dir}/ivy.xml"/> <!-- delete last produced ivy file to be sure a new one will be generated -->
    <ivy:publish artifactspattern="${build.dir}/[artifact].[ext]"
        resolver="local"
        pubrevision="${revision}"
        pubdate="${now}"
        status="integration"
    />
    <echo message="project ${ant.project.name} published locally with version ${revision}" />
</target>

This is very similar to the publish task, except that this publish the revision in the local repository, which is used only in your environment and doesn't disturb the team. When you change something in a module and want to benefit from the change in another one, you can simply call publish-local in this module, and then your next build of the other module will automatically get this local version.

clean-local

<target name="clean-local" depends="configure" description="cleans the local repository for the current module">
    <delete dir="${ivy.local.default.root}/${ant.project.name}"/>
</target>

This target is used when you don't want to use your local version of a module anymore, for example when you release a new version to the whole team.

report

<target name="report" depends="resolve" description="--> generates a report of dependencies">
    <ivy:report todir="${build.dir}"/>
</target>

Generates both an html report and a graphml report.

For example, to generate a graph like the one shown at the beginning of this tutorial, you just have to follow the instructions given here with the graphml file you will find in projects/console/build/ after having called report in the console project, and that's it, you have a clear overview of all your app dependencies !

Using Ivy Configurations

This tutorial introduces the use of configuration in ivy files. Ivy configurations is indeed a very important concept. Someone even told me one day that using Ivy without using configurations is like eating a good cheese without touching the glass of Chateau Margaux 1976 you have just aside :-)

More seriously, configurations in ivy can be better understood as views on your module, and you will see how they can be used efficiently here.

Reference documentation on configurations can be find here and here.

Introduction

Source code available in src/example/configurations/multi-projects.
We have two projects :
- a library that define an api to filter String array and two implementations of this api.
- a very small app that use this library.

The library produces 3 artifacts:
- the api jar,
- an implementation jar with no external dependency,
- an other implementation that needs commons-collection to perform.

The application only need api to compile and can use any of the two implementation at runtime.

The library project

The first project we defined in this tutorial is the filter-framework.
In order to have a fine grained artifacts publication definition, we defined configurations to map usage other can make of our library.

The ivy.xml file

<ivy-module version="1.3">
    <info organisation="jayasoft" module="filter-framework"/>
    <configurations>
    <conf name="api"  description="only provide filter framework API"/>
      <conf name="homemade-impl" extends="api" description="provide a home made implementation of our api"/>
      <conf name="cc-impl" extends="api" description="provide an implementation that use apache common collection framework"/>
      <conf name="test" extends="cc-impl" visibility="private" description="for testing our framework"/>
    </configurations>
    <publications>
      <artifact name="filter-api" type="jar"  conf="api" ext="jar"/>
      <artifact name="filter-hmimpl" type="jar"  conf="homemade-impl" ext="jar"/>
      <artifact name="filter-ccimpl" type="jar"  conf="cc-impl" ext="jar"/>     
    </publications>
    <dependencies>
        <dependency org="apache" name="commons-collections" rev="3.1" conf="cc-impl->default"/>
        <dependency org="junit" name="junit" rev="3.8" conf="test->default"/>
    </dependencies>
</ivy-module>

Explanation

As you can see we defined 3 public configurations and a private one (defined junit dependency for testing).
The 2 implementations conf homemade-impl, cc-impl extends api configuration so artifacts defined in api will also be required in its extending conf.
In the publications tag we defined the artifacts we produce (here it's jars) and we affect them a configuration.
Later when others will use our library they will have a very flexible way to defined what they need.

See it in action

The library project is build using ant. Open a shell in the root directory of the project and type ant.

Buildfile: build.xml
clean:
resolve:
:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
no configuration file found, using default...
:: configuring :: url = jar:file:/C:/dev/ant/apache-ant-1.6.2/lib/ivy-20060123130642.jar!/fr/jayasoft/ivy/conf/ivyconf.xml
:: resolving dependencies :: [ jayasoft | filter-framework | working@SPIDER ]
        confs: [api, homemade-impl, cc-impl, test]
        found [ apache | commons-collections | 3.1 ] in main
        found [ junit | junit | 3.8 ] in main
downloading http://www.ibiblio.org/maven/commons-collections/jars/commons-collection... ................(546kB)
        [SUCCESSFUL ] [ apache | commons-collections | 3.1 ]/commons-collections.jar[jar] (34320ms)
downloading http://www.ibiblio.org/maven/junit/jars/junit-3.8.jar ........................... (118kB)
        [SUCCESSFUL ] [ junit | junit | 3.8 ]/junit.jar[jar] (8462ms)
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |        api       |   0   |   0   |   0   |   0   ||   0   |   0   |
        |   homemade-impl  |   0   |   0   |   0   |   0   ||   0   |   0   |
        |      cc-impl     |   1   |   1   |   1   |   0   ||   1   |   1   |
        |       test       |   2   |   2   |   1   |   0   ||   2   |   2   |
        ---------------------------------------------------------------------
:: retrieving :: [ jayasoft | filter-framework ]
        confs: [api, homemade-impl, cc-impl, test]
        3 artifacts copied, 0 already retrieved

build:
    [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build
    [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\distrib
    [javac] Compiling 4 source files to D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build
      [jar] Building jar: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\distrib\filter-api.jar
      [jar] Building jar: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\distrib\filter-hmimpl.jar
      [jar] Building jar: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\distrib\filter-ccimpl.jar

test:
    [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build\test-report
    [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build\test-classes
    [javac] Compiling 3 source files to D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build\test-classes
    [junit] Running filter.ccimpl.CCFilterTest
    [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0.02 sec
    [junit] Running filter.hmimpl.HMFilterTest
    [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0.01 sec

publish:
:: delivering :: [ jayasoft | filter-framework | working@SPIDER ] :: 1.3 :: release :: Tue Jan 24 10:53:41 CET 2006
        delivering ivy file to distrib/ivy.xml
:: publishing :: [ jayasoft | filter-framework | working@SPIDER ]
        published filter-api to D:\users\mm\.ivy/local/jayasoft/filter-framework/1.3/jars/filter-api.jar
        published filter-ccimpl to D:\users\mm\.ivy/local/jayasoft/filter-framework/1.3/jars/filter-ccimpl.jar
        published filter-hmimpl to D:\users\mm\.ivy/local/jayasoft/filter-framework/1.3/jars/filter-hmimpl.jar
        published ivy to D:\users\mm\.ivy/local/jayasoft/filter-framework/1.3/ivys/ivy.xml
     [echo] project filter-framework released with version 1.3

BUILD SUCCESSFUL

The ant's default target is publish.
This target use ivy to publish our library binaries in a local repository.
As we do not specify any repository path the default one is use. ({home.dir}/.ivy/local/jayasoft/filter-framework/)
Now we are ready to use our library.

The application project

Now that we have shipped our fantastic library, we want to use it!
The tutorial comes with a sample application called myapp. You will find it in the tutorial folder.

The ivy.xml file

<ivy-module version="1.3">
    <info organisation="jayasoft" module="myapp"/>
 
    <configurations>
      <conf name="build" visibility="private" description="compilation only need api jar" />
      <conf name="noexternaljar" description="use only company jar" />
      <conf name="withexternaljar" description="use company jar and third party jars" />   
    </configurations>
   
    <dependencies>
        <dependency org="jayasoft" name="filter-framework" rev="latest.integration" conf="build->api; noexternaljar->homemade-impl; withexternaljar->cc-impl"/>
    </dependencies>
</ivy-module>

Explanation

We create 3 configurations that define the way we want to use the application.
The build configuration, (as said before) only need api to compile.
The other configuration are defined for runtime.
One configuration will only use "home-made" jars, and the second one will use external jars.

We also defined a dependency on the previous library.
In the dependency we use configuration mapping to match ours and library configurations.
You can found more information on configuration mapping here

  1. build->api : here we tell ivy that our build configuration depends on the api configuration of the dependcy
  2. noexternaljar->homemade-impl : here we tell ivy that our noexternaljar configuration depends on the homemade-impl configuration of the dependcy.
  3. withexternaljar->cc-impl : here we tell ivy that our withexternaljar configuration depends on the cc-impl configuration of the dependcy

Note that we never declares any of the dependency artifacts we need in each configuration: it's the dependency module file which declares the published artifacts and which should be used in each configuration.

In the ant buld.xml file we defined a resolve target as follow:

<target name="resolve" description="--> retreive dependencies with ivy">
<ivy:retrieve pattern="${ivy.lib.dir}/[conf]/[artifact].[ext]"/>
</target>

When we call this target, Ivy will do a resolve using our ivy.xml file in the root folder and will after do retrieve putting all the artifacts in folder for each configuration. Here is how your lib directory should look like after a call to this target:

 Répertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib

01/24/2006  11:19 AM              build
01/24/2006  11:19 AM              noexternaljar
01/24/2006  11:19 AM              withexternaljar
               0 fichier(s)                0 octets

 Répertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib\build

01/24/2006  10:53 AM             1,174 filter-api.jar
               1 fichier(s)            1,174 octets

 Répertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib\noexternaljar

01/24/2006  10:53 AM             1,174 filter-api.jar
01/24/2006  10:53 AM             1,030 filter-hmimpl.jar
               2 fichier(s)            2,204 octets

 Répertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib\withexternaljar
01/24/2006  10:53 AM           559,366 commons-collections.jar
01/24/2006  10:53 AM             1,174 filter-api.jar
01/24/2006  10:53 AM             1,626 filter-ccimpl.jar
               3 fichier(s)          562,166 octets

As you can see for each configuration we have now a set of jars.

Let's try to launch our app.

See it in action

Use ant to run the application.
Default ant target is run-cc and will launch application using common collection jar.

Buildfile: build.xml

resolve:
:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
no configuration file found, using default...
:: configuring :: url = jar:file:/C:/dev/ant/apache-ant-1.6.2/lib/ivy-20060123130642.jar!/fr/jayasoft/ivy/conf/ivyconf.xml
:: resolving dependencies :: [ jayasoft | myapp | working@SPIDER ]
        confs: [build, noexternaljar, withexternaljar]
        found [ jayasoft | filter-framework | 1.3 ] in local
        [1.3] [ jayasoft | filter-framework | latest.integration ]
        found [ apache | commons-collections | 3.1 ] in default
downloading D:\users\mm\.ivy\local\jayasoft\filter-framework\1.3\jars\filter-ccimpl.jar .... (1kB)
        [SUCCESSFUL ] [ jayasoft | filter-framework | 1.3 ]/filter-ccimpl.jar[jar] (0ms)
downloading D:\users\mm\.ivy\local\jayasoft\filter-framework\1.3\jars\filter-api.jar .... (1kB)
        [SUCCESSFUL ] [ jayasoft | filter-framework | 1.3 ]/filter-api.jar[jar] (0ms)
downloading D:\users\mm\.ivy\local\jayasoft\filter-framework\1.3\jars\filter-hmimpl.jar .... (1kB)
        [SUCCESSFUL ] [ jayasoft | filter-framework | 1.3 ]/filter-hmimpl.jar[jar] (10ms)
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |       build      |   1   |   1   |   1   |   0   ||   1   |   1   |
        |   noexternaljar  |   1   |   1   |   1   |   0   ||   2   |   2   |
        |  withexternaljar |   2   |   1   |   1   |   0   ||   3   |   2   |
        ---------------------------------------------------------------------
:: retrieving :: [ jayasoft | myapp ]
        confs: [build, noexternaljar, withexternaljar]
        6 artifacts copied, 0 already retrieved

build:
    [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\myapp\build
    [javac] Compiling 1 source file to D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\myapp\build

run-cc:
     [java] Filtering with:class filter.ccimpl.CCFilter
     [java] Result :[two, tree]

Launching application with only home made jars is straingforward.
type ant run-hm

Buildfile: build.xml

resolve:
:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
no configuration file found, using default...
:: configuring :: url = jar:file:/C:/dev/ant/apache-ant-1.6.2/lib/ivy-20060123130642.jar!/fr/jayasoft/ivy/conf/ivyconf.xml
:: resolving dependencies :: [ jayasoft | myapp | working@SPIDER ]
        confs: [build, noexternaljar, withexternaljar]
        found [ jayasoft | filter-framework | 1.3 ] in default
        [1.3] [ jayasoft | filter-framework | latest.integration ]
        found [ apache | commons-collections | 3.1 ] in default
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |       build      |   1   |   1   |   0   |   0   ||   1   |   0   |
        |   noexternaljar  |   1   |   1   |   0   |   0   ||   2   |   0   |
        |  withexternaljar |   2   |   1   |   0   |   0   ||   3   |   0   |
        ---------------------------------------------------------------------
:: retrieving :: [ jayasoft | myapp ]
        confs: [build, noexternaljar, withexternaljar]
        0 artifacts copied, 6 already retrieved

build:

run-hm:
     [java] Filtering with:class filter.hmimpl.HMFilter
     [java] Result :[two, tree]

BUILD SUCCESSFUL

Nice we got the same result but we can see that implementation class are different.

Conclusion

You should use configuration as often as possible
Configurations are very important concept in ivy. They allow you to groups artifacts set by meaning.
When you write ivy file for projects that are supposed to be reused, use configurations to allow people to get only they what they need without having to specify it by hand using artifact tag in dependency section.

Building a repository

With the install ant task you are given the possibility to copy ivy descriptors and artifacts found from a resolver and publish them into another resolver.

This tutorial will show you how to build your own clean enterprise repository of ivy descriptors and modules artifacts.
We will first use some basic ivy configuration files to show how it works, and then we will use advanced features like namespaces to build a real enterprise repository.

The project used

The project that we will use is quite simple.
It is compouned of an ant build file, and some ivy conf files.

Here are the accessible target that we will use :

Z:\ivy-repository>ant -p
Buildfile: build.xml

Main targets:

 advanced                                 --> retrieve files from public repositories (ivyrep, ibiblio, ...) using namespaces
 basic                                    --> retrieve files from well formatted ivy repositories
 basic-deps                               --> retrieve files from well formatted ivy repositories with dependencies
 clean-cache                              --> clean the cache
 clean-repo                               --> clean the destination repository
 commons-lang-1-0-ibiblio-no-namespace    --> retrieve commons-lang 1.0 from ibiblio maven using no namespaces
 commons-lang-1-0-ibiblio-with-namespace  --> retrieve commons-lang 1.0 from ibiblio maven using namespaces
 maven1                                   --> retrieve commons-lang 1.0 from maven1 repo using namespaces
 maven2                                   --> retrieve files from maven2 repo using namespaces
Default target: basic




The project is accessible in the sources of Ivy into : IVY_HOME/src/example/build-a-ivy-repository

Basic repository replication

!!!! UNDER CONSTRUCTION !!!!

We will study here two cases, corresponding to the two basics targets found in the previous build.xml project file.

Basic : ivyconf.xml file used

The ivy conf file that we will use is very simple here. It defines two resolvers, libraries and local-repository. The first one is used to retrieve the files that we want, the second is used to copy them. The second one will become our own repository.

  • ivyrep : nothing special on it, ivy files will be looked for on ivyrep and artifacts will be downloaded from
    ibilio
  • local-repository : will store the found files
<ivyconf>
    <conf  defaultCache="${ivy.cache.dir}"
            defaultResolver="local-repository"
            defaultConflictManager="all" />    <!-- in order to get all revisions without any eviction -->
    <resolvers>
        <ivyrep name="libraries" />
        <filesystem name="local-repository">
            <ivy pattern="${dest.repo.dir}/[organisation]/[module]/ivys/ivy-[revision].xml"/>
            <artifact pattern="${dest.repo.dir}/[organisation]/[module]/[type]s/[artifact]-[revision].[type]"/>
        </filesystem>
    </resolvers>
</ivyconf>

basic, retrieve commons-lang 1.0

Let's have a look at the basic target.

    <target name="basic" depends="init-basic" description="--> retrieve files from well formatted ivy repositories">
        <ivy:install organisation="apache" module="commons-lang" revision="1.0" from="${from-resolver}" to="${to-resolver}" />
    </target>

After a call to init-basic, that make the ivy initialization with the right ivyconf file, we only call the task install to retrieve apache commons-lang in it's 1.0 version.
Here is the ant call output :

Z:\ivy-repository>ant basic
Buildfile: build.xml

init-basic:
:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
:: configuring :: file = Z:\ivy-repository\ivy-conf-basic.xml

basic:
:: installing [ apache | commons-lang | 1.0 ] ::
:: resolving dependencies ::
        found [ apache | commons-lang | 1.0 ] in libraries
:: downloading artifacts to cache ::
downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-1.0.jar ...
............ (62kB)
        [SUCCESSFUL ] [ apache | commons-lang | 1.0 ]/commons-lang.jar[jar] (1203ms)
:: installing in local-repository ::
        published commons-lang to Z:\ivy-repository/ivy-local-repository/apache/commons-lang/jars/commons-lang-1.0.jar
        published ivy to Z:\ivy-repository/ivy-local-repository/apache/commons-lang/ivys/ivy-1.0.xml

BUILD SUCCESSFUL
Total time: 2 seconds

The trace tells us that the module definition was found using the "libraries" resolver and that the corresponding artifact was downloaded from ibiblio. Then both were published in the local repository.

If we take a look at our repository :

Z:\ivy-repository>dir /s /B /A:-D ivy-local-repository
Z:\ivy-repository\ivy-local-repository\apache\commons-lang\ivys\ivy-1.0.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-lang\jars\commons-lang-1.0.jar
Z:\ivy-repository>

We can see that we have started our own repository by retrieving the commons-lang 1.0 ivy file descriptor and jar.

basic with dependencies, retrieve hibernate 2.1.8

Now let's advance a little more by trying a module that has some dependencies. Here is the target that we will call :

    <target name="basic-deps" depends="init-basic" description="--> retrieve files from well formatted ivy repositories with dependencies">
        <ivy:install organisation="hibernate" module="hibernate" revision="2.1.8" from="${from-resolver}" to="${to-resolver}" transitive="true" />
    </target>

This target is very similar to the basic one, except it defines the transitivity mode to use. By writing, transitive="true", we tell the task to retrieve the corresponding module and it's dependencies.

Ok let's call the target :

Z:\ivy-repository>ant basic-deps
Buildfile: build.xml

init-basic:
:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
:: configuring :: file = Z:\ivy-repository\ivy-conf-basic.xml

basic-deps:
:: installing [ hibernate | hibernate | 2.1.8 ] ::
:: resolving dependencies ::
        found [ hibernate | hibernate | 2.1.8 ] in libraries
        found [ cglib | cglib | 2.0.2 ] in libraries
        found [ apache | commons-collections | 2.1.1 ] in libraries
        found [ apache | commons-logging | 1.0.4 ] in libraries
        found [ dom4j | dom4j | 1.4 ] in libraries
        found [ ehcache | ehcache | 0.9 ] in libraries
        found [ odmg | odmg | 3.0 ] in libraries
        found [ sun | jta | 1.0 ] in libraries
        found [ apache | xalan | 2.4.0 ] in libraries
        found [ apache | xerces | 2.4.0 ] in libraries
        found [ sun | jdbc | 2.0 ] in libraries
        found [ sun | jca | 1.0 ] in libraries
        found [ sun | jaas | 1.0 ] in libraries
        found [ c3p0 | c3p0 | 0.8.4.5 ] in libraries
        found [ apache | commons-dbcp | 1.2.1 ] in libraries
        found [ apache | commons-pool | 1.2 ] in libraries
        found [ apache | commons-collections | 2.1 ] in libraries
        found [ apache | xerces | 2.0.2 ] in libraries
        found [ proxool | proxool | 0.8.3 ] in libraries
        found [ jboss | jboss-cache | 1.1.1 ] in libraries
        found [ opensymphony | oscache | 2.0 ] in libraries
        found [ apache | commons-logging | 1.0.3 ] in libraries
        found [ swarmcache | swarmcache | 1.0RC2 ] in libraries
        found [ apache | commons-logging | 1.0.2 ] in libraries
        found [ jgroups | jgroups | 2.2 ] in libraries
:: downloading artifacts to cache ::
downloading http://www.ibiblio.org/maven/hibernate/jars/hibernate-2.1.8.jar ...
...........
............
.. (944kB)
        [SUCCESSFUL ] [ hibernate | hibernate | 2.1.8 ]/hibernate.jar[jar] (97063ms)


SOME MINUTES LATER .... ;-)


downloading http://www.ibiblio.org/maven/commons-logging/jars/commons-logging-1.0.4.... ...
..
......
.. (37kB)
        [SUCCESSFUL ] [ apache | commons-logging | 1.0.4 ]/commons-logging.jar[jar] (24172ms)

BUILD SUCCESSFUL
Total time: 14 minutes 57 seconds
Z:\ivy-repository>

We can see here that ivy has resolved hibernate 2.1.8 and 24 depending modules. If we look at the ivy file for hibernate 2.1.8, we can see that it defines 17 dependencies. The 7 others that ivy retrieved, were transitive ones used in direct dependent modules of hibernate.

We can notice that we have retrieve 3 differents revisions of apache commons-logging (1.0.2, 1.0.3, 1.0.4) and 2 revisions of commons-collections (1.2, 1.2.1). This is due to the fact that we use the "no conflict" conflic manager in the ivyconf file.
We do not want to evict any modules because we are building our own repository !

8 modules artifacts have not been downloaded cause they have not been found on ibiblio with the ivyconf as it is.
We will see how to handle this problem in the advanced tutorial.

If we look at our repository now, it starts to look to something good :

Z:\ivy-repository>dir /s /B /A:-D ivy-local-repository
Z:\ivy-repository\ivy-local-repository\apache\commons-collections\ivys\ivy-2.1.1.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-collections\ivys\ivy-2.1.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-collections\jars\commons-collections-2.1.1.jar
Z:\ivy-repository\ivy-local-repository\apache\commons-collections\jars\commons-collections-2.1.jar
Z:\ivy-repository\ivy-local-repository\apache\commons-dbcp\ivys\ivy-1.2.1.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-dbcp\jars\commons-dbcp-1.2.1.jar
Z:\ivy-repository\ivy-local-repository\apache\commons-lang\ivys\ivy-1.0.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-lang\jars\commons-lang-1.0.jar
Z:\ivy-repository\ivy-local-repository\apache\commons-logging\ivys\ivy-1.0.2.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-logging\ivys\ivy-1.0.3.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-logging\ivys\ivy-1.0.4.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-logging\jars\commons-logging-1.0.2.jar
Z:\ivy-repository\ivy-local-repository\apache\commons-logging\jars\commons-logging-1.0.3.jar
Z:\ivy-repository\ivy-local-repository\apache\commons-logging\jars\commons-logging-1.0.4.jar
Z:\ivy-repository\ivy-local-repository\apache\commons-pool\ivys\ivy-1.2.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-pool\jars\commons-pool-1.2.jar
Z:\ivy-repository\ivy-local-repository\apache\xalan\ivys\ivy-2.4.0.xml
Z:\ivy-repository\ivy-local-repository\apache\xalan\jars\xalan-2.4.0.jar
Z:\ivy-repository\ivy-local-repository\apache\xerces\ivys\ivy-2.0.2.xml
Z:\ivy-repository\ivy-local-repository\apache\xerces\ivys\ivy-2.4.0.xml
Z:\ivy-repository\ivy-local-repository\apache\xerces\jars\xerces-2.0.2.jar
Z:\ivy-repository\ivy-local-repository\apache\xerces\jars\xerces-2.4.0.jar
Z:\ivy-repository\ivy-local-repository\apache\xerces\jars\xmlParserAPIs-2.0.2.jar
Z:\ivy-repository\ivy-local-repository\c3p0\c3p0\ivys\ivy-0.8.4.5.xml
Z:\ivy-repository\ivy-local-repository\c3p0\c3p0\jars\c3p0-0.8.4.5.jar
Z:\ivy-repository\ivy-local-repository\cglib\cglib\ivys\ivy-2.0.2.xml
Z:\ivy-repository\ivy-local-repository\cglib\cglib\jars\cglib-full-2.0.2.jar
Z:\ivy-repository\ivy-local-repository\dom4j\dom4j\ivys\ivy-1.4.xml
Z:\ivy-repository\ivy-local-repository\dom4j\dom4j\jars\dom4j-1.4.jar
Z:\ivy-repository\ivy-local-repository\ehcache\ehcache\ivys\ivy-0.9.xml
Z:\ivy-repository\ivy-local-repository\ehcache\ehcache\jars\ehcache-0.9.jar
Z:\ivy-repository\ivy-local-repository\hibernate\hibernate\ivys\ivy-2.1.8.xml
Z:\ivy-repository\ivy-local-repository\hibernate\hibernate\jars\hibernate-2.1.8.jar
Z:\ivy-repository\ivy-local-repository\jboss\jboss-cache\ivys\ivy-1.1.1.xml
Z:\ivy-repository\ivy-local-repository\jgroups\jgroups\ivys\ivy-2.2.xml
Z:\ivy-repository\ivy-local-repository\odmg\odmg\ivys\ivy-3.0.xml
Z:\ivy-repository\ivy-local-repository\odmg\odmg\jars\odmg-3.0.jar
Z:\ivy-repository\ivy-local-repository\opensymphony\oscache\ivys\ivy-2.0.xml
Z:\ivy-repository\ivy-local-repository\proxool\proxool\ivys\ivy-0.8.3.xml
Z:\ivy-repository\ivy-local-repository\proxool\proxool\jars\proxool-0.8.3.jar
Z:\ivy-repository\ivy-local-repository\sun\jaas\ivys\ivy-1.0.xml
Z:\ivy-repository\ivy-local-repository\sun\jca\ivys\ivy-1.0.xml
Z:\ivy-repository\ivy-local-repository\sun\jdbc\ivys\ivy-2.0.xml
Z:\ivy-repository\ivy-local-repository\sun\jta\ivys\ivy-1.0.xml
Z:\ivy-repository\ivy-local-repository\swarmcache\swarmcache\ivys\ivy-1.0RC2.xml
Z:\ivy-repository\ivy-local-repository\swarmcache\swarmcache\jars\swarmcache-1.0RC2.jar

Z:\ivy-repository>

Advanced repository - step 1

On the road to a professional repository

We will study in this section how to build a professionnal repository. What is a professionnal dependency resolver ? Our vision is to say that a good quality repository must follow clear rules about projects naming and must offer corrects, usuables, configurables and verified project descriptors. In order to achieve those goals, we think that you have to build your own repository.
We have seen in the previous example, that we could use some public repositories to begin to build our own repository.
Nevertheless, the result is not at all the one that was excepected. Indeed there is a problem with public repositories : their partial incompatibility.
For example, in ivyrep all commons-* projects belong to the apache organisation. In both ibiblio versions, it is not the case. The same problem could appear for other projects with other repositories, it is not the debate here.

To resolve some of the incompatibilities, we will use a new feature of ivy 1.3 the namespaces.

Using namespaces

In order to use namespaces, we first need to see what's happening when none are used on repositories that do not fit our needs.
Let's take commons-lang 1.0 from ibiblio with a maven2 pom.
First clean your cache and repository.

Z:\ivy-repository>ant clean-cache clean-repo

Then call the good ant target : ant commons-lang-1-0-ibiblio-no-namespace

Z:\ivy-repository>ant commons-lang-1-0-ibiblio-no-namespace
Buildfile: build.xml

init-advanced:
:: Ivy 20060125070719 - 20060125070719 :: http://ivy.jayasoft.org/ ::
:: configuring :: file = Z:\ivy-repository\ivy-conf-advanced.xml

commons-lang-1-0-ibiblio-no-namespace:
:: installing [ commons-lang | commons-lang | 1.0 ] ::
:: resolving dependencies ::
        found [ commons-lang | commons-lang | 1.0 ] in ibiblio-maven2-nonamespace
        found [ junit | junit | 3.7 ] in ibiblio-maven2-nonamespace
:: downloading artifacts to cache ::
downloading http://www.ibiblio.org/maven2/commons-lang/commons-lang/1.0/commons-lang... ...
.............. (62kB)
        [SUCCESSFUL ] [ commons-lang | commons-lang | 1.0 ]/commons-lang.jar[jar] (1313ms)
downloading http://www.ibiblio.org/maven2/junit/junit/3.7/junit-3.7.jar ...
.............
.............. (114kB)
        [SUCCESSFUL ] [ junit | junit | 3.7 ]/junit.jar[jar] (2360ms)
:: installing in local-repository ::
        published commons-lang to Z:\ivy-repository/ivy-local-repository/commons-lang/commons-lang/jars/commons-lang-1.0.jar
        published ivy to Z:\ivy-repository/ivy-local-repository/commons-lang/commons-lang/ivys/ivy-1.0.xml
        published junit to Z:\ivy-repository/ivy-local-repository/junit/junit/jars/junit-3.7.jar
        published ivy to Z:\ivy-repository/ivy-local-repository/junit/junit/ivys/ivy-3.7.xml
:: install resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   2   |   2   |   2   |   0   ||   2   |   2   |
        ---------------------------------------------------------------------

BUILD SUCCESSFUL
Total time: 6 seconds
Z:\ivy-repository>

If we take a look at the repository, we can see that we respect the ibiblio maven2 architecture, the organisation apache does not appear.

Z:\ivy-repository>dir /s /B /A:-D ivy-local-repository
Z:\ivy-repository\ivy-local-repository\commons-lang\commons-lang\ivys\ivy-1.0.xml
Z:\ivy-repository\ivy-local-repository\commons-lang\commons-lang\jars\commons-lang-1.0.jar
Z:\ivy-repository\ivy-local-repository\junit\junit\ivys\ivy-3.7.xml
Z:\ivy-repository\ivy-local-repository\junit\junit\jars\junit-3.7.jar

If you take a look at the ivy descriptor for commons-lang, you will see that the organisation is still commons-lang. It could not be another thing as we did not do anything for it.

<ivy-module version="1.0">
<info organisation="commons-lang"
module="commons-lang"
revision="1.0"
status="integration"
publication="20051124062021"
/>

Introduction to namespaces

Let's see directly the result, we will have some explanations after.
Clean your repo and cache, and call : ant commons-lang-1-0-ibiblio-with-namespace

Z:\ivy-repository>ant commons-lang-1-0-ibiblio-with-namespace
Buildfile: build.xml

init-advanced:
:: Ivy non official version :: http://ivy.jayasoft.org/ ::
:: configuring :: file = Z:\ivy-repository\ivy-conf-advanced.xml

commons-lang-1-0-ibiblio-with-namespace:
:: installing [ apache | commons-lang | 1.0 ] ::
:: resolving dependencies ::
        found [ apache | commons-lang | 1.0 ] in ibiblio-maven2
        found [ junit | junit | 3.7 ] in ibiblio-maven2
:: downloading artifacts to cache ::
downloading http://www.ibiblio.org/maven2/commons-lang/commons-lang/1.0/commons-lang... ...
............. (62kB)
        [SUCCESSFUL ] [ apache | commons-lang | 1.0 ]/commons-lang.jar[jar] (1094ms)
downloading http://www.ibiblio.org/maven2/junit/junit/3.7/junit-3.7.jar ...
............................ (114kB)
        [SUCCESSFUL ] [ junit | junit | 3.7 ]/junit.jar[jar] (1641ms)
:: installing in local-repository ::
        published commons-lang to Z:\ivy-repository/ivy-local-repository/apache/commons-lang/jars/commons-lang-1.0.jar
        published ivy to Z:\ivy-repository/ivy-local-repository/apache/commons-lang/ivys/ivy-1.0.xml
        published junit to Z:\ivy-repository/ivy-local-repository/junit/junit/jars/junit-3.7.jar
        published ivy to Z:\ivy-repository/ivy-local-repository/junit/junit/ivys/ivy-3.7.xml
:: install resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   2   |   2   |   2   |   0   ||   2   |   2   |
        ---------------------------------------------------------------------

BUILD SUCCESSFUL
Total time: 5 seconds

Now if we look at our repository, it seems to look fine.

Z:\ivy-repository>dir /s /B /A:-D ivy-local-repository
Z:\ivy-repository\ivy-local-repository\apache\commons-lang\ivys\ivy-1.0.xml
Z:\ivy-repository\ivy-local-repository\apache\commons-lang\jars\commons-lang-1.0.jar
Z:\ivy-repository\ivy-local-repository\junit\junit\ivys\ivy-3.7.xml
Z:\ivy-repository\ivy-local-repository\junit\junit\jars\junit-3.7.jar

Have a look at the ivy file to see it it looks better than before. Ok, we have now our apache organisation.

<ivy-module version="1.0">
<info organisation="apache"
module="commons-lang"
revision="1.0"
status="integration"
publication="20051124062021"
/>

How does this work ?

If we look at the ant target commons-lang-1-0-ibiblio-with-namespace, we can see that it uses a resolver called ibiblio-maven2.
Let's find it... The configuration file used for this test is ivy-conf-advanced.xml. This one includes ivy-maven2-ivyconf.xml where the required resolver is defined.
Let's see it's definition :

<ibiblio name="ibiblio-maven2"
                root="${ibiblio-maven2-root}"
                pattern="${ibiblio-maven2-pattern}"
                m2compatible="true"
                namespace="ibiblio-maven2"
/>

Ok, i see it, it is a ibiblio resolver for which we specify the root and the pattern. The important things here are the 2 other parameters.

  • m2compatible is a flag telling that we allow reading POMs file and make some transformations on URLs regarding the organisation name. Indeed, maven transforms organisations like "org.apache" into "some_url/org/apache" to retrieve information on ibiblio repositories.
  • namespace this attribute defines a domain in which same projects (meanning organsiation, module or revision) can be nammed whith differents kinds.

A namespace is defined by a set of rule, for ibiblio-maven2, whe have declared some rules :

rule handling imported apache maven1 projects

<rule> <!-- imported apache maven1 projects -->
<fromsystem>
    <src org="apache" module=".+"/>
   
    <dest org="$m0" module="$m0"/>
</fromsystem>
<tosystem>
    <src org="commons-.+" module="commons-.+" />
    <src org="ant.*" module="ant.*" />
    ...
    <src org="xmlrpc" module="xmlrpc" />

    <dest org="apache" module="$m0"/>
</tosystem>
</rule>

Note about regular expressions usage :
In order to distinguish matching regular expressions found in organisation, module & revision the notation used prefixes the matching regular expression with the letters 'o', 'm' & 'r'.
$o0 : the whole regular expression term in the organisation attribute
$o1 : the first matching expression term that was marked in the organisation attribute
...
The same applies for modules : $m0, $m1, ...
and for revisions : $r0, $r1, ...
  • fromsystem : we define here that the projects defined in the system under the organisation called "apache" are transformed into the destination namespace (whose resolver it applies) into projects whose organisation is nammed with the module name, we don't care here about the revision. For example, the project ['apache', 'commons-lang', '1.0'] in the namespace system will be translated into ['commons-lang', 'commons-lang', '1.0'] in the ibiblio-maven2 resolver namespace.
  • tosystem : we define here the reverse mapping, ie how to translate apache projects from ibiblio into real apache projects in the namespace system. The rule here, is telling that all projects matching commons-.+ (see it as java regular expression) for their organisation name and module name are transformed into projects whose organisation is apache with the module name as it was found. The same kind of rule is applied for others apache projects like ant, etc. For example, ['ant','ant','1.6.2'] in ibiblio-maven2 namespace will become ['apache','ant','1.6.2'] int the system namespace.

rule handling new apache projects

<rule> <!-- new apache projects -->
    <fromsystem>
        <src org="apache" />
        <dest org="org.apache"/>
    </fromsystem>
    <tosystem>
        <src org="org.apache" />
        <dest org="apache" />
    </tosystem>
</rule>

The mapping adds or removes the package 'org' before the organisation name to conform to maven2 choices.

Advanced repository - step 2

Building the professional repository

Now that we have been well prepared, let's go to a real life example of building our repository.
We will now focus on a bigger example that uses different public repositories to retrieve the information.
In this tutorial we will use, in order of preference :

  • our home made repository
  • ivyrep official
  • ibiblio maven2

the resolvers used

<resolvers>
    <filesystem name="local-repository">
        <ivy pattern="${dest.repo.dir}/[organisation]/[module]/ivys/ivy-[revision].xml"/>
        <artifact pattern="${dest.repo.dir}/[organisation]/[module]/[type]s/[artifact]-[revision].[type]"/>
    </filesystem>

    <chain name="libraries" returnFirst="false">
        <resolver ref="local-repository" />
        <ivyrep name="official-ivy-rep"/>
        <resolver ref="ibiblio-maven2" />
    </chain>
</resolvers>

We start the chain with our home made repository because as we can expect, we consider this repository as good ivy file repository (that's why we create it). So all files that are in this repository are considered as valid and correct and usuable.
The building process is then an iterative process.
After each import of new projects into our repository, we check and modify the generated ivy files (or you do not as you want). The generated ivy files are those that were translated from a POM or those for which an artifact has been found without a module descriptor (ivy or pom).

Let's go

What about to test our configuration with a big project : hibernate 3.0
Just run : ant advanced

Here we go !!!!!!!!

Z:\build-a-ivy-repository>ant advanced
Buildfile: build.xml

init-advanced:
:: Ivy non official version :: http://ivy.jayasoft.org/ ::
:: configuring :: file = Z:\build-a-ivy-repository\config\ivy-conf-advanced.xml

advanced:
:: installing [ hibernate | hibernate | 3.0 ] ::
:: resolving dependencies ::
        found [ hibernate | hibernate | 3.0 ] in ibiblio-maven2
        found [ apache | commons-logging | 1.0.4 ] in official-ivy-rep
        found [ apache | ant | 1.6.3 ] in ibiblio-maven2
        found [ c3p0 | c3p0 | 0.8.4.5 ] in official-ivy-rep
        found [ proxool | proxool | 0.8.3 ] in official-ivy-rep
        found [ ehcache | ehcache | 1.1 ] in official-ivy-rep
        found [ apache | xerces | 2.5.0 ] in official-ivy-rep
        found [ apache | commons-collections | 2.1.1 ] in official-ivy-rep
        found [ opensymphony | oscache | 2.1 ] in ibiblio-maven2
        found [ swarmcache | swarmcache | 1.0RC2 ] in official-ivy-rep
        found [ apache | commons-collections | 2.1 ] in official-ivy-rep
        found [ apache | commons-logging | 1.0.2 ] in official-ivy-rep
        found [ jgroups | jgroups | 2.2 ] in official-ivy-rep
        found [ jboss | jboss-cache | 1.2.2 ] in ibiblio-maven2
        found [ jboss | jboss-system | 4.0.2 ] in ibiblio-maven2
        found [ jboss | jboss-common | 4.0.2 ] in ibiblio-maven2
        found [ jboss | jboss-minimal | 4.0.2 ] in ibiblio-maven2
        found [ jboss | jboss-j2se | 200504122039 ] in ibiblio-maven2
        found [ concurrent | concurrent | 1.3.4 ] in ibiblio-maven2
        found [ jgroups | jgroups-all | 2.2.7 ] in ibiblio-maven2
        found [ cglib | cglib | 2.0.2 ] in official-ivy-rep
        found [ objectweb | asm | 1.3.4 ] in official-ivy-rep
        found [ asm | asm | 1.4.3 ] in ibiblio-maven2
        found [ javax.security | jacc | 1.0 ] in ibiblio-maven2
        found [ dom4j | dom4j | 1.6 ] in ibiblio-maven2
        found [ javax.transaction | jta | 1.0.1B ] in ibiblio-maven2
        found [ hibernate | antlr | 2.7.5H3 ] in ibiblio-maven2
        found [ odmg | odmg | 3.0 ] in official-ivy-rep
:: downloading artifacts to cache ::
downloading http://www.ibiblio.org/maven2/hibernate/hibernate/3.0/hibernate-3.0.jar ...
..................................................
.. (1565kB)
        [SUCCESSFUL ] [ hibernate | hibernate | 3.0 ]/hibernate.jar[jar] (8500ms)
downloading http://www.ibiblio.org/maven2/hibernate/antlr/2.7.5H3/antlr-2.7.5H3.jar ...

           SOME MINUTES LATER !!!!!!!!!!

downloading http://www.ibiblio.org/maven/commons-logging/jars/commons-logging-1.0.4.... ...
........ (37kB)
        [SUCCESSFUL ] [ apache | commons-logging | 1.0.4 ]/commons-logging.jar[jar] (1110ms)
:: installing in local-repository ::
        published hibernate to Z:\build-a-ivy-repository/ivy-local-repository/hibernate/hibernate/jars/hibernate-3.0.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/hibernate/hibernate/ivys/ivy-3.0.xml
        published antlr to Z:\build-a-ivy-repository/ivy-local-repository/hibernate/antlr/jars/antlr-2.7.5H3.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/hibernate/antlr/ivys/ivy-2.7.5H3.xml
        published dom4j to Z:\build-a-ivy-repository/ivy-local-repository/dom4j/dom4j/jars/dom4j-1.6.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/dom4j/dom4j/ivys/ivy-1.6.xml
missing artifact [ javax.security | jacc | 1.0 ]/jacc.jar[jar]: Z:\build-a-ivy-repository\cache\javax.security\jacc\jars\jacc-1.0.jar file does not exist
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/javax.security/jacc/ivys/ivy-1.0.xml
        published asm to Z:\build-a-ivy-repository/ivy-local-repository/asm/asm/jars/asm-1.4.3.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/asm/asm/ivys/ivy-1.4.3.xml
        published cglib-full to Z:\build-a-ivy-repository/ivy-local-repository/cglib/cglib/jars/cglib-full-2.0.2.jar
        published cglib to Z:\build-a-ivy-repository/ivy-local-repository/cglib/cglib/jars/cglib-2.0.2.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/cglib/cglib/ivys/ivy-2.0.2.xml
        published asm to Z:\build-a-ivy-repository/ivy-local-repository/objectweb/asm/jars/asm-1.3.4.jar
        published asm-util to Z:\build-a-ivy-repository/ivy-local-repository/objectweb/asm/jars/asm-util-1.3.4.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/objectweb/asm/ivys/ivy-1.3.4.xml
        published jboss-cache to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-cache/jars/jboss-cache-1.2.2.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-cache/ivys/ivy-1.2.2.xml
        published jgroups-all to Z:\build-a-ivy-repository/ivy-local-repository/jgroups/jgroups-all/jars/jgroups-all-2.2.7.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jgroups/jgroups-all/ivys/ivy-2.2.7.xml
        published concurrent to Z:\build-a-ivy-repository/ivy-local-repository/concurrent/concurrent/jars/concurrent-1.3.4.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/concurrent/concurrent/ivys/ivy-1.3.4.xml
        published jboss-j2se to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-j2se/jars/jboss-j2se-200504122039.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-j2se/ivys/ivy-200504122039.xml
        published jboss-minimal to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-minimal/jars/jboss-minimal-4.0.2.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-minimal/ivys/ivy-4.0.2.xml
        published jboss-system to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-system/jars/jboss-system-4.0.2.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-system/ivys/ivy-4.0.2.xml
        published swarmcache to Z:\build-a-ivy-repository/ivy-local-repository/swarmcache/swarmcache/jars/swarmcache-1.0RC2.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/swarmcache/swarmcache/ivys/ivy-1.0RC2.xml
missing artifact [ jgroups | jgroups | 2.2 ]/jgroups.jar[jar]: Z:\build-a-ivy-repository\cache\jgroups\jgroups\jars\jgroups-2.2.jar file does not exist
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jgroups/jgroups/ivys/ivy-2.2.xml
        published commons-logging to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-logging/jars/commons-logging-1.0.2.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-logging/ivys/ivy-1.0.2.xml
        published oscache to Z:\build-a-ivy-repository/ivy-local-repository/opensymphony/oscache/jars/oscache-2.1.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/opensymphony/oscache/ivys/ivy-2.1.xml
        published c3p0 to Z:\build-a-ivy-repository/ivy-local-repository/c3p0/c3p0/jars/c3p0-0.8.4.5.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/c3p0/c3p0/ivys/ivy-0.8.4.5.xml
        published odmg to Z:\build-a-ivy-repository/ivy-local-repository/odmg/odmg/jars/odmg-3.0.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/odmg/odmg/ivys/ivy-3.0.xml
        published proxool to Z:\build-a-ivy-repository/ivy-local-repository/proxool/proxool/jars/proxool-0.8.3.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/proxool/proxool/ivys/ivy-0.8.3.xml
missing artifact [ javax.transaction | jta | 1.0.1B ]/jta.jar[jar]: Z:\build-a-ivy-repository\cache\javax.transaction\jta\jars\jta-1.0.1B.jar file does not exist
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/javax.transaction/jta/ivys/ivy-1.0.1B.xml
        published jboss-common to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-common/jars/jboss-common-4.0.2.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-common/ivys/ivy-4.0.2.xml
        published ant to Z:\build-a-ivy-repository/ivy-local-repository/apache/ant/jars/ant-1.6.3.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/ant/ivys/ivy-1.6.3.xml
        published commons-collections to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-collections/jars/commons-collections-2.1.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-collections/ivys/ivy-2.1.xml
        published ehcache to Z:\build-a-ivy-repository/ivy-local-repository/ehcache/ehcache/jars/ehcache-1.1.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/ehcache/ehcache/ivys/ivy-1.1.xml
        published commons-collections to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-collections/jars/commons-collections-2.1.1.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-collections/ivys/ivy-2.1.1.xml
        published xercesImpl to Z:\build-a-ivy-repository/ivy-local-repository/apache/xerces/jars/xercesImpl-2.5.0.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/xerces/ivys/ivy-2.5.0.xml
        published commons-logging to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-logging/jars/commons-logging-1.0.4.jar
        published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-logging/ivys/ivy-1.0.4.xml
:: install resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   28  |   28  |   28  |   0   ||   30  |   27  |
        ---------------------------------------------------------------------

BUILD SUCCESSFUL
Total time: 2 minutes 10 seconds
Z:\build-a-ivy-repository>

Analysing the results

OK, it seems that we have a good start point for our repository.
As you can see in the resolving part of the process :

:: resolving dependencies ::
        found [ hibernate | hibernate | 3.0 ] in ibiblio-maven2
        found [ apache | commons-logging | 1.0.4 ] in official-ivy-rep
        ...
        found [ odmg | odmg | 3.0 ] in official-ivy-rep

some ivy files were retrieved from the ivyrep the official ivy repository. That significates that for these modules, you have in your home made repository good ivy files (with meaningfull configurations, ...).

And now

Now what you need to do is to download missing artifacts, those not on ibiblio (from sun, ...) and correct the generated ivy files.
It is important to make a review of the generated ivy files because you could then benefit from all the power of ivy by defining for those projects good configurations and some other good things.

To ease finding generated files, just take a look at the generated resolve report in your cache. You will find there the projects for which a default ivy file was generated


and you can see the resolvers that have resolved the modules. In our example, you will update the files whose project were resolved by the ibiblio-maven2 resolver.

More examples

If you have successfully followed and understood all the tutorials, maybe you still need to get a better picture of how to use Ivy in the real world.

Here are some links which can be interesting:

SAnt

SAnt is an experimental build system based on Ant and Ivy. It can be interesting to use as is or to get insight on an interesting approach to manage your builds.

AntAnt

AntAnt is an ant project generator (generates an ant project skeleton), which uses ivy for dependency management. It can be an interesting place to look for examples of ant build files integrated with ivy.

Spring Modules

The spring modules project build system is based on Ant and Ivy, and it's really interesting to have a look at how a modularized project can take advantage of advanced ant and ivy features to make the build simpler.

Webwork

The webwork project (which should become struts action framework) uses ant+ivy for their build, and thus make their framework very easy to use in an ant+ivy build system. They have a page documenting how to use ivy with their framework, which can be an interesting reading even if you don't plan to use webwork.

Easing multi module development

Johan stuyts, the author of SAnt, also contributed a nice article on his view of how to use Ivy on a multi module environment.

Best practices

Here are some recommendations and best practices we have gathered throughout our experience and consultancies with our customers.

Add module descriptors for all your modules

In Ivy world, module descriptors are ivy files, which are basically simple xml files describing both what the module produce as artifact and its dependencies.

It is a good practice to write or download module descriptors for all the modules involved in your development, even for your third party dependencies, and even if they don't provide themselves such module descriptors.

First it will seem like an extra work, and require time. But when you will have several modules using the same third party library, and than you will only need to add one line to your ivy file to get this library and all its own dependencies that you really need (if you have good module descriptors in your repository, especially with the use of module configurations). It will also be very helpful when you want to upgrade a dependency. One single change in your module ivy file and you will get the updated version with its updated (or not) dependencies.

Therefore we recommend to add ivy files for all the modules in your repository, you can even enforce this rule by setting the allownomd attribute to false on your resolvers. Hence you shouldn't need to use the dependency artifact inclusion/exclusion/specification feature of Ivy, which should only be used in very specific cases.

Use your own enterprise repository

This is usually not a valid recommendation for open source projects, but for the enterprise world we strongly suggest to avoid relying on a public repository like maven ibiblio or ivyrep. Why? Well, there are a couple of reasons:

Note that it's not because you use an enterprise repository that you have to build it entirely by hand. Ivy features an install task which can be used to install modules from a repository to another one, so it can be used to selectively install modules from a public repository to your enterprise repository, where you will then be able to ensure control, reliability and accuracy.

Always use patterns with at least organisation and module

Ivy is very flexible and can accomodate a lot of existing repositories, using the concept of patterns. But if your repository doesn't exist yet, we strongly recommend to always use the organisation and the module name in your pattern, even for private repository where you put only your own modules (which all the same organisation). Why? Because Ivy listing feature rely on the token it can find in the pattern. If you have no organisation token in your pattern, Ivy won't be able to list the (only?) organisation in your repository. And this can be a problem for code completion in IvyDE, for example, but also for repository wide tasks like install or rereport.

Public ivyconf.xml with public repositories

If you create a public repository, provide an url to corresponding ivyconf.xml. It's pretty easy to do, and if someone want to leverage your repository, he will just have to call configure with the url of your ivyconf.xml, or include it in its own configuration file, which makes it really easy to combine several public repositories.

Dealing with integration versions

Very often especially when working in a team or with several modules, you will need to rely on intermediate, non finalized versions of your modules. These versions are what we call integration versions, because their main objective is to be integrated with other modules to make and test an application or a framework.

If you follow the continuous integration paradigm across modules, these integration versions can be produced by a continuous integration server, very frequently.

So, how can you deal with these, possibly numerous, integration versions?

There are basically two ways to deal with them, both ways being supported by Ivy:

So, which way is the best? As often, it depends on your context, and if one of the two was really bad it wouldn't be supported in Ivy :-)

But usually we recommend to use the second one, because using a new version each time you publish a new version better fits the version identity paradigm, and can make all your builds reproducible, even integration one. And this is interesting because it enables, with some work in your build system, to introduce a mechanism to promote an integration build to a more stable status, like a milestone or a release.

Imagine you have a customer which comes on a monday morning and asks your latest version of your software, for testing or demonstration purpose. Obviously he needs it for the afternoon :-) Now if you have a continuous integration process and a good tracking of your changes and your artifacts, it may occur that you are actually able to fulfill his request without needing the use of a dolorean to give you some more time :-) But it may occur also that your latest version stable enough to be used for the purpose of the customer was actually built a few days ago, because the very latest just break a feature or introduce a new one you don't want to deliver. In this case, you can deliver this 'stable' integration build if you want, but be sure that a few days, or weeks, or even months later, the customer will ask for a bug fix on this demo only version. Why? Because it's a customer, and we all know how they are :-)

So, with a build promotion feature of any build in your repository, the solution would be pretty easy: when the customer ask for the version, you not only deliver the integration build, but you also promote it to a milestone status, for example. this promotion indicates that you should keep track of this version in a long period, to be able to come back to it and create a branch if needed.

Unfortunately Ivy does not by its own allow to have such reproducible builds out of the box, simply because Ivy is a dependency manager, not a build tool. But if you publish only versions with a distinct name and use Ivy features like versions constraint replacement during the publication or recursive delivery of modules, it can really help.

On the other hand, the main drawback of this solution is that it can produce a lot of intermediate versions, and you will have to run some cleaning scripts in your repository unless your company name starts with a G and ends with oogle :-)

Inlining dependencies or not?

With Ivy 1.4 you can resolve a dependency without even writing an ivy file. This pratice is called inlining. But what is it good for, and when should it be avoided?

Putting ivy dependencies in a separate file has the following advantages:

On the other hand, using inline dependencies is very useful when:

Hire an expert

Build and dependency management is often considered with a too low level priority in the software development world. We often see build management implemented by developers when they have time. Even if this may seem like a time and money saving in the short term, it often turns out to be a very bad choice in the long term. Building software is not a simple task, when you want to ensure automatic, tested, fully reproducible builds, releases and installations. On the other hand, once a good build system fitting your very specific needs is setup, it can then only rely on a few people with a good understanding of what is going on, with a constant quality ensured.

Therefore hiring a build and dependency expert to analyse and improve your build and release system is most of the time a very good choice (especially if you choose the right one :-))

Feedback

These best practices are the reflect of our own experience, but we do not pretend to own the unique truth about dependency management or even Ivy use.

So feel free to comment on this page to add your own experience feedback, suggestions or opinion.

Reference

Welcome to Ivy reference documentation.

If you don't know Ivy at all, give a glance at its features, the FAQ and the tutorials before digging into this reference documentation.

Reference Overview

This documentation is decomposed in several parts:

Terminology

Here are some terms used in Ivy, with their definitions in Ivy:

Ivy file

An ivy file is an xml file which is used to describe dependencies of a module (see below). It is usually named ivy.xml.

Configuration file

Ivy configuration files are xml files used to configure ivy to indicate where the dependencies can be found. This should not be confused with a module configuration (see below).

Organisation

An organisation is either a company or a simple group of person which produce software. Ivy handle only one level of organisation, so you cannot describe a company hierarchy with this concept. But it is used to group sofware produced by a same team, just to help find and classify them.
Examples: apache, ibm, jayasoft

Module

A module in ivy is a piece of software that is reusable, and that follow a unique cycle of revision.
Examples: hibernate, ant, ...

Artifact

An artifact is a single file produced by a company when releasing a module. In the java world, common artifacts are jars. In many cases, each revision of a module publish only one artifact (like log4j, for instance), but some of them publish many artifacts dependending on the use of the module (like ant, for instance).

Revision

A revision corresponds to one delivery of a module. It can either be a delivery of a release, a milestone, a beta version, a nightly build, or even a continuous build. All of them are considered revisions in ivy.

Branch

A branch corresponds to the standard meaning of a branch (or sometimes stream) in source control management tools. The head, or trunk, or main stream, is also considered as a branch in Ivy.

Configuration

A module configuration is a way to use or construct a module. Some modules may be used in different ways (think about hibernate which can be used inside or outside an application server), and this way may alter the artifacts you need (in the case of hibernate, jta.jar is needed only if it is used outside an application server). Moreover, a module may need some other modules and artifacts only at build time, and some others at runtime. All those differents ways to use or build a module are called in ivy configurations.

For more details on configurations and how they are used in ivy, please refer to the main concepts page.

Status

A module status indicates how stable a module revision can be considered. It can be used to consolidate the status of all the dependencies of a module, to prevent the use of an integration revision of a dependency in the release of your module. Three statuses are defined by default in ivy:
  • integration: revisions builded by a continuous build, a nightly build, and so on, fall in this category
  • milestone: revisions delivered to the public but not actually finished fall in this category
  • release: revision fully tested and labelled fall in this category
since 1.4 This list is configurable in your configuration file.

Repository

What is called a repository in Ivy is a location where Ivy is able to find your modules artifacts and metadata (i.e. ivy files in most cases). Ivy can be used with complex repositories configured very finely. You can use Dependency Resolvers to do so.

Main Concepts

Dependency Resolver

A dependency resolver is a pluggable class in ivy which is used to:

  • find dependencies ivy files
  • download dependencies artifacts

The notion of artifact "downloading" is large: artifact can be on a web site, or on the local file system of your machine. The download is thus the fact to bring a file from a repository to ivy cache.

Moreover, the fact that it is the responsibility of the resolver to find ivy files and download artifacts help to implement various resolving strategies.

As you see, a dependency resolver can be thought as a class responsible of describing a repository.

If you want to see which resolvers are available in ivy, you can go to the corresponding configuration section

Module configurations explained

Module configurations are described in the terminology page as a way to use or construct a module. Configurations being a central part of Ivy, they need more explanations as a concept.


When you define a way to use or construct a module, you are able to define which artifacts are published by this module in this configuration, and you are also able to define which dependencies are needed in this configuration.

Moreover, because dependencies in ivy are expressed on modules and not on artifacts, it is important to be able to define which configurations of the dependency are required in the configuration you define of your module. That's what is called configuration mapping.

If you use only simple modules and do not want to worry about configurations, you don't have to worry about them. They're still there under the hood, cause ivy can't work without configuration. But most of the time if you declare nothing, ivy assumes that the artifacts of your module are published in all configurations, and that all the dependencies configurations are required in all configurations. And it works in simple cases. But whenever you want to separate things within a module, or get more control over things published and got through dependencies resolution, configuration may answer most of your needs.

For details on how to declare your module configurations, how declare in which configuration your artifacts are published, and how to declare configuration mapping, please refer to ivy file documentation. The configurations tutorial is also a good place to go to learn more about this concept.

Variables

During configuration, ivy allows to define what are called ivy variables. Ivy variables can be seen as ant properties, and are used in a very similar way. In particular, you use a properties tag in the configuration file to load a properties file containing ivy variables and their values.

But the main differences between ant properties and ivy variables are that ivy variables can be overriden, whereas ant
properties can't, and that they are defined in separate environment.

Actually all ant properties are imported into ivy variables when the configuration is done (if you call ivy from ant).
This means that if you define an ant property after the call to configure, it will not be available as an ivy variable.
On the other hand, ivy variables are NOT exported to ant, thus if you define ivy variables in ivy, do not try to use them as ant properties.

To use ivy variables, you just have to follow that same syntax as for ant properties:
${variablename}
where variablename is the name of the variable.

Finally, it's also important to be aware of the time of substitution of variables. This substitution is done as soon as possible. This means that when ivy encounter a reference to a variable, it tries to substitute it if such a variable is defined. Consequently, any later modification of the variable will not alter the value already substituted.

Moreover, in an ant environment, a bunch of variables are going to be set by default via the ant property file loading mechanism (in fact they are first loaded as ant properties and then imported as ivy variables, see ), and even in the ant properties themselves there is going to be eager substitution on loading, effectively making it impossible to override some variable purely via the ivyconf.properties file. Some variables will really only be able to be overriden via ant properties because of this.

Moreover, it's also important to understand the difference between ivy variables and ivy pattern tokens.
See Patterns chapter below to see what pattern tokens are.

Patterns

Ivy patterns are used in many dependency resolvers and ivy tasks, and are a simple way to structure the way ivy works.

First let's give an example. You can for instance configure the file system dependency resolver by giving it
a pattern to find artifacts. This pattern can be like this:
myrepository/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]

This pattern indicates that the repository we use is in a directory called myrepository.

In this directory we have directories having for name the name of the organisation of the module we look for.
Then we have a directory per module, each having for name the name of the module.
Then in module directories we find a directory per artifact type (jars, wars, ivys, ...), in which we find artifacts named by the artifact id, followed by an hyphen, then the revision, a dot, and the artifact extension.
Not too difficult to understand, isn't it ? That's it, you have understood the pattern concept !

To give a bit more explanation, a pattern is composed of tokens, which are replaced by actual values when evaluated for a particular artifact or module. Those tokens are different from variables because they are replaced differently for each artifact, whereas variables are usually given the same value.

You can mix variables and tokens in a pattern:
${repository.dir}/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]

The tokens available depends on where the pattern is used (will it be evaluated with artifacts or modules, for instance).
But here are all the tokens currently available:

  • [organisation]
  • the organisation name

  • [module]
  • the module name

  • [branch]
  • the branch name

  • [revision]
  • the revision name

  • [artifact]
  • the artifact name (or id)

  • [type]
  • the artifact type

  • [ext]
  • the artifact file extension

  • [conf]
  • the configuration name

  • [originalname] (since 1.4)
  • the original artifact name (including the extension)

Difference between type and extension are explained in ivy file documentation.

since 1.2 [organization] can be used instead of [organisation].

since 1.3 Optinal parts can be used in patterns.
This let the possibility to avoid some input when a token is not defined, instead of having only the token as blank. Parenthesis are used to delimit the optional part, and only one token can be found inside the parenthesis.
So if you surround a token with '(' and ')', any other text which is between the parenthesis will be ignored if the token has no value.

For instance, suppose the pattern: "abc(def[type]ghi)"
type = "jar" -> the substituted pattern: abcdefjarghi
type = null or "" -> the substitued pattern: abc

A more real life example:
The pattern [artifact](-[revision]).[ext] let you accept both myartifact-1.0.jar when a revision is set, and myartifact.jar (instead of myartifact-.jar) when no revision is set
This is particularly useful when you need to keep control on artifact names.

since 1.4 Extra attributes can be used as any other token in the patterns.

Latest Strategy

Ivy often needs to know which revision between two has to be considered the "latest". For knowing that, it uses the concept of latest strategy. Indeed, there are several way to consider a revision to be the latest.
You can choose an existing one or plug your own.

But before knowing which revision is the latest, ivy needs to be able to consider several revision of a module. Thus ivy has to get a list of files in a directory, and it uses the dependency resolver for that. So check if the dependency resolver you use is compatible with latest revisions before wondering why ivy do not manage to get your latest revision.

Finally, In order to get several revisions of a module, most of the time you need to use the [revision] token in your pattern, so that ivy gets all the files which match the pattern whatever the revision is. It's only then that the latest strategy is used to determine which of this revisions is the latest one.

Ivy has three built-in latest strategies:

  • latest-time
  • it 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
  • it 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
  • : it compares the revisions as string, using lexicographic order (the one used by java string comparison).

See also how to configure new latest strategies here.

Conflict Manager

A conflict manager is able to select, among a list of module revisions in conflict, a list of revisions to keep.
Yes, it can selects a list of revision, even if most conflicts manager select only one revision.
But in some cases you will need to keep several revisions, and load in separate class loaders, for example.

A list of revisions is said to be in conflict if they correspond to the same module, i.e. the same organisation/module name couple.

The list of available conflict managers is available on the conflict manager configuration page.

To have more details on how to setup your conflict managers by module, see conflicts section in ivy file reference.

Pattern matcher

since 1.3
At several places Ivy let uses pattern to match a set of objects. For instance, you can exclude several modules at once when declaring a dependency by using a pattern matching all the modules to exclude.

Ivy uses pluggable pattern matcher to match those object names. 3 are defined by default:

  • exact
  • This matcher matches only string when they are equal to the pattern one

  • regexp
  • This matcher let you use regular expression as supported by the Pattern class of java 1.4 or greater

  • glob
  • This matcher let you use unix like glob matcher, i.e. where the only meta characters are * which matches any sequence of characters and ? which matches exactly one character. Note that this matcher is available only with jakarta oro 2.0.8 in your classpath.

Note also that with any matcher the character '*' has the special meaning of matching anything. This is particularly useful with default values which do not depend on the matcher.

Extra attributes

since 1.4
Several tags in ivy xml files are extensible with what is called extra attributes.
The idea is very simple: if you need some more information to define your modules, you can add the attribute you want and you will then be able to access it as any other attribute in your patterns for example.

Example:
Here is an ivy file with the attribute 'color' set to blue:

<ivy-module version="1.4">
<info organisation="jayasoft"
      module="foo"
      color="blue"
      status="integration"
      revision="1.59"
/>
</ivy-module>

Then you can use the extra attribute when you declare a dependency on foo:

<dependency org="jayasoft" name="foo" color="blue" rev="1.5+" />

And you can define your repository pattern as:

${repository.dir}/[organisation]/[module]/[color]/[revision]/[artifact].[ext]

Note that in order to use extra attributes, you will need to disable ivy file validation, since your files won't fulffill anymore the official ivy xsd. See the configuration doc page to see how to disable validation.

Checksums

since 1.4
Ivy allow to use checksums, also known as digester, to verify the correctness of a downloaded file.

For the moment Ivy supports md5 and sha1 algorithm.

The configuration of using md5 and/or sha1 can be done globally or by dependency resolver.
Globally, use the ivy.checksums variable to list the check to be done (only md5 and sha1 are supported).
On each resolver you can use the checksums attribute to override the global setting.

The setting is a comma separated list of checksum algorithm to use.
During checking (at download time), the first checksum found is checked, and that's all. This means that if you have a "sha1, md5" setting, then if ivy finds a sha1 file, it will compare the downloaded file sha1 against this sha1, and if the comparison is ok, it will assume the file is ok. If no sha1 file is found, it will look for a md5 file. If none is found no checking is done.
During publish, all listed checksum algorithms are computed and uploaded.

By default checksum algorithms are "sha1, md5".

If you want to change this default, you can set the variable ivy.checksums. Hence to disable checksum validation you just have to set ivy.checksums to "".

Events and Triggers

since 1.4
When Ivy performs the dependency resolution and some other tasks, it fires events before and after the most important steps. You can listen to these events using Ivy API, or you can even register a trigger to perform a particular action when a particular event occur.

This is a particularly powerful and flexible feature which allow for example to perform a build of a dependency just before it is resolved, or follow what's happening during the dependency resolution process accuratly, and so on.

For more details about event and triggers, see the triggers documentation page in the configuration section of this documentation.

Circular Dependencies

since 1.4
Circular dependencies can be either direct or indirect. For instance, if A depends on A it's a circular dependency, and if A depends on B which itself depends on A, this is also a circular dependency.

Prior to Ivy 1.4 circular dependencies where causing a failure in Ivy. As of Ivy 1.4, the behaviour of Ivy when it finds a circular dependency is configurable through a circular dependency strategy.

3 built-in strategies are available:

  • ignore
  • circular dependencies are only signaled in verbose messages

  • warn
  • same as ignore, except that they are signaled as warning (default)

  • error
  • halt the dependency resolution when a circular dependency is found.

See the configuration page to see how to configure the circular dependency strategy you want to use.

How does it work ?

Now that you have been introduced to main ivy terminology and concepts, it is time to give some explanations about how ivy works.

Usual cycle of modules between different locations


More details on ant tasks here.

Configure

Ivy needs to be configured to be able to resolve your dependencies. This configuration is usually done with a configuration file, which defines a set of dependency resolvers. Each resolver is able to find ivy files and / or artifacts, given simple information such as organition, module, revision, artifact name, artifact type and artifact extension.

The configuration is also responsible for indicating which resolver should be used to resolve which module. This configuration is dependent only on your environment, i.e. where the modules and artifacts can be found.

A default configuration is used by ivy when none is given. This configuration uses ivyrep to resolve all modules.

Resolve

The resolve time is the moment when ivy actually resolve the dependencies of one module. It first needs to access the ivy file of the module for which it resolves the dependencies.

Then, for each dependency declared in this file, it asks the appropriate resolver (according to configuration) to find the module (i.e. either an ivy file for it, or its artifacts if no ivy file can be found). It also uses a filesystem based cache to avoid asking for a dependency if it is already in cache (at least if possible, which is not the case with latest revisions).

If the resolver is a composite one (i.e. a chain or a dual resolver), several resolvers may actually be called to find the module.

When the dependency module has been found, its ivy file is downloaded to ivy cache. Then ivy checks if it has itself dependencies, in which case it recursilvely traverse the graph of dependencies.

All over this traversal, conflict management are done to prevent the access to a module as soon as possible.

When ivy has traversed the whole graph, it asks to the resolvers to download the artifacts corresponding to each dependencies which are not already in cache and which have not been evicted by conflict managers. All downloads are made to ivy cache.

Finally, an xml report is generated in cache, which allows ivy to easily know what are all the dependencies of the module, without traversing the graph again.

After this resolve step, two main steps are possible: either build a path with artifacts in cache, or copy them to another directory structure.

Retrieve

What is called retrieve in ivy is the fact to copy artifacts from the cache to another directory structure. This is done using a pattern, which indicates to ivy where the files should be copied.

For this, ivy uses the xml report in cache corresponding to the module it should retrieve to know which artifacts should be copied.

It also checks if the files are not already copied to maximize performances.

Building a path from cache

In some cases, it is preferable to use artifacts directly from the cache. Ivy is able to use the xml report generated at resolve time to build a path of all artifacts required.

This can be particularly useful especially when building plug-ins for IDE.

Reports

Ivy is also able to generate readable reports describing the dependencies resolution.

This is done with a simple xsl transformation of the xml report generated at resolve time.

Publish

Finally, Ivy can be used to publish a particular version of a module in your repository, so that it becomes available for futher resolve. This task is usually called either manually or from a continuous integration server for example.

Installation

There are basically two way to install Ivy. Either manually or automatically.

Manually

Download the version you want here, unpack the downloaded zip file wherever you want, and copy the ivy jar file in your ant lib directory (ANT_HOME/lib).

If you use ant 1.6.0 or superior, you can then simply go to the src/example/hello-ivy dir and run ant: if the build is successful, you have successfully installed Ivy !

If you use ant 1.5.1 or superior, you have to modify the build files in the examples:
- remove the namespace section at their head: xmlns:ivy="antlib:fr.jayasoft.ivy.ant"
- add taskdefs for ivy tasks:

  <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-publish" classname="fr.jayasoft.ivy.ant.IvyPublish"/> 

- replace ivy:xxx tasks by ivy-xxx
You can now run the build, if it is successful, you have successfully installed Ivy !

If the build is not successful, check the FAQ to see what can be the problem with the ivyrep resolver.

Automatically

If you want to use Ivy only in your ant build scripts, and have an internet connection when you build, you can download Ivy from this site and use the downloaded version automatically, using this simple build snippet:

    <property name="ivy.install.version" value="1.4-RC1" />

    <condition property="ivy.home" value="${env.IVY_HOME}">
        <isset property="env.IVY_HOME" />
    </condition>
    <property name="ivy.home" value="${user.home}/.ivy" />
    <property name="ivy.jar.dir" value="${ivy.home}/jars" />
    <property name="ivy.jar.file" value="${ivy.jar.dir}/ivy.jar" />

    <target name="download-ivy" unless="offline">
        <mkdir dir="${ivy.jar.dir}"/>
        <!-- download Ivy from web site so that it can be used even without any special installation -->
        <get src="http://www.jayasoft.org/downloads/ivy/${ivy.install.version}/ivy-${ivy.install.version}.jar"
            dest="${ivy.jar.file}" usetimestamp="true"/>
    </target>

    <target name="init-ivy" depends="download-ivy">
    <!-- try to load ivy here from ivy home, in case the user has not already dropped
              it into ant's lib dir (note that the latter copy will always take precedence).
              We will not fail as long as local lib dir exists (it may be empty) and
              ivy is in at least one of ant's lib dir or the local lib dir. -->
        <path id="ivy.lib.path">
            <fileset dir="${ivy.jar.dir}" includes="*.jar"/>
        </path>
        <taskdef resource="fr/jayasoft/ivy/ant/antlib.xml"
                uri="antlib:fr.jayasoft.ivy.ant" classpathref="ivy.lib.path"/>
    </target>

Then the only thing to do is to add the init-ivy target in the depends attribute of your targets using Ivy, and add ivy namespace to your build script. See the self contained go-ivy example for details about this.

Configuration

In order to work as you want, ivy need some configuration. Actually, ivy can work with no configuration at all, see the default configuration documentation for details about that. 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 :

<ivyconf>
        <properties file="${ivy.conf.dir}/ivyconf-file.properties" />
        <conf defaultCache="${cache.dir}" defaultResolver="ibiblio" checkUpToDate="false" />
        <resolvers>
                <ibiblio name="ibiblio" />
                <filesystem name="internal">
                        <ivy pattern="${repository.dir}/[module]/ivy-[revision].xml" />
                        <artifact pattern="${repository.dir}/[module]/[artifact]-[revision].[ext]" />
                </filesystem>
        </resolvers>
        <modules>
                <module organisation="jayasoft" name=".*" resolver="internal" />
        </modules>
</ivyconf>



Mainly, the configuration enables to configure the default cache directory used by ivy and the dependency resolvers that it will use to resolve dependencies.
Note: To work, this configuration file needs a property file named ivyconf-file.properties in the same directory as the configuration file, with ivy variables you want in it.

Some useful variables are available in ivyconf files:

since 1.4 Note that all java system properties are available as ivy variables in your configuration file.

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
    property
    properties
    conf
    include
    classpath
    typedef
    latest-strategies
    version-matchers
    triggers
    parsers
    conflict-managers
    outputters
    namespaces
        namespace
            rule
                fromsystem
                    src
                    dest
                tosystem
                    src
                    dest
    macrodef
        attribute
        any resolver
    resolvers
        any resolver
    modules
        module
    statuses
        status

ivyconf

Tag: ivyconf

Root tag of any ivyconf file.

Child elements

Element Description Cardinality
property set an ivy variable 0..n
properties loads a properties file as ivy variables 0..n
conf configures ivy with some defaults 0..1
include includes another ivyconf file 0..n
classpath add a location in the classpath used to load plugins 0..n
typedef defines new types in ivy 0..n
latest-strategies defines latest strategies 0..1
parsers defines module descriptor parsers 0..1
version-matchers defines new version matchers 0..1
triggers register triggers on ivy events 0..1
namespaces defines new namespaces 0..1
macrodef defines a new macro resolver 0..n
resolvers defines dependency resolvers 0..1
conflict-managers defines conflicts managers 0..1
modules defines rules between modules and dependency resolvers 0..1
outputters defines the list of available report outputters 0..1
statuses defines the list of available statuses 0..1

property

Tag: property

Defines an ivy variable. since 1.3

The optional override attribute enables to avoid overriding the previous value of the varable, which makes the definition behave like ant properties, which is particularly useful to define default values (values which are used only if they haven't been defined yet).

Attributes

Attribute Description Required
name the name of the variable to define Yes
value the new value the variable must take Yes
override true if the previous value (if any) of the variable should overriden, false otherwise No, defaults to true

Examples

<property name="myvar" value="myvalue"/>

Sets the variable myvar to the value myvalue.


<property name="myvar" value="myvalue" override="false"/>

Sets the variable myvar to the value myvalue only if myvar has not been set yet.

properties

Tag: properties

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

Attributes

AttributeDescriptionRequired
filea path to a properties file to load Yes
overrideindicates if the variable found in the properties file should override their previous value, if any since 1.3 No, defaults to true

conf

Tag: conf

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

Note that this is not related at all with conf found in ivy files. This tag is only used to setup ivy.

Default cache is used whenever a cache is not provided. It usually points to a directory in your filesystem. This should not point to a directory used as a repository!

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
defaultBranch the default branch to use for all modules, except if they have a module specific branch setting. since 1.4 No, defaults to no default branch
circularDependencyStrategy the name of the circular dependency strategy to use since 1.4 No, defaults to warn
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]
useRemoteConfig true to configure ivyrep and ibiblio resolver from a remote configuration file (updated with changes in those repository structure if any) (since 1.2) No, defaults to false

include

Tag: include

Includes another ivyconf file as if it were part of this one. since 1.3

The included ivyconf file has to be a complete well formed ivyconf file, i.e. it does have to include the <ivyconf> tag.

Attributes

Attribute Description Required
file a path to the ivyconf file to include Yes

Examples

<ivyconf>
  <property name="myrepository" value="path/to/my/real/rep"/>
  <conf defaultResolver="default"/>
  <include file="path/to/ivyconf-default.xml"/>
</ivyconf>

with ivyconf-default.xml:

<ivyconf>
  <property name="myrepository" value="path/to/rep" overwrite="false"/>
  <resolvers>
    <ivyrep name="default" ivyroot="${myrepository}"/>
  </resolvers>
</ivyconf>

The included ivyconf defines a resolver named default, which is an ivyrep resolver, with its root configured as being the value of myrepository variable. This variable is given the value path/to/rep in the included file, but because the attribute overwrite is set to false, it will not overide the value given in the main ivyconf including this one, so the value used for myrepository will be path/to/my/real/rep.


<ivyconf>
  <include file="ivyconf-macro.xml"/>
  <resolvers>
    <mymacro name="includeworks" mymainrep="included/myrep" mysecondrep="included/secondrep"/>
  </resolvers>
</ivyconf>

with ivyconf-macro.xml being the ivyconf example given on the macrodef documentation page.
This let reusing macro resolver easy.

classpath

Tag: classpath

Includes a jar in the classpath used to load plugins. since 1.4

This let you add ivy plugins without relying on ant classpath for instance, easing therefore the use of ivy in multiple execution environment (ant, standalone, IDE plugins, ...).

Attributes

Attribute Description Required
url the url of a jar to add to the classpath Yes, unless file is specified
file a jar to add to the classpath Yes, unless url is specified

Examples

<ivyconf>
  <classpath file="${ivy.conf.dir}/custom-resolver.jar"/>
  <typedef name="custom" classname="fr.jayasoft.ivy.resolver.CustomResolver"/>
  <resolvers>
    <custom name="custom"/>
  </resolvers>
</ivyconf>

Adds custom-resolver.jar found in the same directory as the ivyconf.xml file itself to the classpath, then define a custom resolver and use it.


<ivyconf>
  <classpath url="http://www.myserver.com/ivy/custom-resolver.jar"/>
  <typedef name="custom" classname="fr.jayasoft.ivy.resolver.CustomResolver"/>
  <resolvers>
    <custom name="custom"/>
  </resolvers>
</ivyconf>

Same as above, but find the jar on a web server.

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

AttributeDescriptionRequired
namethe name of the type to define. This name is then used as an xml tag. Yes
classnamethe 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

latest-revision

since 1.4 The latest-revision can now be configured to handle more words with special meanings than the one defined in php version_compare function.

Here is an example of how you can do so:

<latest-strategies>
  <latest-revision name="mylatest-revision">
    <specialMeaning name="PRE" value="-2"/>
    <specialMeaning name="QA" value="4"/>
    <specialMeaning name="PROD" value="5"/>
  </latest-revision>
</latest-strategies>

Knowing that the default special meaning words are the following:

    <specialMeaning name="dev" value="-1"/>
    <specialMeaning name="rc" value="1"/>
    <specialMeaning name="final" value="2"/>

You can even get rid or redefine the default special meanings by setting usedefaultspecialmeanings="false" on the latest-revision tag.
Example:

<latest-strategies>
  <latest-revision name="mylatest-revision" usedefaultspecialmeanings="false">
    <specialMeaning name="pre" value="-2"/>
    <specialMeaning name="m" value="1"/>
    <specialMeaning name="rc" value="2"/>
    <specialMeaning name="prod" value="3"/>
  </latest-revision>
</latest-strategies>

parsers

Tag: parsers

Defines a list of module descriptor parsers usable in ivy. Each parser defines which resources (which descriptor file) it accepts.
The child tag used for the parser must be equal to a name of a parser type (added with the typedef tag).

Note that when looking for a parser, ivy queries the parsers list in the reverse order. So the last parser in the list will be queried first. Consequently, if the last parser accepts all resources, the other parsers will never have a chance to parse the resource.

Two parsers are available by default and thus do not need to be declared in this section:

  • ivy file parser
  • this is the parser used for ivy xml files. This parser is used for resources that aren't accepted by any other parser.

  • pom parser
  • this parser is able to parse maven2 pom files

Child elements

Element Description Cardinality
any module descriptor parser adds a module descriptor parser to the list of available parsers 0..n

namespaces

Tag: namespaces

Namespaces are an advanced feature of Ivy which let you use resolvers in which module names and organisations are not consistent between each other.

For instance, if you want to use maven2 repository and ivyrep collectively, you will face some naming issues. For example all apache commons projects are declared to be part of the organisation apache in ivyrep whereas in maven2 ibiblio repository, they are declared to be part of the organisation of the same name of the module.

So if you try to use both maven2 and ivyrep repositories, you will face some issues like:

How do I declare a dependency on commons-lang ?
I have an error while trying to resolve module xxx. It says that it depends on [commons-httpclient commons-httpclient] ant that it isn't available.
...

Ivy has an answer to give to this kind of troubles, and this answer is called namespaces. In short, you can affect a namespace to each dependency resolver in Ivy, and each namespace defines rules to convert names from the system namespace to the defined namespace itself, and vice versa.

This very powerful feature is thoroughly used in the build your own repository tutorial, and this is a good place to have examples of what can be done with namespaces.

Child elements

Element Description Cardinality
namespace defines a new namespace 0..n

namespace

Tag: namespace

Defines a new namespace. A namespace is identified by a name, which is used to reference the namespace in the resolvers using the namespace.

Namespaces overview is given in the namespaces documentation.

A namespace mainly consists of a list of rules, each rule defining a translation between system namespace and the defined namespace, and vice versa.

There are two main possibilities for using these rules. By default, a namespace iterate through the rules, and when it finds one that translate the given name, it returns the translated name. But the namespace can be configured to do use the list as a translator chain: in this case, all rules are applied in order, the result of the first rule translation being passed to the second, and so on.

Attributes

Attribute Description Required
name the namespace name Yes
chainrules true to indicate that namespaces rules should be chained, false otherwise No, defaults to false

Child elements

Element Description Cardinality
rule defines a new namespace rule 0..n

Example

<namespace name="test">
  <rule>
    <fromsystem>
      <src org="systemorg"/>
      <dest org="A"/>
    </fromsystem>
    <tosystem>
      <src org="A"/>
      <dest org="systemorg"/>
    </tosystem>
  </rule>
</namespace>
<namespace name="test">
  <rule>
    <fromsystem>
      <src org="systemorg2" module="system\-(.+)"/>
      <dest org="B" module="$m1"/>
    </fromsystem>
    <tosystem>
      <src org="B" module=".+"/>
      <dest org="systemorg2" module="system-$m0"/>
    </tosystem>
  </rule>
</namespace>
<namespace name="test" chainrules="true">
  <rule>
    <fromsystem>
      <src org="systemorg"/>
      <dest org="A"/>
    </fromsystem>
    <tosystem>
      <src org="A"/>
      <dest org="systemorg"/>
    </tosystem>
  </rule>
  <rule>
    <fromsystem>
      <src module="systemmod"/>
      <dest module="A"/>
    </fromsystem>
    <tosystem>
      <src module="A"/>
      <dest module="systemmod"/>
    </tosystem>
  </rule>
  <rule>
    <fromsystem>
      <src module="systemmod2"/>
      <dest module="B"/>
    </fromsystem>
    <tosystem>
      <src module="B"/>
      <dest module="systemmod2"/>
    </tosystem>
  </rule>
</namespace>

rule

Tag: rule

Defines a new namespace rule. A rule defines a translation between system namespace and the defined namespace, and vice versa.

See namespace doc for details.

Child elements

Element Description Cardinality
fromsystem defines the translation to apply from system namespace to the defined namespace 1
tosystem defines the translation to apply from the defined namespace to system namespace 1

fromsystem / tosystem

Tag: fromsystem / tosystem

Defines a one way translation rule, i.e. a translation from system namespace to the defined namespace or vice versa.

Child elements

Element Description Cardinality
src defines a source name which can be accepted 1..n
dest defines the translation to apply when a name is accepted by an src pattern 1

src

Tag: src

Defines the acceptation part of a translation rule. If a name matches this src, it will be translated using the dest part.

Attributes

Attribute Description Required
org the organisation to match as a regexp No, defaults to .*
module the module name to match as a regexp No, defaults to .*
rev the revision to match as a regexp No, defaults to .*

dest

Tag: dest

Defines the translation part of a translation rule. If a name has matched a corresponding src, it will be translated using this dest part.

The new names can contain references to groups of the matched name, using a slightly modified regexp syntax. Indeed, referenced groups can be part of either the organisation, module or revision part of the original name. So, to reference the groups, you just have to add a letter identifying the part in which the group should be selected: o for organisation, m for module, and r for revision.

For instance, $o0 matches the whole matched organisation, and $m0 the whole matched module name. $o1 matches the first group of the matched organisation.

For details about regexp and groups, see the Pattern class documentation in the jdk.

Attributes

Attribute Description Required
org the new organisation name No, defaults to $o0
module the new module name No, defaults to $m0
rev the new revision No, defaults to $r0

Examples

    <fromsystem>
      <src org="systemorg2" module="system\-(.+)"/>
      <dest org="B" module="$m1"/>
    </fromsystem>

Matches modules from systemorg2 which have a name beginning with system followed by a minus and anything else, and translate it to organisation B and module the part following system- of the original name.

macrodef

Tag: macrodef

Defines a new dependency resolver type based upon an other one. This definition is very similar to the macrodef feature of ant for defining macro tasks. since 1.3

This task eases the lot the process of creating new dependency resolver, because it avoid writing java code.

It is generally used in combination with the include feature to help reusing macro at several places.

A macro is defined by writing the resolver it is equivalent to as if it were written in the resolver place, except that you can use attributes to pass parameters to the newly defined resolver type. Attributes are defined with a name and sometimes a default value, and are used using the following syntax: @{attributename}.

Attributes

Attribute Description Required
name name of the resover type created Yes

Child elements

Element Description Cardinality
attribute defines an attribute for the macro resolver 0..n
any resolver defines the base resolver upon which this macro is defined 1

Examples

Defining a simple macro:

  <macrodef name="mymacro">
    <attribute name="mymainrep"/>
      <filesystem name="fs1">
        <ivy pattern="@{mymainrep}/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
        <artifact pattern="@{mymainrep}/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
      </filesystem>
  </macrodef>

Using it:

  <resolvers>
    <mymacro name="default" mymainrep="path/to/myrep"/>
  </resolvers>



A complete example:

<ivyconf>
  <macrodef name="mymacro">
    <attribute name="mymainrep"/>
    <attribute name="mysecondrep"/>
    <attribute name="myseconddirlayout" default="[organisation]/[module]/[type]s"/>
    <chain>
      <filesystem name="fs1">
        <ivy pattern="@{mymainrep}/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
        <artifact pattern="@{mymainrep}/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
      </filesystem>
      <filesystem name="fs2" latest="latest-time">
        <ivy pattern="@{mysecondrep}/@{myseconddirlayout}/ivy-[revision].xml"/>
        <artifact pattern="@{mysecondrep}/@{myseconddirlayout}/[artifact]-[revision].[ext]"/>
      </filesystem>
    </chain>
  </macrodef>

  <resolvers>
    <mymacro name="default" mymainrep="path/to/myrep" mysecondrep="path/to/secondrep"/>
    <mymacro name="other"
      mymainrep="path/to/myrep"
      mysecondrep="path/to/secondrep"
      myseconddirlayout="[module]/[type]s"/>
  </resolvers>
</ivyconf>

attribute

Tag: attribute

Defines a macrodef attribute. See macrodef for details.

Attributes

Attribute Description Required
name the name of the attribute Yes
default the default value of the attribute if none is specified No, by default attribute are required

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

since 1.3 Once defined, resolvers can be referenced by their name, using the following syntax:

<resolver ref="alreadydefinedresolver"/>

Note that this works only if the resolver has been already defined, and not if it is defined later in the ivyconf file.

Child elements

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

Built-in Resolvers

Ivy comes with a set of built-in dependency resolvers able to answer to the most common needs.

If you don't find the one you want here, you can also check if some one has not contributed it in the links page, or even write your own.

There are basically two types of resolver in Ivy: composite and standard resolvers. A composite resolver is a resolver which delegates the work to other resolvers. The other resolvers are standard resolvers.

Here is the list of built-in resolvers:

Name Type Description
IvyRep Standard Finds ivy files on ivyrep and artifacts on ibiblio.
IBiblio Standard Finds artifacts on ibiblio.
FileSystem Standard This very performant resolver finds ivy files and artifacts in your file system.
Url Standard Finds ivy files and artifacts in any repository accessible with urls.
Vfs Standard Finds ivy files and artifacts in any repository accessible with apache commons vfs.
ssh Standard Finds ivy files and artifacts in any repository accessible with ssh.
sftp Standard Finds ivy files and artifacts in any repository accessible with sftp.
Chain Composite Delegates the finding to a chain of sub resolvers.
Dual Composite Delegates the finding of ivy files to one resolver and of artifacts to another.

Common attributes

All resolvers of the same type share some common attributes detailed here:

Attribute Description Required Composite Standard
name the name which identify the resolver Yes Yes Yes
validate indicates if resolved ivy files should be validated against ivy xsd No, defaults to call setting Yes Yes
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} No Yes
changingPattern Indicates for which revision pattern this resolver should check lastmodified date to know if an artifact file is up to date. since 1.4 No, defaults to none Yes Yes
changingMatcher The name of the pattern matcher to use to match a revision against the configured changingPattern. since 1.4 No, defaults to exactOrRegexp Yes Yes
alwaysCheckExactRevision Indicates if this resolver should check the given revision even if it's a special one (like latest.integration). since 1.3 No, defaults to ${ivy.default.always.check.exact.revision} No Yes
namespace The name of the namespace to which this resolver belong since 1.3 No, defaults to 'system' Yes Yes
checkconsistency true to check consistency of module descriptors found by this resolver, false to avoid consistency check since 1.3 No, defaults to true No Yes
allownomd true if the absence of module descriptor (usually an ivy file) is authorised for this resolver, false to refuse modules without module descriptor since 1.4 No, defaults to true No (except dual) Yes
checksums a comma separated list of checksum algorithms to use both for publication and checking since 1.4 No, defaults to ${ivy.checksums} No Yes
latest The name of the latest strategy to use. No, defaults to 'default' Yes Yes

Examples

<resolvers>
  <filesystem name="1">
    <ivy pattern="${ivy.conf.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
    <artifact pattern="${ivy.conf.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
  </filesystem>
  <chain name="chain1">
    <resolver ref="1"/>
    <ivyrep name="ivyrep"/>
  </chain>
  <chain name="chain2" returnFirst="true" dual="true">
    <resolver ref="1"/>
    <ibiblio name="ibiblio"/>
  </chain>
</resolvers>

Defines a filesystem resolver, named '1', which is then used in two chains, the first which seconds the filesystem resolver with an ivyrep resolver, and second which seconds the filesystem resolver with an ibiblio resolver, and which returns the first module found, and uses the whole chain to download artifacts (see corresponding resolvers documentation for details about them).

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 usually better to use this resolver instead of ibiblio one, which is provided mainly for compatibility reasons.

Attributes

This resolver shares the common attributes of standard resolvers.

Attribute Description Required
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}

Examples

<ivyrep name="ivyrep" />

A default ivyrep resolver, looking for ivy files on ivyrep and artifacts on ibiblio.


<ivyrep name="ivyrep" ivyroot="http://ivyrep.mycompany.com"/>

Looks for ivy files on and ivyrep like web site located at http://ivyrep.mycompany.com.

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.

since 1.3 Using the m2compatible attribute, you can benefit from maven 2 repository compatibility (convert dots in organisation in slashes, search for poms, use transitive dependencies of poms). This setting also affects the default place where the resolver look for its artifacts to point to the maven2 repository. So setting this attribute to true is sufficient to use maven 2 ibiblio repository.

since 1.4 When using the m2compatible flag, you can disable the use of poms by setting the usepoms flag to false. It is then roughly equivalent to an url resolver configured like this:

<url name="test" m2compatible="true">
  <artifact pattern="http://www.ibiblio.org/maven2/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
</url>

Attributes

This resolver shares the common attributes of standard resolvers.

Attribute Description Required
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}
m2compatible True if this resolver should be maven2 compatible, false otherwise since 1.3 No, defaults to false
usepoms True if this resolver should use maven poms when it is already in m2compatible mode, false otherwise since 1.4 No, defaults to true

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.

since 1.3 Using the m2compatible attribute, this resolver will convert dots found in organisation in slashes like maven2 does for groupId. For instance, it will transform the organisation from 'com.company' into 'com/company' when replacing the token [organisation] in your pattern.

Attributes

This resolver shares the common attributes of standard resolvers.

Attribute Description Required
m2compatible True if this resolver should be maven2 compatible, false otherwise since 1.3 No, defaults to false
local True if this resolver should be considered local, false otherwise since 1.4. See useOrigin attribute on the resolve task for details. No, defaults to true

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

This resolver shares the common attributes of standard resolvers.

Attribute Description Required
m2compatible True if this resolver should be maven2 compatible, false otherwise since 1.3 No, defaults to false

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

Example

<url name="two-patterns-example">
  <ivy pattern="http://ivyrep.mycompany.com/[module]/[revision]/ivy-[revision].xml" />
  <artifact pattern="http://ivyrep.mycompany.com/[module]/[revision]/[artifact]-[revision].[ext]" />
  <artifact pattern="http://ivyrep.mycompany.com/[module]/[revision]/[artifact].[ext]" />
</url>

Looks for ivy files in one place and for artifacts in two places: with or without revision in name (revision being already in the directory structure).

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

This resolver shares the common attributes of composite resolvers.

Attribute Description Required
returnFirst true if the first found should be returned. No, defaults to false
dual true if the chain should behave like a dual chain. since 1.3 No, defaults to false

Child elements

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

Examples

<chain name="test">
  <filesystem name="1">
    <ivy pattern="${ivy.conf.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
    <artifact pattern="${ivy.conf.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
  </filesystem>
  <ivyrep name="2"/>
</chain>

Both a filesystem and ivyrep will be used to look for ivy files. If a dynamic revision is required, then both the filesystem and ivyrep will be queried to find the most recent revision among the two resolvers. Once the most recent revision is found in one resolver, it's the same resolver which will be used to download artifacts.


<chain name="test" returnFirst="true">
  <filesystem name="1">
    <ivy pattern="${ivy.conf.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
    <artifact pattern="${ivy.conf.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
  </filesystem>
  <ivyrep name="2"/>
</chain>

Same as before, except that if a revision is found in the filesystem then ivyrep will not be queried: its the filesystem which will be used for both the ivy file and the artifacts.


<chain name="test" dual="true">
  <filesystem name="1">
    <ivy pattern="${ivy.conf.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
    <artifact pattern="${ivy.conf.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
  </filesystem>
  <ivyrep name="2"/>
</chain>

Same as first example, except that once a module is found by either filesystem or ivyrep, then it's the whole chain which will be queried to download the artifacts. So in this case ivy file and artifacts may be split across the two resolvers for the same module.

Dual resolver

Tagdual
Handle latestdepends on sub resolvers
Handle publishdelegates 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

This resolver shares the common attributes of composite resolvers.
AttributeDescriptionRequired
allownomdtrue if the absence of module descriptor (usually an ivy file) is authorised for this resolver, false to refuse modules without module descriptor since 1.4 No, defaults to true

Child elements

ElementDescriptionCardinality
any resolvertwo resolvers, the first being the ivy resolver, the second the artifact resolver 2

sftp resolver

Tag sftp
Handle latest yes
Handle publish yes



This resolver can be used when your ivy repository is located on a server accessible via sftp. The secured nature of sftp and its wide spread implementation on most *nix servers makes this resolver a very good candidate in an enterprise environment. since 1.4

If your server supports ssh but not sftp, there is also an ssh resolver.

Note that sftp is also supported by vfs, so you can use a vfs resolver instead. The advantage of this resolver is that you have a better control over authentication, it can prompt for username/password credentials, or you can use private/public key authentication, which is not possible with the vfs resolver. When it prompts for username/password, it uses a Swing dialog, which is not possible in a headless environment. If you want to prompt for the credentials on the command line, use ant input task for example before calling ivy.

All necessary connection parameters can be set here via attributes.
However all attributes defined in the pattern url of the resolver will have higher priority and will overwrite the values given here. To specify connection parameters in the pattern, you have to specify a full url and not just a path as pattern.
e.g. pattern="/path/to/my/repos/[artifact].[ext]" will use all connection parameters from this class
e.g. pattern="sftp://myserver.com/path/to/my/repos/[artifact].[ext]" will use all parameters from the attributes with the exception of the host, which will be "myserver.com"
e.g. pattern="sftp://user:geheim@myserver.com:8022/path/to/my/repos/[artifact].[ext]" will use only the keyFile and keyFilePassword from the attributes (if needed). Rest will come from the url.

Note that the authentication features of this resolver are exactly the same as the ssh resolver. Choosing between the two is often a matter of server implementation. If your server supports sftp, usually it's preferrable.

Internally this resolver relies on jsch as ssh client, which is a popular java ssh client, used for example in eclipse.

Attributes

This resolver shares the common attributes of standard resolvers.

Attribute Description Required
user The username to provide as credential No, defaults to username given on the patterns, or prompt if none is set
userPassword The password to provide as credential No, defaults to password given on the patterns, or prompt if none is set
keyFile Path to the keyfile to use for authentication No, defaults to username/password authentication
keyFilePassword the password used to protect the key file No, will prompt for password if keyFile authentication is used and if it is password encrypted
host The host to connect to No, defaults to host given on the patterns, fail if none is set
port The port to connect to No, defaults to 22

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

Example

<sftp user="myuser" host="myhost.com">
  <ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
  <artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
</sftp>

Will connect to myhost.com using myuser and prompt for the password.


<sftp user="${myuser}" userPassword="${my.password}" host="myhost.com">
  <ivy pattern="path/to/ivy/[module]/ivy.xml"/>
  <artifact pattern="path/to/[organisation]/[module]/[artifact].[ext]"/>
</sftp>

Will connect to myhost.com using user and password provided with ivy variables.


<sftp>
  <ivy pattern="sftp://user:geheim@yourserver.com:8022/path/to/repos/[module]/[revision]/ivy.xml"/>
  <artifact pattern="sftp://user:secret@myserver.com:8022/path/to/my/repos/[artifact].[ext]"/>
</sftp>

Will connect to yourserver.com on port 8022 with user 'user' and password 'geheim' for authentication for ivy files, and to myserver.com on port 8022 using user 'user' and password 'secret' for the artifacts.


<sftp keyFile="path/to/key/file" keyFilePassword="${password}">
  <ivy pattern="sftp://user@yourserver.com:8022/path/to/repos/[module]/[revision]/ivy.xml"/>
  <artifact pattern="sftp://user@myserver.com:8022/path/to/my/repos/[artifact].[ext]"/>
</sftp>

Will connect to yourserver.com on port 8022 with user 'user' and use keyFile path/to/key/file for keyFile and the value of password variable for keyFilePassword authentication for ivy files, and to myserver.com on port 8022 using user 'user' with the same keyFile/keyFilePassword pair for the artifacts.

ssh resolver

Tag ssh
Handle latest yes
Handle publish yes



This resolver can be used when your ivy repository is located on a server accessible via ssh. The secured nature of ssh and its wide spread implementation on most *nix servers makes this resolver a very good candidate in an enterprise environment. since 1.4

If your server supports sftp, you can consider using the sftp resolver.

Internally this resolver shares most of its behaviour with the sftp resolver, so refer to its documentation for details.

Attributes

This resolver shares the common attributes of standard resolvers.

Attribute Description Required
user The username to provide as credential No, defaults to username given on the patterns, or prompt if none is set
userPassword The password to provide as credential No, defaults to password given on the patterns, or prompt if none is set
keyFile Path to the keyfile to use for authentication No, defaults to username/password authentication
keyFilePassword the password used to protect the key file No, will prompt for password if keyFile authentication is used and if it is password encrypted
host The host to connect to No, defaults to host given on the patterns, fail if none is set
port The port to connect to No, defaults to 22

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

Example

<ssh user="myuser" host="myhost.com">
  <ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
  <artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
</ssh>

Will connect to myhost.com using myuser and prompt for the password.


<ssh keyFile="path/to/key/file" keyFilePassword="${password}">
  <ivy pattern="ssh://user:geheim@yourserver.com:8022/path/to/repos/[module]/[revision]/ivy.xml"/>
  <artifact pattern="ssh://user:geheim@myserver.com:8022/path/to/my/repos/[artifact].[ext]"/>
</ssh>

Will connect to yourserver.com on port 8022 with user geheim and use keyFile path/to/key/file for keyFile and the value of password variable for keyFilePassword authentication for ivy files, and to myserver.com on port 8022 using user geheim with the same keyFile/keyFilePassword pair for the artifacts.

vfs

Tag vfs
Handle latest depend on vfs capacity, usually yes
Handle publish depend on vfs capacity, usually yes



This resolver is certainly the most capable, since it relies on Apache commons VFS, which gives an uniform access to a good number of file systems, including ftp, webdav, zip, ... since 1.4

Note: commons vfs has not released a stable version yet, hence Ivy relies on a nightly build. Stability should thus be considered carefully before using this resolver in a production environment

Attributes

This resolver shares the common attributes of standard resolvers.

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

Example

<vfs name="vfs-resolver">
  <ivy pattern="sftp://username:password@host/[organisation]/[module]/[revision]/ivy.xml" />
  <artifact pattern="sftp://username:password@host/[organisation]/[module]/[revision]/[artifact].[ext]" />
</vfs>

Access ivy and artifacts files using sftp.

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.

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

  • strict
  • this conflict manager throws an exception (i.e. causes a build failure) whenever a conflict is found.

The two "latest" conflict managers also take into account the force attribute of the dependencies.
Indeed direct dependencies can declare a force attribute (see dependency), which indicates the the revision given in the direct dependency should be prefered over indirect dependencies.

Here is a list of conflict manager types available, which can be used to define your own custom conflict managers:

  • latest-cm
  • The latest conflict manager uses a latest strategy to select the latest revision among several ones. Both latest-time and latest-revision conflict managers are based on this conflict manager type. It takes 'latest' as attribute to define which latest strategy should be used. Example:
    <latest-cm name="mylatest-conflict-manager" latest="my-latest-strategy"/>

  • regexp-cm
  • This conflict manager is based on a regular expression and throw an exception (i.e. causes a build failure) when a conflict is found with versions with different matching group. For instance if a conflict is found between 1.2.x and 1.3.y it will throw an exception if the regular exception is (.*)\.\d, because the matching group will match different string (1.2 and 1.3). 1.2.1 and 1.2.2 won't throw an exception with the same regular expression. The regular expression is set using the 'regexp' attribute. A 'ignoreNonMatching' attribute can also be set to simply warrn when a version is found which does not match the regular expression, instead of throwing an exception.

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 per module or module set settings.

The rules are given by defining a module set, using pattern for module organisation and name, and giving some settings for the set, like the name of the corresponding resolver to use.

If no rule match a given module, the default setting will be used.

Even if not required, because the use of a default big resolver (chain, for instance) able to resolve all dependencies can answer all the needs, the configuration of smaller resolvers used for different cases can improve performances a lot. For instance, if you have a local repository for your modules and a distant repository for third party libraries, it is a good idea to have two separate resolvers, and configure ivy to use one for all your modules and another for the rest (the default one).

Child elements

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

module

Tag: module

Define a module set rule. The tag defines a module set, by giving an expression and the matcher to use for organisation and name (for instance, you can use * to specify all).

It also gives the specific setting to use for this module set.

For each module set, you can configure:

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
matcher the matcher to use to match the modules to which the resolver should be applied since 1.3 No, defaults to exactOrRegexp in pre 1.3 ivy files, and exact in 1.3 and superior
resolver the name of the resolver to apply. The resolver must have been defined in the resolvers section of the configuration file. No
conflict-manager the name of the conflict manager to apply. since 1.4 No
branch the default branch to apply. since 1.4 No

Examples

<modules>
  <module organisation="jayasoft" name="*" resolver="myprojectsresolver"/>
</modules>

Uses myprojectresolver for all modules from jayasoft.


<modules>
  <module organisation="apache" name="commons-*" matcher="glob" resolver="myapachecommonsresolver"/>
</modules>

Uses myapachecommonsresolver for all modules beginning by commons- from apache.


<modules>
  <module organisation="apache" name="commons-[a-z]+" matcher="regexp" resolver="myapachecommonsresolver"/>
</modules>

Uses myapachecommonsresolver for all modules from apache beginning by commons- followed by any number of alphabetic lowercase characters.


<modules>
  <module organisation="jayasoft" name="ivy*" matcher="glob" conflict-manager="latest-time"/>
</modules>

Uses latest-time conflict manager for all modules from jayasoft which name begins with ivy.


<modules>
  <module organisation="jayasoft" name="ivy*" matcher="glob" branch="fix-103"/>
</modules>

Uses 'fix-103' as default branch for all modules from jayasoft which name begins with ivy.

outputters

Tag: outputters

Defines a list of report outputters usable in ivy.

A report outputter is used at the end of the resolve process to generate a report of how the resolve has been performed.

Two report outputters are registered by default:

  • a log report outputter (LogReportOutputter)
  • which produces the output on the console at the end of the resolve, which looks like this:

            ---------------------------------------------------------------------
            |                  |            modules            ||  artifacts  |
            |      conf      | number| search|dwnlded|evicted|| number|dwnlded|
            ---------------------------------------------------------------------
            |      default    |  1  |  1  |  0  |  0  ||  1  |  1  |
            ---------------------------------------------------------------------
  • an xml report outputter (XmlReportOutputter)
  • which produces an xml report in the cache, which is mandatory for correct Ivy behaviour, since it's that report which is used when you do a post resolve step in a separate buid from the resolve itself. It's also this xml report which is processed to generate all the different reports available in the report task.

The child tag used for the parser must be equal to a name of a report outputter type (added with the typedef tag).

To see how to define your own report outputter see Extending Ivy documentation

Child elements

Element Description Cardinality
any report outputter adds a report outputter to the list of available ones 0..n

statuses

Tag: statuses

Defines the list of available statuses. since 1.4

By default, ivy has 3 statuses: release, milestone and integration. By adding a statuses section to your ivyconf file, you define the statuses you want to use. Note that in this case if you still want to have ivy default statuses you will have to declare them.

The integration property on each status is only used for recursive delivery, an integration dependency being delivered if the caller is not in integration state itself.

The default status is the one used when none is defined in a module descriptor. If not specified, it defaults to the last defined status.

The statuses order is important, the first is considered the more mature, the last the less mature. This is used to know if a status is compatible with a latest. version matcher.

Attributes

Attribute Description Required
default the name of the status to use when none is declared in an ivy file No, defaults to the last status declared

Child elements

Element Description Cardinality
status defines a new status 0..n

Examples

<statuses default="bronze">
  <status name="gold" integration="false"/>
  <status name="silver" integration="false"/>
  <status name="bronze" integration="true"/>
</statuses>

Defines 3 statuses, gold, silver and bronze. The default status used when none is declared in an ivy file will be bronze.
It is also considered as an integration status, and thus doesn't trigger any recrusive delivery.

status

Tag: status

Define one available module status.

See statuses page for details about how statuses are defined.

Attributes

Attribute Description Required
name name of status defined Yes
integration true if this is an integration status, false otherwise No, defaults to false

triggers

Tag: triggers
since 1.4

Defines a list of triggers to activate on some Ivy events.

A trigger is an action which is performed whenever a particular event occurs.
Ivy supports two type of triggers out of the box: ant-call and ant-build. The first calls a target in the same build as the original one whenever a particular event occurs, the second call an ant build which may be in another ant build script.

If you want to use a different trigger, you can implement your own.

The event available in Ivy are the following ones:

Name Attributes Description
pre-resolve
  • organisation
  • the organisation of the module for which the dependencies will be resolved

  • module
  • the name of the module for which the dependencies will be resolved

  • revision
  • the revision of the module for which the dependencies will be resolved

  • conf
  • comma separated list of configurations which will be resolved

Fired before a module dependencies will be resolved
pre-resolve-dependency
  • organisation
  • the organisation of the dependency resolved

  • module
  • the name of the dependency resolved

  • revision
  • the revision asked for the dependency

  • resolver
  • the name of the resolver used to resolve the dependency

Fired before each dependency is resolved in a single resolve call
post-resolve-dependency
  • organisation
  • the organisation of the dependency resolved

  • module
  • the name of the dependency resolved

  • revision
  • the revision of the dependency resolved, or the revision asked if the resolution was not successful

  • resolved
  • true if the resolution was successful, false otherwise

  • resolver
  • the name of the resolver used to resolve the dependency

Fired after each dependency resolved in a single resolve call
post-resolve
  • organisation
  • the organisation of the module for which the dependencies have been resolved

  • module
  • the name of the module for which the dependencies have been resolved

  • revision
  • the revision of the module for which the dependencies have been resolved

  • conf
  • comma separated list of configurations resolved

Fired after a module dependencies has been resolved
pre-download-artifact
  • organisation
  • the organisation of the artifact which is about to be downloaded

  • module
  • the name of the module of the artifact which is about to be downloaded

  • revision
  • the revision of the the artifact which is about to be downloaded

  • artifact
  • the name of the the artifact which is about to be downloaded

  • type
  • the type of the the artifact which is about to be downloaded

  • ext
  • the extension of the the artifact which is about to be downloaded

  • resolver
  • the name of the resolver used to download the artifact

  • origin
  • the origin location from which it will be downloaded

  • local
  • true if it's a local artifact, false otherwise

Fired before an artifact is downloaded from a repository to the cache
post-download-artifact
  • organisation
  • the organisation of the artifact which was just downloaded

  • module
  • the name of the module of the artifact which was just downloaded

  • revision
  • the revision of the the artifact which was just downloaded

  • artifact
  • the name of the the artifact which was just downloaded

  • type
  • the type of the the artifact which was just downloaded

  • ext
  • the extension of the the artifact which was just downloaded

  • resolver
  • the name of the resolver used to download the artifact

  • origin
  • the origin location from which it was downloaded

  • local
  • true if it's a local artifact, false otherwise

  • size
  • the size in bytes of the downloaded artifact

  • file
  • the file to which it has been downloaded

Fired after an artifact has been downloaded from a repository to the cache

The child tag used for the dependency resolver must be equal to a name of a trigger type (either built-in or added with the typedef tag).

Child elements

Element Description Cardinality
any trigger adds a trigger to the list of registered triggers 1..n

Built-in Triggers

Ivy comes with two built-in triggers:

Name Description
ant-build Triggers an ant build.
ant-call Calls a target in the current ant build.

Common attributes

All triggers share some common attributes detailed here.

Among these attributes, you will find how to select when the trigger should be performed. You have to provide an event name, which is simple, but you can also use a filter expression. The syntax for this expression is very simple and limited:
you can use the = operator to compare an attribute (left operande) with a value (right operande).
you can use AND OR NOT as boolean operators
you cannot use parenthesis to change the precedence

Attribute Description Required
name the name of the trigger for identification purpose only Yes
event the name of the event on which the trigger should be performed Yes
filter a filter expression used to restrict when the trigger should be performed No, defaults to no filter

Examples

<triggers>
    <ant-build antfile="${ivy.conf.dir}/[module]/build.xml" target="publish"
          event="pre-resolve-dependency" filter="revision=latest.integration"/>
</triggers>

Triggers an ant build of the ant file ${ivy.conf.dir}/[module]/build.xml (where [module] is replaced by the name of the dependency resolved) with the target "publish", just before resolving a dependency with a latest.integration revision.


<triggers>
    <ant-call target="unzip" prefix="dep"
          event="post-download-artifact" filter="type=zip AND status=successful"/>
</triggers>

Triggers an ant call of the target unzip just after downloading a zip artifact, prefixing all parameters to the target with 'dep'.
Here is how the target can look like:

<target name="unzip">
    <echo>
        unzipping artifact:
        organisation=${dep.organisation}
        module=${dep.module}
        revision=${dep.revision}
        artifact=${dep.artifact}
        type=${dep.type}
        ext=${dep.ext}
        origin=${dep.origin}
        local=${dep.local}
        size=${dep.size}
        file=${dep.file}
    </echo>
    <mkdir dir="${basedir}/out"/>
    <unzip src="${dep.file}" dest="${basedir}/out"/>
</target>

version-matchers

Tag: version-matchers

Defines a list of version matchers. since 1.4

The child tag used for the version matcher must be equal to a name of a report outputter type (added with the typedef tag).

A version matcher is used to evaluate if a a dependency version contraint matches a dependency version.

See dependency doc for details about built-in version matchers.

Child elements

Element Description Cardinality
any version matcher adds a version matcher to the list of available ones 0..n

Ivy Files

Ivy use is entirely based on what is called ivy files. Ivy files are xml files, usually called ivy.xml, containing the description of the dependencies of a module, its published artifacts and its configurations.

Here is the simplest ivy file you can write:

<ivy-module version="1.3">
  <info organisation="myorg"
        module="mymodule"
        />
</ivy-module>

Since version 0.8, ivy publishes an xslt which help make ivy files more readable. You just have to add
a line like this one in your ivy file:

<?xml-stylesheet type="text/xsl" href="http://www.ivyrep.org/ivy-doc.xsl"?>

However, all information is not presented with the xslt (dependency configurations, in particular).
And due to security issues, it only works if the ivy file is in the same domain as the xsl... But they are particularly useful to browse the ivy repository.

If you want to see a sample file using almost all possibilities of ivy files, check this one, with or without xslt.

Before beginning the reference itself, it is required to have in mind the terminology defined in the main page of this reference documentation.

For those familiar with xml schema, the schema used to validate ivy files can be found here. For those using xsd aware IDE, you can declare the xsd in your ivy files to benefit from code completion / validation:

<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="1.3"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation=
                  "http://www.jayasoft.org/misc/ivy/ivy.xsd">
  <info organisation="myorg"
        module="mymodule"
        />
</ivy-module>

Hierarchical Index

ivy-module
    info
        license
        ivyauthor
        repository
        description
    configurations
        conf
    publications
        artifact
            conf
    dependencies
        dependency
            conf
                mapped
            artifact
                conf
            include
                conf
            exclude
                conf
    conflicts
        manager

ivy-module

Tag: ivy-module

Root tag of any ivy-file.

Attributes

Attribute Description Required
version the version of the ivy file specification - should be '1.3' with current version of ivy Yes

Child elements

Element Description Cardinality
info contains information about the described module 1
configurations container for configuration elements 0..1
publications container for published artifact elements 0..1
dependencies container for dependency elements 0..1
conflicts section to configure the conflict managers to use 0..1

info

Tag: info Parent: ivy-module

Gives information about the module this ivy file describe.

since 1.4 This tag supports extra attributes.

Attributes

Attribute Description Required
organisation the name of the organisation that is the owner of this module. Yes
module the name of the module described by this ivy file. Yes
branch the branch of this module. since 1.4 No, defaults to the default branch configured, or nothing if no default branch is configured
revision the revision of this module. Yes in repository ivy files, no in ivy files to resolve
status the status of this module. See terminology section for details No, default to 'integration'
publication the date of publication of this module. It should be given in this format: yyyyMMddHHmmss No, but it's a good practice to set it with delivered ivy files

Child elements

Element Description Cardinality
license contains information about the licenses of the described module 0..n
ivyauthor describes who has contributed to write the ivy file 0..n
repository describes on which public repositories this module can be found 0..n
description describes how to use the module 0..1

license

Tag: license Parent: info

Gives information about a license of the described module.

Attributes

AttributeDescriptionRequired
namethe name of the license. Try to respect spelling when using a classical license. Yes
urlan url pointing to the license text. No, but it's a good practice to indicate it

ivyauthor

Tag: ivyauthor Parent: info

Gives information about who has contributed to write this ivy file. It does NOT indicate who is the author of the module itself.

Attributes

AttributeDescriptionRequired
namethe name of the author, as a person or a company. Yes
urlan url pointing to where the author can bea reached. No, but it's a good practice to indicate it

repository

Tag: repository Parent: info

Gives information about a public repository where the module can be found. This information is given as an indication, repositories being able to be down over time.

Attributes

AttributeDescriptionRequired
namethe name of the repository. Try to respect spelling for common repositories (ibiblio, ivyrep, ...) Yes
urlan url pointing to the repository. Yes
patternan ivy pattern to find modules on this repository No, but it's recommended to indicate it.
ivystrue if ivy file can be found on this repository No, defaults to false.
artifactstrue if module artifacts can be found on this repository No, defaults to false.

description

Tag: description Parent: info

Describes the current module. This tag is the only one which can contain free text, including html. It is used to describe the module itself, usually in a single short phrase (it is not meant to replace the module description on the corresponding web site), and then gives all information necessary to use the module, especially information about public configurations, how and when to use them.

Attributes

AttributeDescriptionRequired
homepagethe url of the homepage of the module No, but it's recommended to indicate it.

configurations

Tag: configurations Parent: ivy-module

Container for configuration element. If this container is not present, it is assumed that the module has one public configuration called 'default'.

since 1.3 You can define a new default conf mapping on this container by specifying the defaultconfmapping attribute.

A default conf mapping is very similar to the defaultconf which can be set on the dependencies tag, but it has a slightly different behaviour.
The default conf mapping not only defines the conf mapping to use when no conf mapping is specified for a dependency in this ivy file, but it also modify the way ivy interprets conf mapping with no mapped conf. In this case, Ivy will look in the default conf mapping and use the conf mapping defined in the default conf mapping for the conf for which there is no mapped conf.

See examples on the dependency page.

since 1.4 You can activate a confmappingoverride mode for all configurations, in which case the extending configurations will override the mappings of the configurations they extend from. This is an advanced feature which should be used only if you understand its implication.
For a discussion about the origin of this feature see this thread.

Attributes

Attribute Description Required
defaultconfmapping the default conf mapping to use in this ivy file since 1.3 No, defaults to no default conf mapping
confmappingoverride true to activate configuration mapping override, false otherwise since 1.4 No, defaults to false

Child elements

Element Description Cardinality
conf declares a configuration of this module 0..n
include include configurations from another file 0..n

conf

Tag: conf Parent: configurations

Declares a configuration of this module. As described in the reference page, a configuration is a way to use or construct a module. Some modules may be used in different ways (think about hibernate which can be used inside or outside an application server), and this way may alter the artifacts you need (in the case of hibernate, jta.jar is needed only if it is used outside an application server). Moreover, a module may need some other modules and artifacts only at build time, and some others at runtime. All those differents ways to use or build a module are called in ivy configurations.

The conf element in the configurations section declares one configuration. This declaration gives the name of the configuration declared, its visibility and the other configurations of the module it extends.

Visibility is used to indicate whether or not a configuration can be used from other modules depending on this one. Thus a private configuration is only used for internal purpose (maybe at build time), and other modules cannot declare to depend on it.

A configuration can also extend one or several other ones of the same module. When a configuration extends another one, then all artifacts required in the extended configuration will also be required in the configuration that extends the other one. For instance, if configuration B extends configuration A, and if artifacts art1 and art2 are required in configuration A, then they will be automatically required in configuration B. On the other hand, artifacts required in configuration B are not necessarily required in configuration A.

This notion is very helpful to define configurations which are similar with some differences.

since 1.4 The extends attribute can use the following wildcards:

* all other configurations
*(public) all other public configurations
*(private) all other private configurations


since 1.4 A whole configuration can be declared as non transitive, so that all dependencies resolved in this configuration will be resolved with transitivity disabled. Note that the transitivity is disabled for all the configuration dependencies (including those obtained because this conf extends other ones), and only for this configuration (which means that a conf extending this one with transitivityy enabled will get transitive dependencies even for dependencies being part of the non transitive configuration).
This is very useful to build a compile configuration, for instance, forcing the dependency declaration on each direct dependency, with no risk to forget some because of transitivity.

since 1.4 This tag supports extra attributes.

Attributes

Attribute Description Required
name the name of the declared configuration Yes
description a description for the declared configuration No
visibility the visibility of the declared configuration.
'public' means that this configuration can be used by other modules, while 'private' means that this configuration is used only in the module itself, and is not exposed to other modules
No, defaults to public
extends a comma separated list of configurations of this module that the
current configuration extends
No, defaults to none
transitive a boolean to indicate if this conf is transitive or not since 1.4 No, defaults to true
deprecated indicates that this conf has been deprecated by giving the date of the deprecation.
It should be given in this format: yyyyMMddHHmmss
No, by default the conf is not deprecated

Examples

<conf name="core" visibility="private" />
<conf name="compile" extends="core" transitive="false" visibility="private" />
<conf name="runtime" extends="compile" description="everything needed to run this module" />

Declares three configurations, core compile and runtime, with only the runtime one accessible from other modules, and with the compile one being non transitive.
Therefore the core configuration will only be composed of dependencies declared in the core configuration itself, the compile configuration will be composed of all dependencies required in either core or compile configuration, but without transivity (neither for core nor compile dependencies), and runtime will be composed of all dependencies, all transitively, including the dependencies declared only in compile.

include

Tag: include Parent: configurations

Include configurations specified in another file. since 1.3

The included file should have a configurations tag as root tag, which follow the same specification as the configurations tag of the ivy file.

This means that it can contain conf declarations, other file inclusion, and also a defaultconfmapping.

When delivering an ivy file with such an inclusion, the included configuration file is inlined, i.e. ivy remove the dependency on the external file.

Attributes

Attribute Description Required
file the file to include Yes

Examples

<ivy-module version="1.0">
  <info organisation="myorg"
        module="mymodule"
  />
  <configurations>
    <include file="path/to/included-configurations.xml"/>
    <conf name="conf3"/>
  </configurations>
  <dependencies>
    <dependency name="mymodule1" rev="1.0"/>
    <dependency name="mymodule2" rev="2.0" conf="conf2,conf3->*"/>
  </dependencies>
</ivy-module>

with included-configurations.xml like this:

<configurations defaultconfmapping="*->@">
  <conf name="conf1" visibility="public"/>
  <conf name="conf2" visibility="private"/>
</configurations>

Defines 3 configurations, conf1, conf2 and conf3. mymodule1 is required in each configuration, with for each the same configuration (conf1 is needed in conf1, conf2 in conf2, and conf3 in conf3) due to the defaultconfmapping defined in the included file.

publications

Tag: publications Parent: ivy-module

Container for artifact elements, used to describe the artifacts published by this module. If this container is not present, it is assumed that the module has one artifact, with the same name as the module, and published in all module configurations.
Thus if you have a module which publishes no artifacts (a sort of virtual module, made only to integrate several other modules as a whole), you have to include a publications element with no artifact sub element.

Child elements

ElementDescriptionCardinality
artifactdeclares a published artifact for this module 0..n

artifact

Tag: artifact Parent: publications

Declares an artifact published by this module. This is especially useful for other modules dependending on this one. They thus get all published artifacts belonging to the configurations asked. Indeed, each published artifact declares in which public configuration it is published. Thus a module depending on this module only get artifacts marked with the asked configurations, taking into account configurations extension (see configuration declaration).

The configurations in which an artifact is published can be configured in two ways:

  • conf attribute on artifact element
  • conf subelement

The twos are equivalent, it is only a matter of preference. However, do not mix both for one artifact.

since 1.4 The artifact element as default values for all its attributes, so if you want to declare a default artifact you can just declare it like that:

<artifact />

If this is the only artifact declared, then it's equivalent to having no publication section at all.

since 1.4 It is possible to give a url at which artifacts can be found. This is not mandatory, and even not recommended. This is only a convenient way to deal with an existing repository with a bad layout, but should not be avoided in an enterprise repository.

Attributes

Attribute Description Required
name the name of the published artifact. This name must not include revision. No, defaults to the name of the module
type the type of the published artifact. It's usually its extension, but not necessarily. For instance, ivy files are of type 'ivy' but have 'xml' extension No, defaults to jar
ext the extension of the published artifact No, defaults to type
conf comma separated list of public configurations in which this artifact is published.
'*' wildcard can be used to designate all public configurations of this module
No, defaults to '*' if neither conf attribute nor conf children element is given
url a url at which this artifact can be found if it isn't located at the standard location in the repository since 1.4 No, defaults to no url

Child elements

Element Description Cardinality
conf indicates a public configuration in which this artifact is published 0..n

Examples

<artifact />

Declares an artifact with the name of the module as name, type and ext jar, and published in all configurations.


<artifact name="foo-src" type="source" ext="zip" conf="src" />

Declares an artifact foo-src, of type 'source' with extension 'zip', and published in the src configuration.


<artifact name="foo" url="http://www.acme.com/repository/barbaz/foo-1.2-bar.jar" />

Declares an artifact foo, of type and extension 'jar' located at the url http://www.acme.com/repository/barbaz/foo-1.2-bar.jar. This url will only be used if the artifact cannot be found at its standard location.

conf

Tag: conf Parent: artifact

Indicates a public configuration in which enclosing artifact is published.

Attributes

AttributeDescriptionRequired
namethe name of the module public configuration in which this artifact is published. '*' wildcard can be used to designate all public configurations of this module Yes

dependencies

Tag: dependencies Parent: ivy-module

Container for dependency elements, used to describe the dependencies of this module.
If this container is not present, it is assumed that the module has no dependency at all.

This container let the possibility to defines two very similar things: defaultconf and defaultconfmapping.

defaultconf exists since Ivy 1.1 and enables to define the default conf attribute to use when no conf is defined for a dependency in this ivy file. It is only used when no conf mapping is defined, and has no influence in other cases.

defaultconfmapping exists since Ivy 1.3 and enables not only to define the default conf mapping when no conf is specified for a dependency in this ivy file, but it also influence the way conf mapping with no mapped conf are interpreted (see configurations doc page for details about this).

Note that if both defaultconf and defaultconfmapping are defined, it's the defaultconfmapping that is used. Note also that if several defaultconfmapping are defined (one in the configurations tag, one or several in included configurations file, and/or one in the dependency tag, then it's only the last which is taken into account, the others will have no effect at all.

Attributes

Attribute Description Required
defaultconf the default configuration to use when none is specified in a dependency. since 1.1 No, defaults to *->*
defaultconfmapping the default configuration mapping to use in this ivy fie. since 1.3 No, defaults to no default conf mapping

Child elements

Element Description Cardinality
dependency declares a dependency for this module 0..n

dependency

Tag: dependency Parent: dependencies

Declares a dependency for this module. A dependency is described by the module on which the current module depends (identified by its name, organisation and revision), and a mapping of configurations.

Fixed and dynamic revisions

The revision can be given as a fixed one (1.5.2, for instance) or as a latest (or dynamic) one. Several possibilities for dynamic revisions are implemented in Ivy:

  • latest.integration
  • selects the latest revision of the dependency module.

  • latest.[any status]
  • selects the latest revision of the dependency module with at least the specified status. since 1.4
    For instance latest.milestone will select the latest version being either a milestone or a release, and latest.release will only selects the latest release. Note that in order to find the latest revision with the appropriate status Ivy has to parse all the ivy files in your repository from the last one until it finds such a revision. Hence don't be surprised if the resolution slow down.
    See also statuses to see how to configure module statuses.

  • end the revision with a +
  • selects the latest sub-revision of the dependency module. For instance,
    if the dependency module exists in revision 1.0.3, 1.0.7 and 1.1.2, "1.0.+" will select 1.0.7.

  • version ranges
  • mathematical notation for ranges can be used to match a range of version. since 1.4
    Examples:
    [1.0,2.0] matches all versions greater or equal to 1.0 and lower or equal to 2.0
    [1.0,2.0[ matches all versions greater or equal to 1.0 and lower than 2.0
    ]1.0,2.0] matches all versions greater than 1.0 and lower or equal to 2.0
    ]1.0,2.0[ matches all versions greater than 1.0 and lower than 2.0
    [1.0,) matches all versions greater or equal to 1.0
    ]1.0,) matches all versions greater than 1.0
    (,2.0] matches all versions lower or equal to 2.0
    (,2.0[ matches all versions lower than 2.0

since 1.4 If you don't find a way to expression your dependency version constraint among these, you can plug your own.
The way to determine which revision is the "latest" between two is configurable through the use of pluggable LatestStrategy. See ivy main concepts for details about this.

Configurations mapping

This mapping indicates which configurations of the dependency are required in which configurations of the current module, also called master configurations.

There are several ways to declare this mapping of configurations, choose depending more on preference than on possibilities. Try to avoid mixing usage in a single dependency element: do not use both nested and inline mapping declaration.

The first way to declare this mapping is called the inline mapping. It is maybe the less natural at first, but it's powerful and concise. Inline mapping can take several forms.

  • Specify one configuration name
  • This means that in this master configuration the same dependency configuration is needed (except if a defaultconfmapping has been specified in this ivy file, see configurations for details, or table below for examples).
    For instance, if the current module has defined a configuration named 'runtime', and the dependency too, then having an inline mapping configuration set to 'runtime' means that in the runtime master configuration the runtime dependency configuration is required.

    More examples:
    The table below indicates how ivy interpret the conf attribute according to how
    defaultconfmapping is set:

    defaultconfmapping conf ivy interpretation
    *->*
    runtime runtime->runtime
    test test->test
    runtime->*;test->default runtime->*;test->default
    runtime->*;test->default runtime runtime->*
    runtime->*;test->default test test->default


  • Specify a configuration mapping using the '->' operator separating a comma separated list of master configurations (left operand) of a comma separated list of dependency configurations (right operand).
  • A good way to remember which side is for the master configuration (i.e. the configuration of the module defining the dependency) and which side is for the dependency configuration is to read the '->' as 'depends on'.

    In this case, all specified dependency configurations are required in all specified master configurations.
    For instance, 'A, B, C -> E, F' means that dependency configurations E & F are required in master configurations A, B and C.

    Note that you can use the wildcard '*' as a configuration name, meaning that all configurations (either master or dependency public ones depending on the side) are wanted. For instance, '* -> B, C' means that B & C dependency configurations are required in all master configurations.

    since 1.4 you can use * wildcard followed by negated configurations to mean all but xxx. For instance, '*, !A, !B -> X' means that X dependency configuration is required in all master configurations except A and B.

    since 1.2 '@' also has a special meaning as a right operand of the dependency mapping, it means map to self. This is particularly useful with '*', '*->@' meaning that all configurations of the module maps to their equivalent (same name) in the dependency.

    since 1.4 '#' can be used as right side operand to mean 'this' configuration, and thus refers to the configuration being resolved. It is slightly similar to @, except that it takes into account the configuration being actually resolved in case of a configuration extending another one.

    Example:
    Let's foo be a module with two configurations, A and B, B extending A.
    Then a dependency declaring conf A-># will get A dep conf in its confs A (when resolving A, ivy will find interpret the # symbol as A) and B dep conf in its conf B (when resolving B, ivy will interpret the # symbol as B, even if this dependency is only required because of the A dependency).

    See this thread on the forum for a more detailed motivation behind this keyword.
    If you don't understand really how this works, do not use :-)

    since 1.4 '%' can be used as left side operand to mean 'all the other configurations'. This can be usefull when you only have a specific mapping for some configurations and a default mapping for all the others.

    Example:
    test->runtime;%->default means that the test configuration is mapped to the runtime configuration, but all the other configurations are mapped to the default configuration.

    since 1.3 a fallback mechanism can be used when you are not sure that the dependency will have the required conf. You can indicate to ivy that you want one configuration, but if it isn't present, use another one.
    The syntax for specifying this adds the fallback conf between parenthesis right after the required conf.
    For instance, test->runtime(default) means that in the test configuration of the module the runtime conf of the dependency is required, but if doesn't exist, it will use the default conf instead. If default conf doesn't exist then it will be considered as an error. Note that the * wildcard can be used as fallback conf.

    since 1.4 you can add simple conditions in the dependency mapping. This is done by adding a condition between '[' and ']'. If the condition evaluates to true, the mapping is performed. If the condition evaluates to false, the mapping will be ignored. For instance, test->[org=A]runtime,[org=B]default means that the test configuration will be mapped to the runtime conf for the dependencies of organisation 'A' and to the default conf for dependencies of organisation 'B'.

  • Specify a semi-column separated list of any of the previous specs.
  • In this case, it is the union of the mapping which is kept. For instance, 'A -> B; * -> C' means that B conf is needed in A conf and C conf is need in all master conf... so both B & C dep conf are required in A master conf

If you prefer more verbose mapping declaration, everything is also possible with sub elements mapping declaration.

Artifact restriction

Moreover, the dependency element also supports an artifact restriction feature (since 0.6).
See dependency artifact restriction for details.

Forcing revision

Finally, the dependency element also supports an a force attribute (since 0.8), which gives an indication
to conflicts manager to force the revision of a dependency to the one given here.

See conflicts manager for details.

since 1.4 this tag supports extra attributes

Attributes

Attribute Description Required
org the name of the organisation of the dependency. No, defaults to the master module organisation
name the module name of the dependency Yes
branch the branch of the dependency. since 1.4 No, defaults to the default branch configured for the dependency.
rev the revision of the dependency. See above for details. Yes
force a boolean to give an indication to conflict manager that this dependency
should be forced to this revision (see conflicts manager)
No, defaults to false
conf an inline mapping configuration spec (see above for details) No, defaults to defaultconf attribute of dependencies element if neither conf attribute nor conf children element is given
transitive true to resolve this dependency transitively, false otherwise (since 1.2) No, defaults to true
changing true if the dependency artifacts may change without revision change, false otherwise (since 1.2). Artifacts update will be looked after only if the publication date of the ivy file has changed. Note that this is not a recommended use and that it avoid some cache optimization in ivy. No, defaults to false

Child elements

Element Description Cardinality
conf defines configuration mapping has sub element 0..n
artifact / include defines artifacts inclusion - use only if you do not control dependency ivy file 0..n
exclude defines artifacts exclusion - use only if you do not control dependency ivy file 0..n

Examples

<dependency org="jayasoft" name="swtbinding" revision="0.2"/>

Declares a dependency on the module swtbinding from jayasoft in its revision 0.2. All the configuration of this dependency will be included in all configurations of the module in which the dependency is declared.


<dependency org="jayasoft" name="swtbinding" branch="fix-103" revision="latest.integration"/>

Same as above except that it will take the latest revision on the branch 'fix-103' instead of revision '0.2'.


<dependency name="mymodule" revision="latest.integration" conf="test->default"/>

Declares a dependency on the module mymodule from the same organisation as the module in which the dependency is declared. The latest available revision of this dependency will be used. This dependency will only be included in the test configuration of the module, and it's only the default configuration of the dependency which will be included.


<dependency org="apache" name="commons-lang" revision="2.0" force="true" conf="default"/>

Declares a dependency on the module commons-lang from apache, in revision 2.0. The revision 2.0 will be used even if another dependency declares itself a dependency on another version of commons-lang. Moreover, if no defaultconfmapping is defined, only the default conf of commons-lang will be used in the default conf of the master module. If *->runtime was declared as defaultconfmapping, then the runtime conf of commons-lang would be included in the default conf of the master module. Note that whatever the defaultconfmapping is, the dependency only be included in the default conf of the master module. The defaultconfmapping only changes the required dependency confs.


<dependency org="foo" name="bar" revision="3.0" transitive="false" conf="default->@;runtime,test->runtime"/>

Declares a dependency on the module bar from foo, in revision 3.0. The dependencies of bar will themselves not be included due to the setting of transitive. The default dependency conf will be included in the default master conf, and the runtime dependency conf will be included in both the runtime and test master conf.


<dependency org="foo" name="bar" revision="3.0" changing="true" conf="compile->runtime(default)"/>

Declares a dependency on the module bar from foo, in revision 3.0. This revision is considered to be able to change (changing="true"), so even if it is already in ivy cache, Ivy will check if a revision is a more recent last modified date is available on the repository. The runtime conf of bar is required in the compile conf of the master module, but if bar doesn't define a runtime conf, then the default conf will be used.

conf

Tag: conf Parent: dependency

Describes a configuration mapping for a dependency. See also the inline configuration mapping in dependency element.

Attributes

AttributeDescriptionRequired
namethe name of the master configuration to map. '*' wildcard can be used to designate all configurations of this module Yes
mappeda comma separated list of dependency configurations to which this master configuration should be mapped No, default to the same configuration as master one, unless nested mapped elements are specified

Child elements

ElementDescriptionCardinality
mappedmap dependency configurations for this master configuration 0..n

mapped

Tag: mapped Parent: conf

Describes a mapped dependency configuration for a master configuration.

Attributes

AttributeDescriptionRequired
namethe name of the dependency configuration mapped. '*' wildcard can be used to designate all configurations of this module Yes

artifact

Tag: artifact Parent: dependency

This feature gives you more control on a dependency for which you do not control its ivy file.
It enables to specify the artifacts required, if the dependency has no ivy file.

Indeed, when a module has no ivy file, it is assumed that it publishes exactly one artifact having the same name as the module itself. But when this module publishes more artifacts, or simply does not respect the name rule, and if you cannot deliver an ivy file for it (because you do not control the repository, for instance - think about maven ibiblio repository, to give no name), then this feature let you specify the artifacts names you want to get.

Each artifact specification can be given in the context of particular master configurations. By default, if no configuration is specified, artifacts specification apply to all master configurations. But you can specify that a specification applies only to one or several master configurations, using either inline or nested conf specification. In this case, do not forget that if you do not specify any specification for a particular configuration, then no specification will apply for this configuration and it will be resolved not taking into account any specification.

For instance, imagine you have A, B & C master configurations. If you specify art1 in A & B and art2 in A, then C will not be specified at all, and will thus assume the default artifact. To prevent this, you have to specify a configuration mapping for the dependency, mapping only A & B to some or all dependency configurations.

Example:

<dependency org="yourorg" name="yourmodule9" rev="9.1" conf="A,B->default">
  <artifact name="art1" type="jar" conf="A,B"/>
  <artifact name="art2" type="jar" conf="A"/>
</dependency>

since 1.4 It's possible to indicate the url at which the artifact can be found. This is not mandatory, and even not recommended with an enterprise repository. Note that Ivy will always look at the location where the artifact should be and only use th url if it cannot be found at the standard location in the repository.

Attributes

Attribute Description Required
name the name of an artifact of the dependency module Yes
type the type of the artifact of the dependency module Yes
ext the extension of the artifact of the dependency module No, defaults to type
conf comma separated list of the master configurations in which this artifact should be included.
'*' wildcard can be used to designate all configurations of this module
No, defaults to '*', unless nested conf are specified
url an url where this artifact can be found if it isn't present at the standard location in the repository since 1.4 No, defaults to no url

Child elements

Element Description Cardinality
conf configuration in which the artifact should be included 0..n

Examples

<dependency org="foo" name="bar" rev="1.0">
  <artifact name="baz" type="jar"/>
</dependency>

Declares a dependency on module bar which only publish one artifact: baz.jar.


<dependency org="foo" name="bar" rev="1.0">
  <artifact name="baz" type="jar" url="http://www.acme.com/repository/bar/baz-1.0-acme.jar"/>
</dependency>

Same as above, except that if the artifact is not found at its standard location, Ivy will use http://www.acme.com/repository/bar/baz-1.0-acme.jar to download it.

conf

Tag: conf Parent: artifact

Specify a configuration in which the enclosing artifact specification should be included.

Attributes

Attribute Description Required
name the name of the master configuration in which the enclosing artifact should be included Yes

exclude

Tag: exclude Parent: dependency

This feature gives you more control on a dependency for which you do not control its ivy file.
It enables to restrict the artifacts required, by excluding artifacts being published by the dependency or any of its transitive dependencies,
even if configuration does not a good separation of published artifacts

The same principle concerning configuration as for include applies to this exclude feature (see above the include feature).

Note that exclusion is always done AFTER inclusion has been done.

since 1.3 This exclude feature can also be used not only to exclude artifacts but also to exclude whole modules. Indeed when you exclude artifacts, it doesn't avoid ivy to search for the module itself, and to resolve the dependencies of the module. But you can also exclude the whole module, which means that the module will not be downloaded at all, and so its own dependencies will not be resolved. For sure, this is usually done to exclude not a direct dependency but an indirect one. To exclude a whole module, you just have to not specify any artifact name, type and ext in your exclude rule. For instance:

<dependency name="A" rev="1.0">
  <exclude module="B"/>
</dependency>

Attributes

Attribute Description Required
org the organisation of the dependency module or artifact to exclude, or a regexp matching this organisation since 1.3 No, defaults to *
module the name of the dependency module or the artifact to exclude, or a regexp matching this module name since 1.3 No, defaults to *
name the name of an artifact of the dependency module to add to the exclude list, or a regexp matching this name No, defaults to *
type the type of the artifact of the dependency module to add to the exclude list, or a regexp matching this name No, defaults to *
ext the extension of the artifact of the dependency module to add to the exclude list, or a regexp matching this name No, defaults to type
matcher the matcher to use to match the modules to excludes since 1.3 No, defaults to exactOrRegexp in pre 1.3 ivy files, and exact in 1.3 and superior
conf comma separated list of the master configurations in which this artifact should be included.
'*' wildcard can be used to designate all configurations of this module
No, defaults to '*', unless nested conf are specified

Child elements

Element Description Cardinality
conf configuration in which the artifact should be included 0..n

conf

Tag: conf Parent: artifact

Specify a configuration in which the enclosing artifact exclusion should be included.

Attributes

AttributeDescriptionRequired
namethe name of the master configuration in which the enclosing artifact should be excluded Yes

include

Tag: include Parent: dependency

This feature gives you more control on a dependency for which you do not control its ivy file.
It enables to restrict the artifacts required by including only the artifacts given here, even if configuration does not a good separation of published artifacts.

Each artifact restriction can be given in the context of particular master configurations. By default, if no configuration is specified, artifacts restriction apply to all master configurations. But you can specify that a restriction applies only to one or several master configurations, using either inline or nested conf specification. In this case, do not forget that if you do not specify any restriction for a particular configuration, then no restriction will apply for this configuration and it will be resolved not taking into account any restriction.

For instance, imagine you have A, B & C master configurations. If you restrict to art1 in A & B and art2 in A, then C will not be restricted at all, and will thus get all artifacts of all dependency configurations if you do not specify a configuration mapping. To prevent this, you have to specify a configuration mapping for the dependency, mapping only A & B to some or all dependency configurations.

Example:

<dependency org="yourorg" name="yourmodule9" rev="9.1" conf="A,B->default">
  <include name="art1" type="jar" conf="A,B"/>
  <include name="art2" type="jar" conf="A"/>
</dependency>

Attributes

Attribute Description Required
name the name of an artifact of the dependency module to add to the include list, or a regexp matching this name No, defaults to .*
type the type of the artifact of the dependency module to add to the include list, or a regexp matching this name No, defaults to .*
ext the extension of the artifact of the dependency module to add to the include list, or a regexp matching this name No, defaults to type
conf comma separated list of the master configurations in which this artifact should be included.
'*' wildcard can be used to designate all configurations of this module
No, defaults to '*', unless nested conf are specified

Child elements

Element Description Cardinality
conf configuration in which the artifact should be included 0..n

conf

Tag: conf Parent: include

Specify a configuration in which the enclosing artifact inclusion should be included.

Attributes

Attribute Description Required
name the name of the master configuration in which the enclosing artifact should be included Yes

conflicts

Tag: conflicts Parent: ivy-module

Container for conflict manager elements, used to indicate how conflicts should be resolved for this module.

The list of built-in conflict managers available is listed on the conflict manager configuration page.

Conflicts manager are used during the resolve operation, i.e. when ivy analyse the graph of dependencies and download corresponding ivy files and artifacts. The fact to manage conflict at resolve time enables to minimize downloads: when a module is evicted by a conflict manager, it is not downloaded.

There are two things optimized during conflict resolution: download of artifacts and download of ivy files. The first is always ensured by ivy, i.e. artifacts of a module evicted will never be downloaded. The second is not as simple to handle because to know what are the conflicts ivy needs to know the dependency graph, and to know the dependency graph, it has to download ivy files. But ivy is highly optimized on this too, and it tries to evict modules as soon as possible.
That's why the order of dependencies is important for download optimization. Indeed ivy traverses the dependency graph in the order in which dependencies are declared in the ivy files, and each time it encounters a dependency on a module, it first check if there is a conflict on this module, and if this is the case, it asks the conflict manager to resolve the conflict. Then if the module is evicted, it does not download its ivy file, and the whole branch is not traversed, which can saves a lot of time.

If this container is not present, a default conflict manager is used for all modules. The current default conflict manager is the "latest-revision" conflict manager.

Child elements

ElementDescriptionCardinality
managerdeclares a conflict manager for this module 1..n

manager

Tag: manager Parent: conflicts

Specify a a conflict manager for one or several dependencies.
The way to specify a conflict manager is by giving indication to which dependencies the conflict manager applies (by giving organisation and module names or name regexp), and then specifying the conflict manager, either by giving its name or by specifying a fixed revision list, in which case a fixed conflicts manager is used.

See Conflicts Manager for details on conflicts manager in general.

Attributes

AttributeDescriptionRequired
orgthe name, or a regexp matching the name of organisation to which this conflict manager should apply No, defaults to * (match all)
modulethe name, or a regexp matching the name of module to which this conflict manager should apply No, defaults to * (match all)
namethe name of the conflict manager to use Exactly one of two
reva comma separated list of revisions this conflict manager should select
matcherthe matcher to use to match the modules for which the conflict manager should be used since 1.3 No, defaults to exactOrRegexp in pre 1.3 ivy files, and exact in 1.3 and superior

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

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:fr.jayasoft.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 follow this tip given by colin sampaleanu.

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

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.

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">
    <ivy:configure />
   
    <ivy:resolve file="${ivy.dep.file}" conf="${ivy.configurations}" />
   
    <ivy:retrieve pattern="${ivy.retrieve.pattern}" conf="${ivy.configurations}" />
</target>

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

  1. task attribute
  2. ivy instance
  3. project property

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.

Usual cycle of main tasks

Example

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

<project xmlns:ivy="antlib:fr.jayasoft.ivy.ant" name="sample" default="resolve">

    <target name="resolve">
        <ivy:configure file="../ivyconf.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>

All ivy tasks are documented in the following pages.

artifactproperty

since 1.1

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:

<artifactproperty conf="build"
      name="[module].[artifact]-[revision]"
      value="${cache.dir}/[module]/[artifact]-[revision].[ext]"/>

will set two properties:

mydep.foo-1.0 = my/cache/dir/mydep/foo-1.0.jar
mydep.bar-1.0 = my/cache/dir/mydep/bar-1.0.jar

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:

<?xml version="1.0" encoding="UTF-8"?>
<modules>
  <module organisation="hippo" name="sant-classes" rev="1.01.00b04-dev" status="integration">
    <artifact name="sant-classes-src" ext="zip" type="zip">
      <origin-location is-local="true">
        C:/home/jstuyts/data/ivy/local/hippo/sant-classes/1.01.00b04-dev/sant-classes-src-1.01.00b04-dev.zip</origin-location>
      <cache-location>
        C:/home/jstuyts/data/ivy/cache/hippo/sant-classes/zips/sant-classes-src-1.01.00b04-dev.zip</cache-location>
      <retrieve-location>lib/test/sant-classes-src-1.01.00b04-dev.zip</retrieve-location>
    </artifact>
    <artifact name="sant-classes-unoptimized" ext="jar" type="jar">
      <origin-location is-local="true">
        C:/home/jstuyts/data/ivy/local/hippo/sant-classes/1.01.00b04-dev/sant-classes-unoptimized-1.01.00b04-dev.jar</origin-location>
      <cache-location>
        C:/home/jstuyts/data/ivy/cache/hippo/sant-classes/jars/sant-classes-unoptimized-1.01.00b04-dev.jar</cache-location>
      <retrieve-location>lib/test/sant-classes-unoptimized-1.01.00b04-dev.jar</retrieve-location>
    </artifact>
  </module>
  <module organisation="testng" name="testng" rev="4.6.1-jdk15" status="release">
    <artifact name="testng" ext="jar" type="jar">
      <origin-location is-local="false">
        <a href="http://repository.hippocms.org/maven/testng/jars/testng-4.6.1-jdk15.jar</origin-location>" title="http://repository.hippocms.org/maven/testng/jars/testng-4.6.1-jdk15.jar</origin-location>">http://repository.hippocms.org/maven/testng/jars/testng-4.6.1-jdk15.jar&...</a>
      <cache-location>C:/home/jstuyts/data/ivy/cache/testng/testng/jars/testng-4.6.1-jdk15.jar</cache-location>
      <retrieve-location>lib/test/testng-4.6.1-jdk15.jar</retrieve-location>
    </artifact>
  </module>

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

<ivy:artifactreport tofile="${basedir}/path/to/myreport.xml" />

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

<ivy:artifactreport tofile="${basedir}/path/to/myreport.xml" conf="default"/>

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

    <ivy:buildlist reference="build-path">
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

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:

    <subant target="build" buildpathref="build-path" />


    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" reverse="true">
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

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.


    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" root="myapp">
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

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.


    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" leaf="mymodule">
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

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

<ivy:buildnumber organisation="jayasoft" module="ivy" />

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


<ivy:buildnumber organisation="jayasoft" module="ivy" revision="1.3" />

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


<ivy:buildnumber organisation="jayasoft" module="ivy" revision="1.2" />

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


<ivy:buildnumber organisation="jayasoft" module="ivy" revision="1." />

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


<ivy:buildnumber organisation="jayasoft" module="ivy" revision="3." />

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


<ivy:buildnumber organisation="jayasoft" module="ivy" revision="1.4-RC" defaultBuildNumber="1" revSep=""/>

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

<cachepath pathid="default.classpath" conf="default" />

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


<cachepath pathid="default.classpath" conf="default" useOrigin="true" />

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


<ivy:cachepath organisation="emma" module="emma" revision="2.0.4217" inline="true" conf="ant" pathid="emma.classpath"/>
<taskdef resource="emma_ant.properties" classpathref="emma.classpath" />

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".
AttributeDescriptionRequired
filepath 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
urlurl of the configuration file to use
hosthttp authentication hostNo, unless authentication is required
realmhttp authentication realm
usernamehttp authentication user name
passwdhttp 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

<ivy:findrevision organisation="jayasoft" module="ivy" revision="latest.integration"/>

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


<ivy:findrevision organisation="jayasoft" module="ivy" revision="1.0+"/>

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

<ivy:info file="${basedir}/path/to/ivy.xml" />

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

<ivy:install organisation="apache" module="commons-lang" revision="2.0" from="ivyrep" to="myfsresolver"/>

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

<ivy:listmodules organisation="jayasoft" module="ivy" revision="*" property="ivy.[revision]" value="found"/>

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'


<ivy:listmodules organisation="*" module="ivy*" revision="1.0" matcher="glob" property="modules.[module]" value="[organisation]"/>

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:

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

<ivy:cachepath organisation="emma" module="emma" revision="2.0.4217" inline="true" conf="ant" pathid="emma.classpath"/>
<taskdef resource="emma_ant.properties" classpathref="emma.classpath" />

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

<ivy:publish resolver="local" pubrevision="1.0">
  <artifacts pattern="1/[artifact].[ext]" />
  <artifacts pattern="2/[artifact].[ext]" />
</ivy:publish>

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:

<ivy:repreport />



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

<ivy:repreport xml="false" graph="true" />



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

<ivy:repreport organisation="foo" />



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:

<ivy:repreport organisation="foo" module="bar*" revision="1.+" matcher="glob" />



To generate an XML report using a custom stylesheet:

<ivy:repreport xsl="true" xslfile="my-custom-stylesheet.xsl" xslext="xml" />



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

<ivy:repreport xsl="true" xslfile="my-custom-stylesheet.xsl" xslext="xml">
    <param name="param1" expression="value1" />
    <param name="param2" expression="value2" />
</report>

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

<ivy:resolve file="path/to/ivy.xml"/>

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


<ivy:resolve file="path/to/ivy.xml" transitive="false" />

Same as above, but with transitive dependencies disabled.


<ivy:resolve file="path/to/ivy.xml" conf="default, test"/>

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


<ivy:resolve file="path/to/ivy.xml" type="jar"/>

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


<ivy:resolve organisation="apache" module="commons-lang" revision="2+" inline="true" />

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

<ivy:retrieve />

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


<ivy:retrieve pattern="${lib.dir}/[conf]/[artifact].[ext]"/>

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:

lib
  default
    commons-lang.jar
    commons-logging.jar
  test
    junit.jar

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.


<ivy:retrieve pattern="${lib.dir}/[conf]/[artifact].[ext]" sync="true" />

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:

lib
  default
    commons-lang.jar
    commons-logging.jar
  test
    junit.jar

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:

lib
  default
    commons-lang.jar
  test
    junit.jar

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


<ivy:retrieve pattern="${lib.dir}/[type]/[artifact]-[revision].[ext]" conf="runtime"/>

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

lib
  jar
    commons-lang-1.0.jar
    looks-1.1.jar
  source
    looks-1.1.zip


<ivy:retrieve organisation="foo" module="bar" inline="true" pattern="${my.install.dir}/[artifact].[ext]"/>

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.

since 1.4

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:

<report conf="compile" />



To generate a HTML report only:

<report conf="compile" graph="false" />



To generate an XML report using a custom stylesheet:

<report conf="compile" xslfile="my-custom-stylesheet.xsl" xslext="xml" />

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

<report conf="compile" xslfile="my-custom-stylesheet.xsl" xslext="xml">
    <param name="param1" expression="value1" />
    <param name="param2" expression="value2" />
</report>

Using yEd to layout report graphs

yEd is a free graph editor, benefiting from all the automatic layouts of yFiles. Ivy is able to generate graphs which are readable by yEd.

The graphs generated by ivy are not layed out (in fact it's why we use yEd), so you have to follow a simple sequence of steps to layout the generated graphs.

Preparation

First you have to generate a graphml file. Simply call the report task (see ivy use documentation) for that.

Step 1: open the graphml file

Launch yEd editor, and open the graphml file generated by the report task. You should obtain something like this:

Step 2: ask yEd to adjust nodes size



Step 3: ask yEd to layout nodes





That's all, you should have obtained something like this:



Note that this is only one possibility, test the available layouts yourself, you could find one better in your case. Once you have layed out the graph, you can either save it with in the same file (but be warned that it will be overwritten at next ivy report call), or another file, export it to jpg, gif, svg, etc. (see yEd site for details).

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.

AttributeDescriptionRequired
namethe name of the variable to set No
valuethe value of the variable to set Yes when using the name attribute
filethe filename of the property file to load as ivy variables One of these, when not using the name attribute
urlthe url from which to read ivy variables
prefixPrefix to apply to variables. A "." is appended to the prefix if not specified. No

Standalone

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.

since 1.3 System properties are included as ivy variables, so you can easily define an ivy variable like this:

java -Dmyivyvar=myvalue fr.jayasoft.ivy.Main [parameters]

Examples

java fr.jayasoft.ivy.Main

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


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

calls ivy with given ivyconf file using given ivy file



since 1.3

java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -dependency apache commons-lang 2.0

calls ivy with given ivyconf file and resolve apache commons-lang 2.0.

This is equivalent to:

java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -ivy ivy.xml

with ivy.xml like this:

<ivy-module version="1.0">
  <info organisation="org"
      module="standalone"
      revision="working"
  />
  <dependencies>
    <dependency org="apache" name="commons-lang" rev="2.0" conf="default->*"/>
  </dependencies>
</ivy-module>



since 1.3

java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -ivy path/to/myivy.xml -cachepath mycachefile.txt

calls ivy with given ivyconf file and resolve the dependencies found in the given ivy file, and then output the classpath of resolved artifacts in cache in a file. This file can then be used to define a classpath corresponding to all the resolved dependencies for any java program.



since 1.4

java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -dependency bar foo 2.0 -main org.bar.foo.FooMain

calls ivy with given ivyconf file and resolve bar foo 2.0, and then run org.foo.FooMain class with the resolved artifacts as classpath

Extending Ivy

Many things are configurable in ivy, and many things are available with ivy core. But when you want to do something not built in ivy core, you can still plug your own code.

Several things are pluggable in ivy: Before trying to implement your own, we encourage you to check if the solution to your problem cannot be addressed by existing features, or by contributed ones. Do not hesitate to ask for help on the forum.

If you still don't find what you need, there are two solutions:
- prepare yourself to enter in ivy internals
- contact us to ask for specific development or advice. As ivy creators, we will always spend less time to implement your features or help you make good developement environment a reality. So do not hesitate to contact us and ask for a pricing.

And what if you still want to develop your own plugins ? Here are the main things to know...

All ivy plug-ins use the same code patterns as ant specific tasks for parameters. This means that if you want to have a "myattribute" of type String, you just have to declare a method called setMyattribute(String val) on your plug-in. The same applies to child tags, you just have to follow ant specifications.

Knowing that, you then have to implement the appropriate interface: To help you understand what is required in each implementation, and what you can use to do it, have a look to existing implementations, it's the best advice we can give you !

Release Notes

The following pages list the changes introduced in each revision of Ivy since its first public version on january 2005.
For each revision you will be able to see the complete list of changes (bug fixes, improvements and new features).

The most recent version also feature a new and noteworthy section.

Refer to these pages if you want to know the benefits of upgrading to a newer version of Ivy.



The latest stable version is 1.4.1

0.5 - 2005-01-12

Ivy 0.5 is the first public version of Ivy.

Downloads

ivy-0.5-bin.zip (731 kB)
ivy-0.5-src.zip (501 kB)
ivy-0.5-src-withdep.zip (764 kB)

0.5.1 - 2005-01-16

Changes log

- Bug fix: NPE in publish task.
- Documentation update.

Downloads

ivy-0.5.1-bin.zip (742 kB)
ivy-0.5.1-src.zip (511 kB)
ivy-0.5.1-src-withdep.zip (774 kB)

0.6 - 2005-02-03

Changes log

+ functional
- added haltonfailure attribute on resolve and retrieve task, so that build can be halt when resolve or retrieve fails
- added dependency artifacts filtering feature, enabling to work better with ibiblio
- ibiblio resolver can now be configured to use any maven like repository, with root and pattern attributes
- added download progression info on resolve
- default cache is now in user home (.ivy-cache in user home), so that cache is shared by default for all projects of the same user
- added public access to method getDependencies(...) in Ivy, which resolve dependencies without downloading artifacts
- added DualResolver, which allows to have ivy files in one place and artifacts in another one

+ non functional
- added some unit tests
- deep review of ivy file reference documentation

+ bugs and refactoring
- bug fix: SimpleURLResolver not handling the case when there is no ivy file
- refactoring: URLResolver renamed to AbstractURLResolver
- refactoring: SimpleURLResolver renamed to URLResolver

Downloads

ivy-0.6-bin.zip (935 kB)
ivy-0.6-src.zip (723 kB)
ivy-0.6-src-withdep.zip (986 kB)

0.6.1 - 2005-02-11

Changes log

+ bugs fix
- conf 'extends' problem with publications
- typedef badly handled in ivyconf.xml
- default properties loading in ivy configure loaded using task classloader

Downloads

ivy-0.6.1-bin.zip (947 kB)
ivy-0.6.1-src.zip (739 kB)
ivy-0.6.1-src-withdep.zip (1002 kB)

0.7 - 2005-03-11

Changes log

- added latest sub revision feature: you can now select the latest sub revision of a module using a +. For instance, "1.0+" selects the latest revision starting with 1.0. (thanks to jonas for the idea)
- haltonfailure now defaults to true (as suggested by Jeroen)
- shorter info lines to better view important info (as suggested by Jeroen)
- retrieve now checks if files are up to date before copying them from cache. This feature can be disabled using the checkUpToDate attribute in ivy configuration file.
- do not download dependencies when not necessary during publication (as suggested by Daniele)
- bug fix: better handling of publish without recursive delivery

Downloads

ivy-0.7-bin.zip (951 kB)
ivy-0.7-src.zip (745 kB)
ivy-0.7-src-withdep.zip (1008 kB)

0.8 - 2005-03-30

Changes log

Note: this version is a major update compared to version 0.7, and contains several API breaks. Ivy files and configuration are compatible, but this is not the case of Ivy Java API. Some defaults changes also, especially default resolver which is no longer ibiblio but ivyrep (but ivyrep is compatible with ibiblio, so it should no break your builds).

- url resolver now handles latest with file urls and http ones (tested only with apache server, many thanks to Glen Marchesani for its contribution)
- added publish artifacts feature, which enable to publish declared artifacts of a module to a repository described by a dependency resolver. It currently works only with filesystem resolver.
- added conflict management at resolve time: during resolve, modules in conflict can be evicted and thus not downloaded
- added ivyrep resolver, using ivyrep to find ivy files, and ibiblio for artifacts
- use ivyrep instead of ibiblio as default resolver
- added more info in ivy files (description, homepage, ivy authors, license, public repository, ...)
- added validate attribute on resolve, retrieve and publish, which allows to disable ivy file validation against ivy.xsd (useful to parse future compatible ivy files)
- ant properties are now available in ivyconf file
- unified default properties in ivyconf, with better independance from url or file
- added ext on artifacts: this enable to distinguish artifact extension from artifact type, util in cases where it differs (example: 'src' type with 'zip' extension, 'ivy' type with 'xml' extension, ...)
- added latest strategy concept: the way to determine which artifact is the latest is now configurable on resolvers handling latest.
- added parameter on chain resolver to say if it should return first found or try to find the latest among all if asked
- a module can now publish no artifact, useful for virtual modules consisting only of integration of other modules
- now cache layout is configurable, using cacheIvyPattern and cacheArtifactPattern attributes on conf element in ivyconf.xml
- changed default cache layout: artifacts are separated by type
- added cachepath task, which enables to build an ant path of artifacts in cache required for a conf

Downloads

ivy-0.8-bin.zip (946 kB)
ivy-0.8-src.zip (761 kB)
ivy-0.8-src-withdep.zip (1024 kB)

0.9 - 2005-04-06

Changes log

Note: this version is not compatible with preceding ones.
The way to indicate patterns (in configuration as well as in some tasks) has changed: brackets are used for tokens instead of ant notation, which is kept for variables.
Thus a pattern previously noted:
${repository.dir}/${organisation}/${module}/${artifact}-${revision}.${ext}
will now be:
${repository.dir}/[organisation]/[module]/[artifact]-[revision].[ext]

This has been done to prevent collision and make a better separation between variables and tokens.
Moreover migration costs should not be too high, ivy files not being concerned by the change.

- ChainResolver are now able to publish (delegating the call to the first resolver in the chain)
- DualResolver sub resolvers are now registered in Ivy
- more precise message on eviction
- add validate attribute on most resolvers
- ivy files validation handling review
- use ivy variables in ant tasks to get default values for attributes
- documentation update for configuring ivy
- FIX: dependencies order not taken into account during resolve
- FIX: evicting modules also evict confs
- FIX: NPE during resolve when a dependency ivy file has no publication date
- FIX: check nullity of artifact download reports

Downloads

ivy-0.9-bin.zip (958 kB)
ivy-0.9-src.zip (776 kB)
ivy-0.9-src-withdep.zip (1039 kB)

1.0 - 2005-04-26

1.0-rc3 has been promoted to 1.0 on 2005-04-26

See child pages for details about changes introduced by each release candidate

Known bugs and limitations:
- cyclic dependencies result in StackOverflowError
- infinite loop in rare cases when a conflict occur between a latest subversion and a fully resolved revision
- url connections not closed properly when not using commons-httpclient
- latest does not work with http urls in some cases, when the name of the link is truncated in the web page

Downloads

ivy-1.0-bin.zip (1166 kB)
ivy-1.0-src.zip (904 kB)
ivy-1.0-src-withdep.zip (1167 kB)

1.0-rc1 - 2005-04-12

Changes log

- add report task, which enables to generates reports of dependencies, including a graph ready to be layed out by yEd
- add exclude feature in dependency
- include exclude feature now handles regexps
- new latest strategy: latest revision now uses a "php version_compare" like algorithm, whereas lexicographic comparison is now available in latest lexicographic
- enhance xml resolve report details
- FIX: better separation between root configurations
- FIX: XmlModuleDescriptorUpdater now preserves xml header
- FIX: modules figures in report (displayed at the end of resolve)

Downloads

ivy-1.0-rc1-bin.zip (1161 kB)
ivy-1.0-rc1-src.zip (984 kB)
ivy-1.0-rc1-src-withdep.zip (1247 kB)

1.0-rc2 - 2005-04-18

Changes log

- IMPROVE: improved messages: more debug, more verbose, and more details on failures
- FIX: bug with '\' in path patterns
- FIX: bug with relative paths patterns
- FIX: configure task tries ivy.conf.file as relative to base dir and to current dir
- FIX: file system resolver publishes ivy files with ivy pattern
- FIX: 0 content length considered as non existing (behaviour of jre 5.0 on linux)
=> empty ressources are now considered as non existing

Downloads

ivy-1.0-rc2-bin.zip (1164 kB)
ivy-1.0-rc2-src.zip (987 kB)
ivy-1.0-rc2-src-withdep.zip (1250 kB)

1.0-rc3 - 2005-04-21

Changes log

A few bugs have been discovered in the 1.0-rc2, so here is the reason for this rc3, which should fix these bugs.
If no bug is discovered, 1.0-rc3 should be promoted to 1.0 on 2005-04-26

- IMPROVE: added debug messages on variables setting
- FIX: ivyconf now able to load a properties file given as url
- FIX: deliver pub date now actually defaults to 'now'
- FIX: all tasks attributes now substitute ivy variables

Downloads

ivy-1.0-rc3-bin.zip (1168 kB)
ivy-1.0-rc3-src.zip (993 kB)
ivy-1.0-rc3-src-withdep.zip (1256 kB)

1.1 - 2005-06-13

Changes log

- remote configuration (if available) of ivyrep and ibiblio patterns and roots
- new detailed messages when ivy fails to reach an url (thanks to Nicolas)
- new artifactproperty task, which enables to set a property for each dependency artifacts resolved by ivy
- new defaultconf attribute in ivy file dependencies, to change the default conf to use in the file when no conf is specified for a dependency
- add the ability to change the xsl file and report name pattern used by report task
- http listing now compatible with tomcat listing (tested with 5.0.28)
- pub revision in deliver task now defaults to timestamp if not provided by any other way
- debug messages improvements, with configuration dump among others
- new var task, enables to set ivy variables from ant
- now defaults for ivyrep and ibiblio resolver are configurable by variables
- refactoring: introduce the notion of BasicResolver, Repository, Resource, RepositoryResolver, making much easier the task of writing basic resolvers
- added checkmodified attribute on all basic resolvers, which defaults to ${ivy.resolver.default.check.modified}
This makes ivy check last modified date of ivy files to see it its cache is up to date
- artifacts download are now first made to a temp file, which is renamed only at the end of the download.
This prevent interrupted downloads to be considered as finished
- FIX: handle proxy configuration with http-client (thanks to Nicolas)
- FIX: remove dependency on ant outside of ant integration classes
- FIX: resolve problem when conflicts on latest revisions
- FIX: allow use of any kind of URL in IvyRepResolver (both ivyroot and artroot) and IBibiblioResolver
- FIX: chain resolver can now be used for artifacts part of dual resolver
- FIX: now detects and warn about circular dependencies
- FIX: cachepath task now takes pathid as parameter instead of id, to prevent
special handling from ant
- FIX: ivy.xsd: set artifact minOccurs to 0 in publications

Thanks to John Shields from Robert Half International, Inc.:
- FIX: no more infinite loop when a conflict occurs between a latest subversion and a fully resolved revision
- FIX: BasicURLHandler now closes its connections
- FIX: ApacheURLLister now works with capital letter in revisions and truncated names
- now use of ivy variables is allowed in ivy files
- added a null check in pattern helper substitute

Downloads

ivy-1.1-bin.zip (999 kB)
ivy-1.1-src.zip (738 kB)
ivy-1.1-src-withdep.zip (1001 kB)

1.2a - 2005-09-16

Changes log

Note: due to a bad delivery operation, version 1.2 found on this site from 2005-09-14 to 2005-09-16 was not the intended 1.2 version. Please use 1.2a instead

- new ivy.deps.changed property set if there are changes since last resolve (IVY-71)
- new buildlist task: calculate order of dependencies of subprojects for easy multi-projects builds (IVY-69)
- accept organization as token (IVY-55)
- added type filtering mechanism on resolve task (IVY-45)
- detect and warn about resolver using ivy cache as repository (IVY-53)
- new transitive attribute on dependency, which enable to disable transitive dependency management on a particular dependency (thanks to Ingo Adler) (IVY-20)
- new '@' in dependency configuration mapping declaration, used to indicate that a configuration maps to itself useful with *, '*->@' meaning that all configurations of the module maps to their equivalent (same name) in the dependency (IVY-52)
- new changing attribute on dependencies indicate that the dependency artifacts may change even without revision change, but with only a new ivy file with new publication date
- new useRemoteConfig on conf tag in ivyconf.xml, tells to use remote configuration file for repository config
- new type filtering in cachepath task
- new cachefileset task: builds an ant fileset of artifacts in cache
- publish task now uses srcivypattern for ivy files finding and for delivery
- better debug and error messages (IVY-60 IVY-61)
- added a javadoc target in ant build (thanks to joshua nichols)

- FIX: module descriptors sort was failing in some case cases (fix by Karl Baum)
- FIX: Ivy complains about schema directive (IVY-64)
- FIX: 'null' status attribute in module descriptor (IVY-62)
- FIX: report header contains incorrect link after resolve for multiple, comma-separated configurations (IVY-57)
- FIX: error retrieving dependencies with a '+' in their revision if the ivy file doesn't exist - fixed by maarten coene (IVY-59)
- FIX: trying to resolve latest with no revision in pattern caused a StackOverflowError (IVY-56)
- FIX: now handle transitive eviction (IVY-51)
- FIX: resolve now store resolved file id in ivy variables, so that multiple resolve calls can be followed by multiple retrieve, each retrieve will use the last resolve info (IVY-49)
- FIX: IllegalStateException on retrieve done from command line
- FIX: checks ivy files data consistency with asked info (org, module name and revision)
- FIX: use AUTH configuration for configuration file
- IMPROVE: added publish handling from command line (IVY-48)

Downloads

ivy-1.2a-bin.zip (1028 kB)
ivy-1.2a-src.zip (776 kB)
ivy-1.2a-src-withdep.zip (1040 kB)

1.3 - 2006-03-17

Changes log

Ivy 1.3-RC3 has been promoted to 1.3 on 2006-03-17.

For known bugs and limitations please see http://jira.jayasoft.org/

For detailed list of changes since 1.2a, please see changes of the three release candidates below.

Downloads

ivy-1.3-bin.zip (1.52 MB)
ivy-1.3-src.zip (1.21 MB)
ivy-1.3-src-withdep.zip (1.59 MB)

1.3-RC1 - 2006-01-25

Changes log

compatiblity with previous version:
- the default place for the cache has changed, it is now in {USER_HOME}/.ivy/cache, instead of {USER_HOME}/.ivy-cache
please move this directory if you want to avoid unnecessary downloads
- modules are now logged as they are found, set ivy.log.module.when.found variable to false to avoid this

- NEW: namespace system: a resolver can be declared to belong to a namespace, which itself specify the transformation to apply to convert it from and to system namespace (IVY-147)
- NEW: pluggable module descriptor parsers let define new kind of module descriptor (IVY-146) (thanks to Maarten Coene)
- NEW: a new install task let add modules found in a repository in another one, even transitively (IVY-141)
- NEW: maven2 pom compatibility: most resolvers are now able to handle m2 pom as project metadata and there is a new convertpom task able to convert a pom file to an ivy file (IVY-140)
- NEW: include configurations from external file (IVY-88)
- NEW: a new default resolver which let override ivy files and artifacts found on public repository (ivyrep / ibiblio) and let publish modules in a local repository (IVY-132)
- NEW: ivyconf file inclusion in ivyconf files (IVY-99)
- NEW: macrodef feature in ivyconf for defining macro resolvers with parameters (IVY-98)
- NEW: conf fallback mechanism (IVY-145)
- NEW: exclusion now let exclude whole modules (IVY-144)
- NEW: ability to use a dependency instead of an ivy file in standalone mode (IVY-96)
- NEW: ability to output a path of dependencies in cache from the standalone mode (IVY-92)
- NEW: it is now possible to reference existing resolver in resolver containers (IVY-35)
- NEW: overwrite attribute in the publish task now let force overwrite of read only files (IVY-83)
- NEW: add a conflict manager ("strict") making build fail when a diamond conflict is found (thanks to Christer Jonsson) (IVY-118)

- IMPROVE: generate xml report using ivy:report task (IVY-143)
- IMPROVE: possibility to configure ivy so that special revisions are not queried as fixed one at all (IVY-139)
- IMPROVE: better url querying management (IVY-138) (thanks to Bernard Niset)
- IMPROVE: do not add resolver info in ivy files in cache so that they can be safely used as usual ivy files in a repository (IVY-137)
- IMPROVE: review default conf mapping management (IVY-134)
- IMPROVE: add possibility for a chain to behave like a dual chain (IVY-131)
- IMPROVE: add possibility to avoid overwrite of an ivy variable when setting them in ivyconf.xml (IVY-127)
- IMPROVE: ability to exclude the root project from the buildlist (thanks to Constantine Vetoshev) (IVY-124)
- IMPROVE: exclusion of artifacts now works on transitive artifacts, and exclusion can specify organisation and/or module (IVY-116)
- IMPROVE: now dynamic revisions replacement by deliver task can be turned off (IVY-120)
- IMPROVE: better performance with deep transitive dependencies
- IMPROVE: allow optional parts in the patterns (IVY-102) (thanks to Maarten Coene)
- IMPROVE: ability to define variable directly in ivyconf.xml (IVY-100)
- IMPROVE: ability to use no revision in pattern with latest.integration dependency, artifacts being updated according to revision change in ivy file (if checkmodified is set to true) (IVY-95)
- IMPROVE: ability to specify a root module in buildlist to filter out unnecessary build files (IVY-93) (thanks to Kristian Cibulskis)
- IMPROVE: import system properties as ivy variables in standalone mode
- IMPROVE: string identifying a module is now clearly different from a path
- IMPROVE: better error message when publish fails due to readonly destination (IVY-83)
- IMPROVE: some javadoc improvements (IVY-136 IVY-129) (thanks to Stephen Nesbitt)

- FIX: problem resolving dependencies when 2 module versions have different configurations (IVY-151)
- FIX: problem with inheritance between public and private conf (IVY-149)
- FIX: no variable replacement during the deliver step (IVY-133)
- FIX: conflict badly solved in some complex cases (IVY-130)
- FIX: mapping on conf * now only takes public configurations (IVY-126)
- FIX: bad dependency ivy files now causes failure (IVY-112)
- FIX: stack overflow error in contradictory conflict cases (IVY-117)
- FIX: publish now doesn't call deliver when not necessary (IVY-119)
- FIX: cachefileset was returning all artifacts for empty configuration (IVY-108)
- FIX: transitive and changing attribute were not copied in ivy files in cache (IVY-94)
- FIX: chain resolver now support latest strategy configuration (IVY-90)
- FIX: raise a clean error when a cyclic variable definition is found (IVY-75)
- FIX: clean ant project reference at the end of the build to improve usability in ide launching multiple builds in the same vm (like netbeans) (IVY-87 - IVY-115)
- FIX: ivy is now able to use simple ivy files in cache (doesn't need resolver info, use default one if no resolver is given) (IVY-86)
- FIX: private conf not accessible from other modules (IVY-76)
- FIX: root module configurations isolation bug fixed (IVY-84)
- FIX: changed the place where ivy stores master ivy files in cache to not overlap with dependencies one (IVY-85)
- FIX: bug in ResourceHelper didn't let override resource easily (IVY-80)
- FIX: throws a circular dependency exception when a circular dependency is found instead of failing silently (IVY-79)

Downloads

ivy-1.3-RC1-bin.zip (1.41 MB)
ivy-1.3-RC1-src.zip (1.15 MB)
ivy-1.3-RC1-src-withdep.zip (1.48 MB)

1.3-RC2 - 2006-02-15

Changes log

- IMPROVE: ivy now supports ${pom.version} in poms (IVY-174)
- IMPROVE: adds the possibility to disable concistency check (IVY-163)
- IMPROVE: add possibility to choose matcher on include exclude and conflict manager rules in ivy files, and on resolver per module in ivyconf (IVY-161)
- IMPROVE: add regexp management in the install ant task (IVY-154)

- FIX: httclient is not registered for https urls (IVY-171)
- FIX: post resolve tasks like retrieve or cachepath should be able to run from cache information (IVY-169)
- FIX: resolve fails without appropriate message when cache is empty and a module in the repository has no revision (IVY-165)
- FIX: resolve problem with configuration inheritance (IVY-164)
- FIX: some files in cache detected by not used by Ivy for subsequent retrieves (IVY-159)
- FIX: HTML report shouldn't display the dependencies of evicted modules (IVY-158) (thanks to Maarten Coene)
- FIX: bug when an organisation or module or revision contains a space (IVY-157)
- FIX: cos-nonambig warnings (IVY-156)

Downloads

ivy-1.3-RC2-bin.zip (1.53 MB)
ivy-1.3-RC2-src.zip (1.22 MB)
ivy-1.3-RC2-src-withdep.zip (1.60 MB)

1.3-RC3 - 2006-03-06

Changes log

- IMPROVE: Retrieve task now also optionally do ivy file downloads (IVY-167) (with the contribution of Costin Leau)

- FIX: ivy variable substitution in ivy files (IVY-186)
- FIX: force attribute is not treated as it should in some cases (IVY-182)
- FIX: problem reading 'invalid' POMs (IVY-153)
- FIX: cryptic NPE due to spelling error in ivy.xml (IVY-177)
- FIX: conflicts with dynamic revisions not resolved properly (IVY-181)
- FIX: incorrect configuration definition gives misleading NullPointerException (IVY-175)
- FIX: throw an error when using a non-existing conflict manager as default (IVY-179) (thanks to Maarten Coene)
- FIX: eviction problem with different conflicts in multiple confs (IVY-173)

Downloads

ivy-1.3-RC3-bin.zip (1.56 MB)
ivy-1.3-RC3-src.zip (1.26 MB)
ivy-1.3-RC3-src-withdep.zip (1.64 MB)

1.3.1 - 2006-03-30

Changes log

This version is bugfix release, upgrade from 1.3 is strongly recommended.
- FIX: retrieval of multiple artifacts in different configurations does not work as expected (IVY-188)
- FIX: configuration http url include doesn't work with commons http client (IVY-203)
- FIX: problem with conflict resolution in transitive dependencies (IVY-199)
- FIX: pb with force when it comes after a conflict which has already been solved (IVY-193)
- FIX: POM files that reference to the parent artifact download fails (IVY-195) (thanks to Tat Leung)
- FIX: M2 compatibility does not take into account the . replacement for publishing artifacts (IVY-191) (thanks to Peter Hayes)
- FIX: artifactproperty does not set the [conf] token in the pattern to the correct value. It is always set to 'default'. (IVY-123) (thanks to Peter Oxenham)

Downloads

ivy-1.3.1-bin.zip (1.57 MB)
ivy-1.3.1-src.zip (1.27 MB)
ivy-1.3.1-src-withdep.zip (1.65 MB)
ivy-doc-1.3.1.zip (1.6MB) (New! Easily browsable offline)
ivy-1.3.1.jar

Note: the zips distributed here before 2006-04-14 didn't include ivy.xml for ivy itself. This is now fixed, for those who want to get it you can find it here:
ivy-1.3.1.xml

1.4 - 2006-10-09

Changes log

Ivy 1.4-RC2 has been promoted to 1.4 on 2006-10-09

Known bugs and limitations:
- references in resolvers are not resolved 'in-time' with macrodef (IVY-319)
- latest. does not work properly when no matching revision exist (IVY-318)
- IVY complains about non-existent reports in the cache directory (IVY-315)
- retrieve fails when resolve is done with useOrigin set to true (IVY-304)

For detailed list of changes since 1.3.1, please see changes of the two release candidates detailed in child pages.
For an overview of what's new and noteworthy in this release since 1.3 see the new and noteworthy section below.

Downloads

ivy-1.4-bin.zip
ivy-1.4-src.zip
ivy-1.4-doc.zip

New and noteworthy

Documentation

A new introduction tutorial as simple as 1-2-3

It has never been so easy to try Ivy! You don't even need to install it yourself! Follow this simple steps and you're done:

  1. make sure you have ant 1.6.2 or greater and a jdk properly installed
  2. copy this build file in an empty directory on your local filesystem (and make sure you name it build.xml)
  3. open a console in this directory and run "ant". That's it!

If you have any trouble, check the FAQ, it may be related to your internet connection (proxy anyone?).
Want to try more tutorials? Check the tutorials page in the documentation.

Offline documentation greatly improved

The offline documentation has been greatly improved, and is now a real copy of the online documentation, with all the navigation between pages as on the online version. Continue to use the online version when you can to have the latest updated version with user comments.

Documentation update

As usual, the documentation has been extensively updated with to reflect the new features. Some are still missing, but we will finish the update before the 1.4 release.

Moreover, more examples have been added, more links between the pages, and some very useful pages have been added like the best practices one.

Core features

Extra attributes

Several tags in ivy xml files are now extensible with extra attributes.

The idea is very simple: if you need some more information to define your modules, you can add the attribute you want and you will then be able to access it as any other attribute in your patterns for example.

Example:
Here is an ivy file with the attribute 'color' set to blue:

<ivy-module version="1.4">
<info organisation="jayasoft"
      module="foo"
      color="blue"
      status="integration"
      revision="1.59"
/>
</ivy-module>

Then you can use the extra attribute when you declare a dependency on foo:

<dependency org="jayasoft" name="foo" color="blue" rev="1.5+" />

And you can define your repository pattern as:

${repository.dir}/[organisation]/[module]/[color]/[revision]/[artifact].[ext]

Note that in order to use extra attributes, you will need to disable ivy file validation, since your files won't fulffill anymore the official ivy xsd. See the configuration doc page to see how to disable validation.

Version matchers

Ivy now rely on a new concept to specify which version of a dependency should be used: pluggable version matchers.
This means that you can define your own way to match a dependency version.

Both latest.integration and latest sub version (1.3+ for instance) have been ported to this mechanism.

With this new feature Ivy also comes with two new built-in version matchers:

  • latest.[any status]
  • selects the latest revision of the dependency module with at least the specified status.

  • version ranges
  • You can now express your version contraint as a mathematical range.

Examples:

<dependency org="foo" name="bar" rev="latest.milestone" />

Will find the latest version of bar which is in milestone or release status.

<dependency org="foo" name="bar" rev="[1.0,2.0]" />

Matches any revision greater than 1.0 and lower than 2.0, inclusive.

URL attribute on artifact to improve ease of use

The artifact tag used when declaring a dependency now supports an url attribute. Even if this should be used only in very special cases (because it derrogates to the standard repository management), it can be useful, well, in very special cases :-)

Example:

<dependency org="foo" name="bar" rev="1.0">
  <artifact name="baz" type="jar" url="http://www.acme.com/repository/bar/baz-1.0-acme.jar"/>
</dependency>

Module configurations enhancements

Several improvements have been made on the module configurations:

  • It is now possible to disable transitivity for a whole configuration.

    Example:

    <conf name="compile" extends="core" transitive="false" visibility="private" />
  • You can use *, *(public) or *(private) as wildcards to extend a set of configurations.

    Example:

    <conf name="all" extends="*" />
  • You can use *, !A, !B in configurations mapping to mean all configurations but A and B.

    Example:

    <dependency name="commons-lang" rev="1.0" conf="*, !deploy->default" />

Events and triggers

Ivy now fires events all along the dependency resolution process, which can be listened and which can trigger events.

Example:

<triggers>
    <ant-build antfile="${ivy.conf.dir}/[module]/build.xml" target="publish"
          event="pre-resolve-dependency" filter="revision=latest.integration"/>
</triggers>

Triggers an ant build just before resolving a dependency with a latest.integration revision.

New Resolvers

vfs

The new vfs resolver leverages the work from apache commons vfs to give a uniform access to a set of different file systems including ftp, sftp, webdav, zip, ...

Example:

<vfs name="remote">
  <ivy pattern="webdav://username:password@host:8080/[organisation]/[module]/[revision]/ivy.xml" />
  <artifact pattern="webdav://username:password@host:8080/[organisation]/[module]/[revision]/[artifact].[ext]" />
</vfs>

ssh and sftp

The new ssh and sftp resolvers allow, as their name suggest, to access a repository using ssh or sftp. The secured nature of ssh and its wide spread implementation on most *nix servers makes these resolvers very good candidate in an enterprise environment.

Example:

<sftp name="secured" keyFile="path/to/key/file" keyFilePassword="${password}">
  <ivy pattern="sftp://user:xavier@yourserver.com:8022/path/to/repos/[module]/[revision]/ivy.xml"/>
  <artifact pattern="sftp://user:xavier@myserver.com:8022/path/to/my/repos/[artifact].[ext]"/>
</sftp>

Configuration files

Configurable statuses

The list of statuses available in module files is now configurable.

Example:

<statuses default="bronze">
  <status name="gold" integration="false"/>
  <status name="silver" integration="false"/>
  <status name="bronze" integration="true"/>
</statuses>

Per module settings

It is now possible possible to configure conflict-manager per module set.

Example:

<modules>
  <module organisation="jayasoft" name="ivy*" matcher="glob" conflict-manager="latest-time"/>
</modules>

Checksums

Ivy now allow to use checksums to verify the correctness of a downloaded file.

For the moment Ivy supports md5 and sha1 algorithm.

The configuration of using md5 and/or sha1 can be done globally or by dependency resolver.
Globally, use the ivy.checksums variable to list the check to be done (only md5 and sha1 are supported).
On each resolver you can use the checksums attribute to override the global setting.

The setting is a comma separated list of checksum algorithm to use.
During checking (at download time), the first checksum found is checked, and that's all. This means that if you have a "sha1, md5" setting, then if ivy finds a sha1 file, it will compare the downloaded file sha1 against this sha1, and if the comparison is ok, it will assume the file is ok. If no sha1 file is found, it will look for a md5 file. If none is found no checking is done.
During publish, all listed checksum algorithms are computed and uploaded.

By default checksum algorithms are "sha1, md5".

Fail when no module descriptor is found

By default when ivy doesn't find a module descriptor for a module, it lloks for an artifact, and if it finds one it assumes a default module descriptor.
It is now possible to configure this behaviour per resolver, by setting the allownomd attribute to false you can force the use of a module descriptor, and fail if none is found. This is also useful to improve performances on a resolver for which you know you will always have module descriptors.

System properties

All java system properties are now available as ivy variables in your configuration files.
Thus you can now easily define the default cache relative to user home (using ${user.home}), or access any specific property set via the standard java system property mechanism.

Changing pattern

You can now define a changingPattern and a changingMatcher to configure a set of revisions which should always be considered as changing one (artifacts are checked to see if they are up to date).

The pattern and the matcher name are attributes available on all built-in resolvers.

Example:

<filesystem name="local" changingPattern="*-SNAPSHOT" changingMatcher="glob">

will consider all modules with a revision ending by SNAPSHOT to be changing revisions.

Customisable classpath

You can now add jars to use to load plugins directly in ivy configuration, so that you can easily use your plugins in several execution environment (ant, standalone, IDE plugin, ...).

Example:

<ivyconf>
  <classpath file="${ivy.conf.dir}/custom-resolver.jar"/>
  <typedef name="custom" classname="fr.jayasoft.ivy.resolver.CustomResolver"/>
  <resolvers>
    <custom name="custom"/>
  </resolvers>
</ivyconf>

Ant tasks

repreport

A new repreport task allows to generate reports directly from your repository. The graph generation is the most interesting one, it can gives you a good overview of the dependencies between of all your modules available in your repository, or restrict this graph to just the modules from this organisation, and so on.

Example:

<ivy:repreport organisation="myorg" xml="false" graph="true" />
will generate a graphml of dependencies with all modules in the organisation "myorg"

artifactreport

A new artifactreport task has been introduced to easily generate an xml report with artifacts resolved, with useful information such as their original location. This report is particularly well suited for generating IDE classpaths (see also the links page for higher IDE integration via plugins).

The generated report looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<modules>
  <module organisation="hippo" name="sant-classes" rev="1.01.00b04-dev" status="integration">
    <artifact name="sant-classes-src" ext="zip" type="zip">
      <origin-location is-local="true">
        C:/home/jstuyts/data/ivy/local/hippo/sant-classes/1.01.00b04-dev/sant-classes-src-1.01.00b04-dev.zip</origin-location>
      <cache-location>
        C:/home/jstuyts/data/ivy/cache/hippo/sant-classes/zips/sant-classes-src-1.01.00b04-dev.zip</cache-location>
      <retrieve-location>lib/test/sant-classes-src-1.01.00b04-dev.zip</retrieve-location>
    </artifact>
  </module>
  <module organisation="testng" name="testng" rev="4.6.1-jdk15" status="release">
    <artifact name="testng" ext="jar" type="jar">
      <origin-location is-local="false">
        <a href="http://repository.hippocms.org/maven/testng/jars/testng-4.6.1-jdk15.jar</origin-location>" title="http://repository.hippocms.org/maven/testng/jars/testng-4.6.1-jdk15.jar</origin-location>">http://repository.hippocms.org/maven/testng/jars/testng-4.6.1-jdk15.jar<...</a>
      <cache-location>C:/home/jstuyts/data/ivy/cache/testng/testng/jars/testng-4.6.1-jdk15.jar</cache-location>
      <retrieve-location>lib/test/testng-4.6.1-jdk15.jar</retrieve-location>
    </artifact>
  </module>

info

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

Example:

<ivy:info file="${basedir}/path/to/ivy.xml" />

listmodules

The new listmodules task let you list modules available in the repository and set ant properties accordingly.

Example:

<ivy:listmodules organisation="jayasoft" module="ivy" revision="*" property="ivy.[revision]" value=="found"/>

findrevision

This new task sets an ant property with the latest revision found for a given module matching a given revision constraint.

<ivy:findrevision organisation="jayasoft" module="ivy" revision="1.0+"/>

useOrigin

The resolve, cachepath, and retrieve tasks now supports a new useOrigin attribute, which allow to use the original location of local artifacts instead of their location in ivy cache. Used directly on a resolve or when no resolve has been done, it will avoid the copy of the artifact to the cache, and use directly the artifact from its original location.

<cachepath pathid="default.classpath" conf="default" useOrigin="true" />

Disable transitive dependencies on resolve

You can now disable transitive dependencies on resolve.

Example:

<ivy:resolve file="path/to/ivy.xml" transitive="false" />

Synchronization feature in retrieve

The retrieve task can now performs a real synchronization of the destination directory, instead of a simple copy.

Example:

<ivy:retrieve pattern="${lib.dir}/[conf]/[artifact].[ext]" sync="true" />

Standalone mode

Application launcher

Ivy can now be used as an application launcher:

java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -dependency bar foo 2.0 -main org.bar.foo.FooMain

calls ivy with given ivyconf file and resolve bar foo 2.0, and then run org.foo.FooMain class with the resolved artifacts (foo 2.0 and its dependencies) as classpath

1.4-RC1 - 2006-09-17

Here are the release notes of version 1.4-RC1.
A new and noteworthy section is available on version 1.4 page.

You can download it here:

It includes 30 new features, 33 improvements and even more bug fixes since Ivy 1.3.1.

  version 1.4-RC1 - 2006-09-17
=================================
Incompatibility with previous versions:
---------------------------------------
* usage:
  - no known major incompatiblity
  - build list task now requires a configured ivy instance (configure will automatically be called if you don't call it explicitly)
  - publish now requires the published ivy file to have the published revision (automatic if you use deliver)
* API:
  - Numerous API changes especially in the BasicResolver class and subclasses due to the introduction of VersionMatcher,
  this may break some custom dependency resolvers or other tools or plugins depending directly on Ivy API
Changes:
--------
* thanks to Jayasoft:
  - NEW: ivy report generate full graph from automated build (IVY-155)
  - NEW: support for build number calculation (IVY-276)
  - NEW: find modules in repository (IVY-275)
  - NEW: explicitly specify artifact download URL (IVY-271)
  - NEW: introduce branch management (IVY-269)
  - NEW: resolve dependencies directly without using an ivy file (IVY-268)
  - NEW: ability to invoke any build scripts for dependencies (IVY-68)
  - NEW: support sftp repository (IVY-267)
  - NEW: pluggable version matcher (IVY-219)
  - NEW: support for version ranges (IVY-295)
  - NEW: dependency based on dependency status (IVY-47)
  - NEW: add possibility to define extra attributes in ivy files (IVY-217)
  - NEW: option to omit specific confs and allow the rest (IVY-66)
  - NEW: use custom classloader for plugins (IVY-220)
  - NEW: adding to SPECIAL_MEANINGS in LatestRevisionStrategy (IVY-121)
  - NEW: Allow use of system properties in ivyconf.xml (IVY-228)
  - IMPROVE: allow to use file-system repository directly without cache (IVY-211)
  - IMPROVE: deliver task use a default value for revision (IVY-252)
  - IMPROVE: better documentation distribution (IVY-274) - in progress
  - IMPROVE: define conflict manager per organisation/module in ivyconf (IVY-270)
  - IMPROVE: transitive parameter in resolve (IVY-21)
  - IMPROVE: add syncing feature in retrieve (IVY-33)
  - IMPROVE: use of md5 and/or sha1 files to check downloads (IVY-27)
  - IMPROVE: possible to use m2compatible without automatically using POMs as well (IVY-263)
  - IMPROVE: support for circular dependencies (IVY-202)
  - IMPROVE: make status list configurable (IVY-242)
  - IMPROVE: use only ivy patterns for listing revisions when module desciptor is required (allownomd = false) (IVY-166)
  - IMPROVE: implement strict haltonfailure if ivy.xml is not found (IVY-110)
  - IMPROVE: artifact's "name" attribute could be omitted (IVY-231)
  - IMPROVE: ivy standalone now return error status (IVY-152)
  - IMPROVE: log messages do not display most specfic resolver name (IVY-170)
  - IMPROVE: prints URL before downloading in verbose mode (IVY-257)
  - IMPROVE: incorrect value in status attribute causes silent failure (IVY-259)
  - IMPROVE: suport empty dependencies tag in an ivy file (IVY-281)
  - IMPROVE: isolate dependency resolution from artifact downloading (IVY-254)
  - IMPROVE: Pass artifact to repository when calling "put" (IVY-192)
  - IMPROVE: Do not publish ivy file with bad revision, and allow to force the deliver when calling publish task (IVY-245)
  - FIX: Problem with multiple artifact includes in transitive dependencies (IVY-283)
  - FIX: Endless recursion in report (IVY-284)
  - FIX: http url lister doesn't work when link text has spaces (IVY-282)
  - FIX: Incorrect ant log level (IVY-279)
  - FIX: Wrong resolution of dependencies if artifacts specified explicitly (IVY-261)
  - FIX: Multiple versions of dependencies appearing in retrieve (IVY-264)
  - FIX: Too many false CircularDependencyException errors thrown (IVY-230)
  - FIX: CircularDependencyException not always thrown (IVY-184)
  - FIX: NullPointer in BasicResolver (IVY-258)
  - FIX: Bad diagnostics message when no space left (IVY-250)
  - FIX: Maven2 POM support can find groupId from "parent" element (IVY-262)
  - FIX: Parent version is expected to be equal to the module version in POM (IVY-241)
  - FIX: problem with cache and returnFirst (IVY-207)
  - FIX: modules splitted across a chain are not handled correctly (IVY-206)
  - FIX: problem with conf extension and latest revisions (IVY-240)
  - FIX: The clean-cache target in /src/example/hello-ivy/build.xml file refers to ${user.home}/.ivy-cache instead of ${user.home}/.ivy/cache/ (IVY-265)
* thanks to Ivy Community:
  - NEW: SSH Resolver added and aligned with SFTP resolver (IVY-273) (thanks to Andreas Sahlbach)
  - NEW: ability to turn off transitivity at configuration level (IVY-103) (thanks to Karl Baum and Maarten Coene)
  - NEW: a conflict manager that is able to allow implementation changes but not api changes (1.2.x - OK), (1.x.x - Not OK) (IVY-223) (thanks to Anders Janmyr)
  - NEW: enhance standalone mode to execute java program by creating classloader of dependant jars from cache (IVY-210) (thanks to Peter Hayes)
  - NEW: addition of Vfs Resolver which uses Commons-Vfs to resolve files (IVY-128) (thanks to Glen Marchesani, Matt Inger and Stephen Nesbitt)
  - IMPROVE: use global properties in the recursive delivery (IVY-222) (with the contribution of Roshan Punnoose)
  - IMPROVE: better handling of authentication (thanks to Christian Riege)
  - FIX: Ant log messsages not embedded in task log (IVY-280) (thanks to Gilles Scokart)
  - FIX: Ivy fails when downloading from a server that supports NTLM authentication (IVY-213) (thanks to Damon Rand)
  - FIX: Delivered Ivy files with incomplete last line. (IVY-125) (thanks to Matthias Kilian)
  - FIX: the vfs resolver should not log passwords (IVY-292) (thanks to Antoine Levy-Lambert)
* thanks to Maarten Coene:
  - NEW: add failureproperty parameter to the resolve task (IVY-285)
  - NEW: Add type filtering to retrieve task (IVY-260)
  - NEW: Add selectors to the configuration mapping (IVY-253)
  - NEW: Add Ant task to retrieve information from an Ivy file without doing a resolve (IVY-255)
  - NEW: add option to cachepath task to create a path with local artifact paths (IVY-221)
  - NEW: allow extending configurations to override the mapping of their super configurations (IVY-218)
  - IMPROVE: Retain artifact filenames along the publish/resolve/retrieve process (IVY-54)
  - IMPROVE: report Ant-task doesn't process the reports in batch (IVY-247)
  - IMPROVE: make ReportOutputter pluggable and customizable (IVY-205)
  - IMPROVE: add wildcard support for extending configurations (IVY-235)
  - IMPROVE: add support for xslt parameters in the report task (IVY-227)
  - IMPROVE: comments now aren't lost when delivering ivy files (IVY-226)
  - IMPROVE: add sort of 'fallback'-mapping to the defaultconfmapping attribute (IVY-215)
  - IMPROVE: artifact origin is not included in the default report (IVY-251)
  - FIX: VFS Resolve fails when trying to resolve a + version (IVY-237)
  - FIX: report Ant-task doesn't use outputpattern for generating graphml reports (IVY-246)
  - FIX: report Ant-task doesn't call init() on the internal XSLTProcess (IVY-248)
  - FIX: value of confmappingoverride from imported configurations is lost when writing Ivy file (IVY-239)
  - FIX: including configurations doesn't import the confmappingoverride setting (IVY-238)
  - FIX: NullPointerException when the creation of Ivy file in cache fails (IVY-234)
  - FIX: Ivy file containing 2 different versions of the same module is not deliverd correctly (IVY-229)
  - FIX: ModuleRevisionId encode/decode doesn't work if revision is empty (IVY-233)
  - FIX: cachepath task should preserve the order of the dependencies (IVY-225)
  - FIX: specifying a defaultconfmapping adds dependencies of each unlisted configuration (IVY-214)
* thanks to Johan Stuyts:
  - NEW: always update artifacts when revision matches a regex pattern (IVY-189)
  - NEW: provide Ant task for generating report about artifacts depended upon (IVY-194)
  - IMPROVE: change default cache artifact pattern to handle missing extension (IVY-196)
* thanks to Karl Baum:
  - NEW: "this" symbol for configuration mappings (IVY-183)
  - IMPROVE: performances improved (IVY-187)

1.4-RC2 - 2006-09-27

Here are the release notes of version 1.4-RC2.
A new and noteworthy section is available on version 1.4 page.

You can download it here:

It includes only bug fixes since 1.4-RC1.

  version 1.4-RC2 - 2006-09-27
=====================================
- FIX: m2compatible flag is ignored for display of failed artifact searches (IVY-303)
- FIX: AntCallTriggerTest and AntBuildTriggerTest fail when run from ivy build.xml (IVY-310)
- FIX: Classloader problem with ant (IVY-311)
- FIX: Make resolve overview more compact (IVY-299)
- FIX: Could not write to "tmp:///webdav_tmp.c1" because it is read-only (IVY-312)

1.4.1 - 2006-11-09

Ivy 1.4.1 is mainly a bug fix version, upgrade from 1.4 is strongly recommended.

It has been released on 2006-11-09.

Downloads

ivy-1.4.1-bin.zip
ivy-1.4.1-src.zip
ivy-1.4.1-doc.zip

Changes log

- IMPROVE: ability to rebuild all dependent projects from a leaf (IVY-101)
- IMPROVE: Artifact pattern list attribute for the ivy:publish (IVY-113)
- IMPROVE: Measure code coverage (IVY-323)
- IMPROVE: add release target to build file (IVY-339)
- IMPROVE: Add a 'conf' parameter to the ivy 'publish' ant task (IVY-322) (thanks to Emmanuel Pellereau)

- FIX: retrieve fails when resolve is done with useOrigin set to true (IVY-304)
- FIX: IVY complains about non-existent reports in the cache directory (IVY-315)
- FIX: Typo in failureproperty attribute of Ant resolve task (IVY-327) (thanks to Jean-Baptiste Quenot)
- FIX: ivy:resolve useOrigin fails to behave correctly (IVY-332)
- FIX: ChainVersionMatcher doesn't handle IvyAware children version matchers (IVY-331)
- FIX: latest.<status> does not work properly when no matching revision exist (IVY-318)
- FIX: attribute name in macrodef is not handled as expected (IVY-319)
- FIX: confmappingoverride doesn't work for configurations extending from "*(public)" (IVY-326)

Appendix

This section is the home of a bunch of appendixes to ivy main documentation.

IvyRep

IvyRep is the official ivy repository. For the moment, it only stores ivy files, artifacts being most of the time found on ibiblio.

You can find more information on ivyrep on its own home page:
http://ivyrep.jayasoft.org/.

Ivy / Maven2 Comparison

We are frequently asked how ivy compares to maven2, so we have decided togives some insight about our opinion on the subject.

Obviously this comparison is biased (hey, you are on official Ivy site :-)), but we'll try to keep it as fair as possible. Do not hesitate to add comment if you feel something is missing or false on this page. You can also have a look at Maven2 feature comparison page on codehaus, which itself offers another point of view.

There have been also severa discussions on the subject, among which the one triggered by spring contemplating about switching to maven is may be the more interesting.

But here is the points we think mainly differentiate maven2 and Ivy.

Comparing plants and apples

First, the most important difference between maven2 and ivy is that they aren't at all the same kind of tools. Maven2 is a software project management and comprehension tool, whereas Ivy is only a dependency management tool, highly integrated with ant, the popular build management tool. Maven2 offers dependency management facility, and that's why many ask how ivy compares to maven2. That's why we'll focus only on dependency management features of maven2 in this comparison.
So if you look for an out of the box software project management tool, you may skip the rest of this comparison and check what maven2 has to offer.

Different concepts

Ivy heavily relies on a unique concept called configuration. In ivy, a module configuration is a way to use or to see the module. For instance, you can have a test and runtime configuration in your module. But you can also have a mysql and an oracle configuration. Or an hibernate and a jdbc configuration. In each configuration you can declare what artifacts (jar, war, ...) are required. And in each configuration, you can declare your dependencies on other modules, and describe which configuration of the dependency you need. This is called configuration mapping, and it is a very flexible way to answer to a lot of problems we face very often in software development.

Maven2 on its side has something called the scope. You can declare a dependency as being part of the test scope, or the buildtime scope. Then depending on this scope you will get the dependency artifact (only one artifact per module in maven2) with its dependencies depending on their scope. Scopes are predefined in maven2 and you can't change that. No way to create an oracle scope. No way to indicate you need what as been declared to be needed in the runtime scope of your dependency in your compile one. Everything here is written in the marble.

And this leads to some kind of troubles... as Matt Raible stated in his blog talking about maven2 dependencies:
[quote]
There are a *lot* of unnecessary dependencies downloaded for many libraries. For example, Hibernate downloads a bunch of JBoss JARs and the Display Tag downloads all the various web framework JARs. I found myself excluding almost as many dependencies as I added.
[/quote]
The problem is that hibernate can be used with several cache implementations, several connection pool implementation, ... And this can't be managed with scopes, wheres Ivy configurations offers an elegant solution to this kind of problem. For instance, in ivy, assuming hibernate as an ivy file like this one, then you can declare a dependency like that:

<dependency org="hibernate" name="hibernate" rev="2.1.8" conf="default->proxool,oscache"/>

to get hibernate with its proxool and oscache implemetations, and like that:

<dependency org="hibernate" name="hibernate" rev="2.1.8" conf="default->dbcp,swarmcache"/>

to get hibernate with dbcp and swarmcache.

Documentation

An important thing to be able to use a tool is its amount of documentation. With Ivy, even if they are written in broken english (would you have prefered well written french :-)), the printer friendly version of the documentation is now about 120 pages.
With maven2, it's a bit difficult to clearly know what can be considered as dependency management documentation, but we didn't managed to find much: some small introductory guides, short entries in the pom reference guide, and not really much more. Even in the maven book you can get for free on mergere website, the insight about dependency management is still light in our point of view.

Conflict management

Conflict management are an important part of dependency management, cause when dealing with transitive dependencies you often have to face conflicts. In this area, Ivy let you do whatever you want: use one conflict manager in one module, another one elsewhere, decide which revision you will get, ... You can even plug your own conflict manager if you need to.

With maven2, conflict management is quite simple: the principle is to get the nearest definition. So if your module depends on foo 1.0, none of your dependencies will ever manage to get foo 1.1 without a change in your own dependency declaration. It may be ok in some cases, it may not in others...

Flexibility

In ivy many things can be configured, and many others can be plugged in: dependency resolvers, conflict manager, module descriptor parser, latest revision strategy, ... Maven2 also offers repository pluggability, but not much more as far as we know. Moreover, repository configuration seems to be less flexible than with ivy.

Public Repositories

Maven2 comes out of the box configured to use ibiblio maven2 repository, which contains a lot of modules (both artifacts and module descriptors). The only problem some may face is that module descriptors are not always checked, so some are not really well written.
Ivy, on its side, is used out of the box with ivyrep, ivy official repository, which contains only a few modules, and is not updated frequently. But it is also compatible with maven1 ibiblio repository (for artifacts only, no module descriptors), can also be used with maven2 repository (with pom compatibility, but you will here face some naming problems - that can be addressed using the namespace feature-, you won't benefit from ivy configurations with the module descriptors found there, and, let's face it, the maven2 compatibility of Ivy is far from maven's one :-)), and also has an ivyrep sandbox in which much more module descriptors can be found (not checked, as with ibiblio repository).