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.settings.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.settings.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">
        http://repository.hippocms.org/maven/testng/jars/testng-4.6.1-jdk15.jar
      </origin-location>
      <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