Documentation (2.2.0)
Welcome to the official Ivy documentation.
What is Ivy?
Ivy is a tool for managing (recording, tracking, resolving and reporting) project dependencies. It is characterized by the following:- flexibility and configurability - Ivy is essentially process agnostic and is not tied to any methodology or structure. Instead it provides the necessary flexibility and configurability to be adapted to a broad range of dependency management and build processes.
- tight integration with Apache Ant - while available as a standalone tool, Ivy works particularly well with Apache Ant providing a number of powerful Ant tasks ranging from dependency resolution to dependency reporting and publication.
Ivy has a lot of powerful features, the most popular and useful being its flexibility, integration with ant, and its strong transitive dependencies management engine.
The transitive dependencies management is a feature which lets you get dependencies of your dependencies, transitively. In order to address this general problem, ivy needs to find metadata about your modules, usually in an ivy file. To find the metadata and your dependencies' artifacts (usually jars), Ivy can be configured to use a lot of different repositories.
About this doc
Tip: The menu on the left is dynamic, you can click on the arrows to browse the menu without going to each page.
This documentation has been migrated from the old Ivy web site hosted by Jayasoft, feel free to report any problem on the mailing-lists.If you browse this documentation from your installation of Ivy, you can also check the online version for the latest updates.
You can also browse this documentation offline either by downloading the documentation distribution, or by checking out the doc directory from svn. This documentation uses xooki as its documentation engine, so you can very easily edit it and submit patches when you browse it from source.
A printer-friendly version of this whole documentation is also provided for your convenience.
Since Ivy 2.0.0-alpha-2, we keep an online history of the documentation. You can thus browse history versions online (in the history menu in the web site) and even check the trunk version documentation currently in development.
For earlier versions, we suggest downloading the documentation to browse the documentation corresponding to the version you use. The full history of Ivy versions with corresponding links for download is available in the history menu on the web site.
Other places to go
Check out Ivy features.Read our FAQ.
Ask for help on our mailing lists.
Report a bug or feature request in our issue tracking system.
Check external tools and resources.
Overview
This documentation is composed of three main parts:- Tutorials The tutorials is the best way to begin to play with Ivy. You will easily and quickly learn the basics of Ivy.
- Reference The reference documentation gives you all the details of Ivy.
- Developer doc The developers's doc is useful for users who would like to extend Ivy or build it from source. It's also the documentation used by the Ivy team, so you will also find information about how we make releases.
The introduction part is particularly useful: it defines some vocabulary, explains main concepts such as dependency resolvers and patterns, and gives an overview of how ivy works internally.
It's also in the reference doc that you will find all you always dreamed to know about ivy settings, ivy files, and ivy use (especially with ant).
Release Notes
Announcement
Sep 30, 2010 - The Ivy project is pleased to announce its 2.2.0 release.
Ivy is a tool for managing (recording, tracking, resolving and
reporting) project dependencies, characterized by flexibility,
configurability, and tight integration with Apache Ant.
Key features of the 2.2.0 release are
* enhanced Maven2 compatibility, with several bug fixes and more
pom features covered
* new parent mechanism for Ivy files
* improved pom generation from an ivy.xml file
* automated PGP signature generation when uploading artifacts
* numerous bug fixes as documented in Jira and in the release notes
We encourage all users of Ivy to update to this new version.
Issues should be reported to:
https://issues.apache.org/jira/browse/IVY
Download the 2.2.0 release at:
http://ant.apache.org/ivy/download.cgi
More information can be found on the Ivy website:
http://ant.apache.org/ivy/
Regards,
Maarten Coene
Release Notes
CONTENTS1. What is Apache Ivy?
2. How to Get Involved
3. How to Report Issues
4. Committers and Contributors for this release
5. List of Changes in this Release
1. What is Apache Ivy?
Apache Ivy is a tool for managing (recording, tracking, resolving and reporting)project dependencies.
It is characterized by the following:
1. flexibility and configurability
Apache Ivy is essentially process agnostic and is not tied to any
methodology or structure.
Instead it provides the necessary flexibility and configurability
to be adapted to a broad range of dependency management and build
processes.
2. tight integration with Apache Ant
while available as a standalone tool, Apache Ivy works particularly well
with Apache Ant providing a number of powerful Ant tasks ranging
from dependency resolution to dependency reporting and publication.
2. How to Get Involved
The Apache Ivy project really needs and appreciates any contributions,including documentation help, source code and feedback. If you are interested
in contributing, please visit http://ant.apache.org/ivy/get-involved.html.
3. How to Report Issues
The Apache Ivy project uses JIRA for issue tracking. Please report anyissues you find at http://issues.apache.org/jira/browse/IVY
4. Committers and Contributors for this Release
Here is the list of people who have contributed source code and documentation
to this release. Many thanks to all of them, and also to the whole Ivy community
contributing ideas and feedback, and promoting the use of Ivy. The list would be too
long, but Ivy couldn't be what it is without you!
Committers
Matt Benson
Maarten Coene
Xavier Hanin
Nicolas Lalevee
Jon Schneider
Gilles Scokart
Contributors
Andreas Axelsson
Jasper Blues
Jean-Louis Boudart
Dave Brosius
Flavio Coutinho da Costa
Stefan De Boey
Gregory Fernandez
Aaron Hachez
Achim Huegen
Anders Jacobsson
Steve Jones
Heschi Kreinick
Steve Miller
Abel Muino
J. Lewis Muir
Jesper Pedersen
Carl Quinn
Michael Scheetz
John Tinetti
Jason Trump
Richard Vowles
Sven Walter
For the list of people who have contributed since Ivy inception, see CHANGES.txt file.
5. List of Changes in this Release
For a full release history of Ivy see the file CHANGES.txt
For details about the following changes, check our JIRA install at
http://issues.apache.org/jira/browse/ivy
List of changes since Ivy 2.1.0:
- DOCUMENTATION: Spelling fixes on artifact description page (IVY-1230)
- DOCUMENTATION: Added missing documentation about the ivy:publish child elements.
- DOCUMENTATION: Grammar, spelling, and clarity of Settings File documentation (IVY-1216) (thanks to Steve Miller)
- DOCUMENTATION: Grammar, spelling, and clarity of Tutorial documentation (IVY-1222) (thanks to Steve Miller)
- DOCUMENTATION: Limit the width of running text in documentation (IVY-1030)
- DOCUMENTATION: Refer to the maven wiki instead of listing some maven2 mirrors ourselfs (IVY-491)
- DOCUMENTATION: Fixed several grammatical and typographic errors in documentation (IVY-1172) (thanks to J. Lewis Muir)
- DOCUMENTATION: ivy-doc.xsl does not show configurations (IVY-1151) (thanks to Jasper Blues)
- DOCUMENTATION: Added documentation of the 'changing' attribute on the ivy:resolve Ant task (IVY-1180)
- NEW: the ivy:makepom Ant task can use a custom template file to generate the pom.xml
- NEW: Ivy can now generate OpenPGP compatible ASCII armored detached signatures when publishing artifacts.
- NEW: Support ivy.xml parent mechanism (IVY-742) (thanks to Jason Trump and Jean-Louis Boudart)
- NEW: Make ivy.xml available (IVY-1158)
- IMPROVEMENT: the child of ivy:publish now accepts any attribute
- IMPROVEMENT: Handle attributes in description subelements (IVY-1214) (thanks to Jean-Louis Boudart)
- IMPROVEMENT: Use IvyAuthenticator only when it is really necessary (IVY-1211)
- IMPROVEMENT: MakePom task handling of mulitple artifacts for Maven2 (IVY-770) (thanks to Jesper Pedersen)
- IMPROVEMENT: ivy:makepom now has an option to disable the generation of an extra Ivy comment block in the POM
- IMPROVEMENT: ivy:makepom now accepts a list of configurations to include (IVY-1005) (thanks to Jesper Pedersen)
- IMPROVEMENT: ivy:makepom can generate a element in the pom (IVY-1215) (thanks to Jesper Pedersen)
- IMPROVEMENT: added support for 'gzip' and 'deflate' HTTP Content-Encoding (IVY-1194)
- IMPROVEMENT: retrieve doesn't retrive files if the current one is more recent (IVY-1044)
- IMPROVEMENT: better diagnostics when reporting bad ivy file in cache (IVY-1190)
- IMPROVEMENT: Support changing="true" for inline retrieve (IVY-1180)
- IMPROVEMENT: Enhance
- IMPROVEMENT: Ivy doesn't support Maven 2.0.9 'import' scope (IVY-807)
- IMPROVEMENT: resolver attribute for listmodules task (IVY-1057)
- IMPROVEMENT: discover 'src' sources in maven repos (IVY-1138)
- IMPROVEMENT: Trace a message when a property file referenced from the settings doesn't exixts (IVY-1074)
- IMPROVEMENT: use defaultconf in combination with defaultconfmapping (IVY-1135) (thanks to Jon Schneider)
- FIX: ApacheURLLister doesn't handle some truncated linknames properly (IVY-1232) (thanks to John Tinetti)
- FIX: Ivy cannot handle Maven pom with parents depending back on theirselfs (IVY-1225)
- FIX: artifactreport ant task doesn't honor log attribute (IVY-1212)
- FIX: XmlModuleDescriptorWriter does not write the transitive attribute (IVY-1207) (thanks to Abel Muino)
- FIX: Ivy info/extends/extendsType attribute is misspelled by XmlModuleDescriptorWriter (IVY-1203) (thanks to Jason Trump)
- FIX: The ivy-module version used by XmlModuleDescriptorWriter is hard coded to '1.0' (IVY-1199)
- FIX: makepom ignores artifact type in ivy.xml and hardcodes 'jar' in the output pom (IVY-736) (thanks to Aaron Hachez)
- FIX: Ant output wasn't always prefixed by the name of the Ivy task
- FIX: Resolved Ivy properties written to cache during ivy:resolve incorrectly represents forced revisions (IVY-1159)
- FIX: Namespace rules not properly applied to parent projects (IVY-1186)
- FIX: LatestVersionMatcher.needModuleDescriptor() does not honor custom statuses (IVY-1170) (thanks to Carl Quinn)
- FIX: Proxy authentication could fail when using commons-httpclient
- FIX: Packager resolver always extracts all files from archives even when the packaging instructions contains include tags (IVY-1179) (thanks to Stefan De Boey)
- FIX: Ivy cannot connect to URLs with '_' in their hostname
- FIX: Transitive dependencies resolutions issue when eviction is triggered (IVY-1178)
- FIX: Can't deal with [VERSION] version pattern from Maven (IVY-1177) (thanks to Richard Vowles)
- FIX: verbose/debug messages were not logged while running ivy:configure task
- FIX: ApacheURLLister does not allow directories not containing a dot on Artifactory (IVY-1175) (thanks to Anders Jacobsson)
- FIX: artifact-lock strategy could hang Ivy when resolving dynamic revisions
- FIX: Authentication won't work in some situations (IVY-1168) (thanks to Sven Walter)
- FIX: Using SFTP resolver with full pattern URL prevents use of dynamic versions (IVY-1167) (thanks to Gregory Fernandez)
- FIX: parent.groupId is not resolved in maven 2 parser (IVY-1169) (thanks to Achim Huegen)
- FIX: Creation of symlinks problematic in Windows with Cygwin 1.7 (IVY-1165)
- FIX: add ability to programmatically change default resolver (IVY-1163) (thanks to Jason Trump)
- FIX: ivy.settings.dir space escaping problem (IVY-1162)
- FIX: Ivy cannot parse alternate format for Maven MD5 files (IVY-1155)
- FIX: Ivy does not close URL connection to ivy-report.xsl properly (IVY-1152)
- FIX: Artifact report throws NPE when artifact is not in cache (IVY-1150) (thanks to Steve Jones)
- FIX: resolve fails for transitive relocated maven modules when the type of the dependency was set to 'jar'
- FIX: optional dependencies, sources and javadocs aren't resolved when a maven module is relocated
- FIX: Encountered 'multiple artifacts retrieved to same file' error when module does not have multiple artifacts (IVY-1148)
- FIX: Use of a shared DocumentBuilder causes SAXException during parallel resolutions (IVY-1147)
- FIX: metadata lock files not always deleted from cache (IVY-1145) (thanks to Jason Trump)
- FIX: FileSystem resolver with m2compatible=true throws error when publishing modules with dotted organisation names (IVY-968)
- FIX: ivy:retrieve sync="true" does nothing if first variable is optional (IVY-1142) (thanks to Andreas Axelsson)
- FIX: Latest Compatible Conflict Manager + Extra Attributes in Dependencies' IVY files == infinite loop (IVY-956)
- FIX: Resolve with Extra Attributes, Forced Dependencies causes invalid delivered ivy file (IVY-1079)
- FIX: ResolveEngine.getDependencies does not work using extra attributes (IVY-1115)
- FIX: ignored in dynamic resolve mode (IVY-1131)
- FIX: IvyNodeEviction.cleanEvicted has bad comparison logic (IVY-1118)
- FIX: ChainResolver doesn't pass the specified 'checkmodified' attribute to the cache (IVY-1133)
- FIX: Ivy couldn't handle maven POMs that depend on theirselves
- FIX: SearchEngine.listModules returns MRID without extra attributes (IVY-1128) (thanks to Michael Scheetz)
- FIX: IvyBuildNumber non-deterministic behaviour (IVY-1120)
- FIX: Change spelling of 'occured' to 'occurred' (IVY-1123)
- FIX: Ivy deliver fails to replace dynamic revision when using extra attributes (IVY-1111) (thanks to Michael Scheetz)
- FIX: IbiblioResolver not always correctly configured when using JRE 1.5 (IVY-1124) (thanks to Flavio Coutinho da Costa)
- FIX: VstfpRepository.readResponse uses bad compare logic (IVY-1119) (thanks to Dave Brosius)
- FIX: URLResource does not properly support authentication (IVY-1106) (thanks to Heschi Kreinick)
- FIX: Excessive hits to missing URLs uses up all ports on Windows (IVY-1105)
- FIX: ivy parse exception when using (IVY-1102)
- FIX: Change org.apache to commons-cli at jdbc-example (IVY-1109)
- FIX: Fixed name snapshots are not updated even if they are marked as changing and the publication date is changed in repo (IVY-938)
- FIX: Cannot publish wildcard configurations other than * (IVY-1171)
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.
For the first tutorial you won't even have to install Ivy (assuming you have Ant and a JDK properly installed), and it shouldn't take more than 30 seconds.
First Tutorial
- Make sure you have ant 1.6.0 or greater and a jdk properly installed
- Copy this build file in an empty directory on your local filesystem (and make sure you name it build.xml)
- Open a console in this directory and run "ant". That's it!
If you have any trouble, check the FAQ. It is most likely related to your internet connection (proxy anyone?).
OK, you've just seen how easy it is to take your first step with Ivy. Go ahead with the other tutorials, but before you do, 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
Guides you through your very first steps with ivy.
- Adjusting default settings
Gives you a better understanding of the default settings and shows you how to customize them to your needs.
- Multiple Resolvers
Teaches you how to configure Ivy to find its dependencies in multiple places.
- Dual Resolver
Helps you configure Ivy to find ivy files in one place and artifacts in another.
- Project dependencies
A starting point for using Ivy in a multi-project environment.
- Using Ivy in multiple projects environment
A more complex example demonstrating the use of Ant+Ivy in a multi-project environment.
- Using Ivy Module Configurations
Shows you how to use configurations in an ivy file to define sets of artifacts.
- Building a repository
Shows you how to build your own enterprise repository.
Quick Start
In this tutorial, you will see one of the simplest ways to use Ivy. With no specific settings, Ivy uses the maven 2 repository to resolve the dependencies you declare in an Ivy file. Let's have a look at the content of the files involved.
You'll find this tutorial's 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="2.0">
<info organisation="org.apache" module="hello-ivy"/>
<dependencies>
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
<dependency org="commons-cli" name="commons-cli" rev="1.0"/>
</dependencies>
</ivy-module>
The format of this file should pretty easy to understand, but let's give some details about what is declared here. First, the root element ivy-module, with the version attribute used to tell Ivy which version of Ivy this file uses.
Then there is an info tag, which is used to give information about the module for which we are defining dependencies. Here we define only the organization and module name. You are free to choose whatever you want for them, but we recommend avoiding spaces for both.
Finally, the dependencies section lets you define dependencies. Here this module depends on two libraries: commons-lang and commons-cli. As you can see, we use the org and name attributes to define the organization and module name of the dependencies we need. The rev attribute is used to specify the version of the module you depend on.
To know what to put in these attributes, you need to know the exact information for the libraries you depend on. Ivy uses the maven 2 repository by default, so we recommend you use mvnrepository.com to look for the module you want. Once you find it, you will have the details on how to declare the dependency in a maven POM. For instance:
<dependency>
<groupId>commons-lang</groupId>
<artifactId>commons-lang</artifactId>
<version>2.0</version>
</dependency>
To convert this into an Ivy dependency declaration, all you have to do is use the groupId as organization, the artifactId as module name, and the version as revision. That's what we did for the dependencies in this tutorial, that is commons-lang and commons-cli. Note that having commons-lang and commons-cli as organization is not the best example of what the organization should be. It would be better to use org.apache, org.apache.commons or org.apache.commons.lang. However, this is how these modules are identified in the maven 2 repository, so the simplest way to get them is to use the details as is (you will see in Building a repository that you can use namespaces to redefine these names if you want something cleaner).
If you want more details on what you can do in Ivy files, you can have a look at the Ivy files reference documentation.
The build.xml file
The corresponding build file contains a set of targets, allowing you to resolve dependencies declared in the Ivy file, to compile and run the sample code, produce a report of dependency resolution, and clean the cache or the project.
You can use the standard "ant -p" to get the list of available targets. Feel free to have a look at the whole file, but here is the part relevant to dependency resolution:
<project xmlns:ivy="antlib:org.apache.ivy.ant" name="hello-ivy" default="run">
...
<!-- =================================
target: resolve
================================= -->
<target name="resolve" description="--> retrieve dependencies with ivy">
<ivy:retrieve />
</target>
</project>
As you can see, it's very easy to call Ivy to resolve and retrieve dependencies: all you need if Ivy is properly installed is to define an XML namespace in your Ant file (xmlns:ivy="antlib:org.apache.ivy.ant"). Then all the Ivy ant tasks will be available in this namespace.
Here we use only one task: the retrieve task. With no attributes, it will use default settings and look for a file named ivy.xml for the dependency definitions. That's exactly what we want, so we need nothing more than that.
Note that in this case we define a resolve target and call the retrieve task. This may sound confusing, actually the retrieve task performs a resolve (which resolves dependencies and downloads them to a cache) followed by a retrieve (a copy of those file to a local project directory). Check the How does it work ? page for details about that.
Running the project
OK, now that we have seen the files involved, let's run the sample to see what happens. Open a shell (or command line) window, and enter the hello-ivy example directory.
Then, at the command prompt, run ant:
[ivy@apache:/ivy/hello-ivy]$ ant
Buildfile: /ivy/hello-ivy/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#hello-ivy;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in public
[ivy:retrieve] found commons-cli#commons-cli;1.0 in public
[ivy:retrieve] found commons-logging#commons-logging;1.0 in public
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0-javadoc.jar ...
[ivy:retrieve] ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:retrieve] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (467kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar(javadoc) (3697ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] ............................................................................................................................................................................................................................................................................................................................................... (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar (1997ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0-sources.jar ...
[ivy:retrieve] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ (245kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar(source) (3495ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-cli/commons-cli/1.0/commons-cli-1.0-javadoc.jar ...
[ivy:retrieve] ........................................................................................................................................................................................... (92kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-cli#commons-cli;1.0!commons-cli.jar(javadoc) (2137ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-cli/commons-cli/1.0/commons-cli-1.0.jar ...
[ivy:retrieve] ......................................................... (29kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-cli#commons-cli;1.0!commons-cli.jar (1404ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-cli/commons-cli/1.0/commons-cli-1.0-sources.jar ...
[ivy:retrieve] ...................................................................................................... (48kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-cli#commons-cli;1.0!commons-cli.jar(source) (1529ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-logging/commons-logging/1.0/commons-logging-1.0.jar ...
[ivy:retrieve] ........................................... (21kB)
[ivy:retrieve] ... (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-logging#commons-logging;1.0!commons-logging.jar (2199ms)
[ivy:retrieve] :: resolution report :: resolve 9095ms :: artifacts dl 16520ms
[ivy:retrieve] :: evicted modules:
[ivy:retrieve] commons-lang#commons-lang;1.0 by [commons-lang#commons-lang;2.0] in [default]
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 4 | 3 | 3 | 1 || 7 | 7 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#hello-ivy
[ivy:retrieve] confs: [default]
[ivy:retrieve] 7 artifacts copied, 0 already retrieved (1069kB/78ms)
run:
[mkdir] Created dir: /ivy/hello-ivy/build
[javac] /ivy/hello-ivy/build.xml:53: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/hello-ivy/build
[java] standard message : hello ivy !
[java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !
BUILD SUCCESSFUL
Total time: 28 seconds
What happened ?
Without any settings, Ivy retrieves files from the maven 2 repository. That's what happened here.
The resolve task has found the commons-lang and commons-cli modules in the maven 2 repository, identified that commons-cli depends on commons-logging and so resolved it as a transitive dependency. Then Ivy has downloaded all corresponding artifacts in its cache (by default in your user home, in a .ivy2/cache directory). Finally, the retrieve task copies the resolved jars from the ivy cache to the default library directory of the project: the lib dir (you can change this easily by setting the pattern attribute on the retrieve task).
You might say that the task took a long time just to write out a "Hello Ivy!" message. But remember that a lot of time was spent downloading the required files from the web. Let's try to run it again:
[ivy@apache:/ivy/hello-ivy]$ ant
Buildfile: /ivy/hello-ivy/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#hello-ivy;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in public
[ivy:retrieve] found commons-cli#commons-cli;1.0 in public
[ivy:retrieve] found commons-logging#commons-logging;1.0 in public
[ivy:retrieve] :: resolution report :: resolve 343ms :: artifacts dl 16ms
[ivy:retrieve] :: evicted modules:
[ivy:retrieve] commons-lang#commons-lang;1.0 by [commons-lang#commons-lang;2.0] in [default]
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 4 | 0 | 0 | 1 || 7 | 0 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#hello-ivy
[ivy:retrieve] confs: [default]
[ivy:retrieve] 0 artifacts copied, 7 already retrieved (0kB/15ms)
run:
[javac] /ivy/hello-ivy/build.xml:53: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[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, so no download was needed and the build was instantaneous.
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.
As you can see, using Ivy to resolve dependencies stored in the maven 2 repository is extremely easy. Now you can go on with the next tutorials to learn more about how to use module configurations which is a very powerful Ivy specific feature. Other tutorials are also available where you will learn how to use Ivy settings to leverage a possibly complex enterprise repository. It may also be a good time to start reading the reference documentation, and especially the introduction material which gives a good overview of Ivy. The best practices page is also a must read to start thinking about how to use Ant+Ivy to build a clean and robust build system.
Adjusting default settings
Ivy comes bundled with some default settings which makes it pretty simple to use in a typical environment. This tutorial, which is close to a reference document, explains what those default settings are and how they can be adjusted to your needs.
To fully understand the concept of settings and what you can do with them, we suggest reading other tutorials related to settings (like Multiple Resolvers and Dual Resolver) or the Settings Files reference documentation.
Concept
The default settings include 3 types of repositories:
- local
a repository which is private to the user.
- shared
a repository which is shared between all the members of a team
- public
a public repository on which most modules, and especially third party modules, can be found
Note that if you work alone, the distinction between a local and shared repository is not very important, but there are some things you should know to distinguish them.
Now let's describe each of these repository concepts in more detail. We will describe how they are set up physically later.
Local
The local repository is particularly useful when you want to do something without being disturbed 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 what is available in others.
For instance, if you have a module declaring a dependency on the module foo with a revision of 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 publishes 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 repository, 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's private modules, and it's also a place where you can put modules not available in the public repository (sun jars, for instance). You can also put modules here that are simply inaccurate in a public repository (bad or incomplete module descriptors for instance).
Note that modules can be split across the shared repository and the public one: For example, you can have the module descriptor in the shared repository and the artifacts in the public one.
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 use the same root in your filesystem. Referenced as ${ivy.default.ivy.user.dir}, this is by default the directory .ivy2 in your user home.
Note that several things can be done by setting Ivy variables. To set them without defining your own ivysettings.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 example:
<target name="resolve">
<property name="ivy.default.ivy.user.dir" value="/path/to/ivy/user/dir"/>
<ivy:resolve />
</target>
Next we will show you how to override default values for the different kinds of repositories. Note that you can find what the default values are below in the details of the default settings.
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. 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 network shared directory. You can use the ivy.shared.default.root
variable to specify a different directory. Moreover, you can also configure the layout with variables similar to the ones used 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 ibiblio in m2 compatible mode (in other words, the maven 2 public repository).
This repository has the advantage of providing a lot of modules, with metadata for most of them. The quality of metadata is not always perfect, but it's a very good start to use a tool like Ivy and benefit from the power of transitive dependency management.
Despite its ease of use, we suggest reading the Best practices to have a good understanding of the pros and cons of using a public unmanaged repository before depending on such a repository for your enterprise build system.
In 1.4 version Ivy was using ivyrep as the default resolver, if you want to restore this, set
ivy.14.compatible=true as an ant property
Going further
OK, so we have seen how to easily change the settings of the three main repositories. But what if my shared repository is on a web server? What if you don't want to use maven 2 repository as the public repository? What if ...
No problem, Ivy is very flexible and can be configured with specific settings to match your needs and environment. But before considering writing your own settings from scratch, we suggest reading the following where you will learn how to leverage a part of the default settings and adjust the rest.
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 ivysettings.xml which is packaged in the Ivy jar. Here is this settings file:
<ivysettings>
<settings defaultResolver="default"/>
<include url="${ivy.default.settings.dir}/ivysettings-public.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-local.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/>
</ivysettings>
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 ivysettings and easily benefit from the rest. For example, if you want to define your own public resolver, you will just have to configure Ivy with an ivysettings like the following:
<ivysettings>
<settings defaultResolver="default"/>
<include url="http://myserver/ivy/myivysettings-public.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-local.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/>
</ivysettings>
Note that only the ivysettings-public.xml inclusion has changed to include a homemade public resolver. Note also that this can be used like that thanks to the fact that ${ivy.default.settings.dir} is a variable which is always set to the place where Ivy's default settings files are (i.e. packaged in the jar).
To finish this example, you have to write your own ivysettings file (that you will make available at http://myserver/ivy/myivysettings-public.xml in this example) for defining your own public resolver. For instance:
<ivysettings>
<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>
</ivysettings>
Now the last thing you will need in order to properly take advantage of the default settings is the content of each included ivysettings file:
ivysettings-public.xml
<ivysettings>
<resolvers>
<ibiblio name="public" m2compatible="true"/>
</resolvers>
</ivysettings>
ivysettings-shared.xml
<ivysettings>
<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>
</ivysettings>
ivysettings-local.xml
<ivysettings>
<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>
</ivysettings>
ivysettings-main-chain.xml
<ivysettings>
<resolvers>
<chain name="main" dual="true">
<resolver ref="shared"/>
<resolver ref="public"/>
</chain>
</resolvers>
</ivysettings>
ivysettings-default-chain.xml
<ivysettings>
<resolvers>
<chain name="default" returnFirst="true">
<resolver ref="local"/>
<resolver ref="main"/>
</chain>
</resolvers>
</ivysettings>
There you go, you should have enough clues to configure Ivy the way you want. Check the settings documentation to see if what you want to do is possible, and go ahead!
Multiple Resolvers
This tutorial is an example of how modules can be retrieved by multiple resolvers. Using multiple resolvers can be useful in many contexts. For example:
- separating integration builds from releases
- using a public repository for third party modules and a private one for internal modules
- use a repository for storing modules which are not accurate in an unmanaged public repository
- use a local repository to expose builds made on one developer's station
In Ivy, the use of multiple resolvers is supported by a compound resolver called the chain resolver.
In our example, we will simply show you how to use two resolvers, one on a local repository and one using the maven2 repository.
project description
the project: chained-resolvers
The project is very simple and contains only one simple class: example.Hello.
It depends on two libraries: Apache's commons-lang and a custom library named test (sources are included in test-1.0jar 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
Let's have a look at the ivy.xml file:
<ivy-module version="1.0">
<info organisation="org.apache" module="chained-resolvers"/>
<dependencies>
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
<dependency name="test" rev="1.0"/>
</dependencies>
</ivy-module>
As we'd expect, the ivy file declares this module to be dependent on the two libraries it uses: 'commons-lang' and 'test'. Note that we didn't specify the org for the dependency 'test'. When we exclude org, Ivy assumes it is in the same org as the declaring module. (i.e. 'org.apache').
the ivy settings
The settings are defined in the ivysettings.xml file located in the settings directory of the project. Below are its contents, followed by an explanation of what it's doing.
<ivysettings>
<settings defaultResolver="chain-example"/>
<resolvers>
<chain name="chain-example">
<filesystem name="libraries">
<artifact pattern="${ivy.settings.dir}/repository/[artifact]-[revision].[ext]" />
</filesystem>
<ibiblio name="ibiblio" m2compatible="true" />
</chain>
</resolvers>
</ivysettings>
the settings tag
This tag initializes Ivy with some parameters. Here only one parameter is set, the name of the resolver to use by default.
the resolvers tag
The resolvers section defines the list of resolvers that Ivy will use to locate artifacts. In our example, we have only one resolver named "chain-example", which is unique in that it defines a list (hence a chain) of resolvers.
The resolvers in this chain are:
- libraries : It is a filesystem resolver, so looks at a directory structure to retrieve the artifacts. This one is configured to look in the repository sub directory of the directory that contains the ivysettings.xml file.
- ibiblio : It looks in the ibiblio maven repository to retrieve the artifacts.
That's it, we have just configured a chain of resolvers!
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 this each time you want to clean up this example.
In almost all examples, we provide a clean target as default target. Since most examples use the same Ivy cache, you will clean the whole Ivy cache each time you call this target.
Cleaning the Ivy cache is something you can do without fear (except performance): it's only a cache, so everything can be (and should be) obtained again from repositories. This may sound strange to those coming from maven 2 land. But remember that in Ivy, the cache is not a local repository and the two are completely isolated.
step 3: run the project
Go to chained-resolvers project directory. And simply run ant.
[ivy@apache:/ivy/chained-resolvers/chainedresolvers-project]$ ant
Buildfile: /ivy/chained-resolvers/chainedresolvers-project/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/chained-resolvers/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#chained-resolvers;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in ibiblio
[ivy:retrieve] found org.apache#test;1.0 in libraries
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] ........................................................................................................................................................................................................................................................................................................................................... (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar (2745ms)
[ivy:retrieve] downloading /ivy/chained-resolvers/settings/repository/test-1.0.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#test;1.0!test.jar (16ms)
[ivy:retrieve] :: resolution report :: resolve 4836ms :: artifacts dl 2761ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 2 | 2 | 1 | 0 || 2 | 2 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#chained-resolvers
[ivy:retrieve] confs: [default]
[ivy:retrieve] 2 artifacts copied, 0 already retrieved (166kB/62ms)
run:
[mkdir] Created dir: /ivy/chained-resolvers/chainedresolvers-project/build
[javac] /ivy/chained-resolvers/chainedresolvers-project/build.xml:58: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/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: 10 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).
Also notice that the 'run' Ant target succeeded in using both commons-lang.jar coming from the ibiblio repository and test.jar coming from the local repository.
Going further
This very simple example helps us see how to set up two resolvers in a chain. The chain resolver's reference documentation is available for those who would like to know all the features offered by this resolver.
Below are a few more interesting things worth knowing about chain resolvers. After reading them, go ahead and try tweaking this example using your new wealth of knowledge!
- a chain is not limited to two nested resolvers, you can use as many as you want
- by setting returnFirst="true", you can have a chain which stops as soon as it has found a result for a given module
- by setting dual="true", the full chain will be used both for module descriptors and artifacts, while setting dual="false", the resolver in the chain which found the module descriptor (if any) is also used for artifacts
Dual Resolver
In some cases, your module descriptions (i.e. Ivy files, maven poms) are located separately from the module artifacts (i.e. jars). So what can you do about it?
Use a Dual resolver! And this tutorial will show you how.
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:
- settings: contains the ivy settings 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 simple 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
Let's have a look at the ivy.xml file:
<ivy-module version="1.0">
<info organisation="org.apache" module="hello-ivy"/>
<dependencies>
<dependency org="commons-httpclient" name="commons-httpclient" rev="2.0.2"/>
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
</dependencies>
</ivy-module>
As you can see, nothing special here... Indeed, Ivy's philosophy is to keep ivy files independent of the way dependencies are resolved.
the ivy settings
The ivy settings are defined in the ivysettings.xml file located in the settings directory. Here is what it contains, followed by an explanation.
<ivysettings>
<settings defaultResolver="dual-example"/>
<resolvers>
<dual name="dual-example">
<filesystem name="ivys">
<ivy pattern="${ivy.settings.dir}/../repository/[module]-ivy-[revision].xml" />
</filesystem>
<ibiblio name="ibiblio" m2compatible="true" usepoms="false" />
</dual>
</resolvers>
</ivysettings>
Here we configured 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" or "metadata" resolver of the dual resolver, and the second one is what is called the "artifact" resolver. It is important that the dual resolver has exactly two sub resolvers in this given order.
The metadata resolver, here a filesystem one, is used only to find module descriptors, in this case Ivy files. The setting shown here tells Ivy that all ivy files are in the repository directory, named with the pattern: [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. This file matches the pattern, so it will be found by the resolver.
The artifact resolver is simply an ibiblio one, configured in m2compatible mode to use the maven 2 repository, with usepoms="false" to make sure it won't use maven 2 metadata. Note that this isn't necessary, since the second resolver in a dual resolver (the artifact resolver) is never asked to find module metadata.
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 the Ivy cache. You can run this each time you want to clean up this example.
step 3 : run the project
Go to the project directory. And simply run ant.
[ivy@apache:/ivy/dual/project]$ ant
Buildfile: /ivy/dual/project/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dual/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#hello-ivy;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-httpclient#commons-httpclient;2.0.2 in ivys
[ivy:retrieve] found commons-logging#commons-logging;1.0.4 in ibiblio
[ivy:retrieve] found commons-lang#commons-lang;2.0 in ibiblio
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-httpclient/commons-httpclient/2.0.2/commons-httpclient-2.0.2.jar ...
[ivy:retrieve] .................................................................................................................................................................................................................................................................................................................................................................................................................................................... (220kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-httpclient#commons-httpclient;2.0.2!commons-httpclient.jar (3853ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] ................................................................................................................................................................................................................................................................................................................................................ (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar (1826ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-logging/commons-logging/1.0.4/commons-logging-1.0.4.jar ...
[ivy:retrieve] .......................................................................... (37kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-logging#commons-logging;1.0.4!commons-logging.jar (1341ms)
[ivy:retrieve] :: resolution report :: resolve 1076ms :: artifacts dl 7036ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 3 | 3 | 1 | 0 || 3 | 3 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#hello-ivy
[ivy:retrieve] confs: [default]
[ivy:retrieve] 3 artifacts copied, 0 already retrieved (423kB/47ms)
run:
[mkdir] Created dir: /ivy/dual/project/build
[javac] /ivy/dual/project/build.xml:58: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/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: 10 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="commons-httpclient"
module="commons-httpclient"
revision="2.0.2"
status="release"
publication="20041010174300"/>
<dependencies>
<dependency org="commons-logging" name="commons-logging" rev="1.0.4" conf="default"/>
</dependencies>
</ivy-module>
So everything seemed to work. The ivy file was found in the repository directory and the artifacts have been downloaded from ibiblio.
This kind of setup can be useful if you don't want to rely on the maven 2 repository for metadata, or if you want to take full advantage of Ivy files for some or all modules. Combining chain and dual resolvers should give you enough flexibility to meet almost any requirement.
For full details about the dual resolver, have a look at the corresponding reference documentation.
Project dependencies
This tutorial will show you how to use Ivy when one of your projects depends on another.
For our example, we will have two projects, depender and dependee, where the depender project uses/requires the dependee project. This example will help illustrate two things about Ivy:
- that dependencies defined by parent projects (dependee) will automatically be retrieved for use by child projects (depender)
- that child projects can retrieve the "latest" version of the dependee project
projects used
dependee
The dependee 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 project ivy file
- src\standalone\Main.java: the only class of the project
Take a look at the ivy.xml file:
<ivy-module version="1.0">
<info organisation="org.apache" module="dependee"/>
<dependencies>
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
</dependencies>
</ivy-module>
The ivy file declares only one dependency, that being the apache commons-lang library.
depender
The depender project is very simple as well. It declares only one dependency on the latest version of the dependee project, and it contains only one class, depending.Main, which does 2 things:
- gets the version of the standalone project by calling standalone.Main.getVersion()
- transforms a string by calling standalone.Main.capitalizeWords(str)
Take a look at the ivy.xml file:
<ivy-module version="1.0">
<info organisation="org.apache" module="depender"/>
<dependencies>
<dependency name="dependee" rev="latest.integration" />
</dependencies>
</ivy-module>
settings
The Ivy settings are defined in two files located in the settings directory:
- ivysettings.properties: a property file
- ivysettings.xml: the file containing the settings
Let's have a look at the ivysettings.xml file:
<ivysettings>
<properties file="${ivy.settings.dir}/ivysettings.properties"/>
<settings defaultCache="${ivy.settings.dir}/ivy-cache" defaultResolver="libraries"/>
<resolvers>
<filesystem name="projects">
<artifact pattern="${repository.dir}/[artifact]-[revision].[ext]" />
<ivy pattern="${repository.dir}/[module]-[revision].xml" />
</filesystem>
<ibiblio name="libraries" m2compatible="true" usepoms="false" />
</resolvers>
<modules>
<module organisation="org.apache" name="dependee" resolver="projects"/>
</modules>
</ivysettings>
The file contains four main tags: properties, settings, resolvers and modules.
properties
This tag loads some properties for the Ivy process, just like Ant does.
settings
This tag initializes some parameters for the Ivy process. In this case, the directory that Ivy will use to cache artifacts will be in a sub directory called ivy-cache of the directory containing the ivysettings.xml file itself.
The second parameter, tells Ivy to use a resolver named "libraries" as its default resolver. More information can be found in the settings reference documentation.
resolvers
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 by locating them on the local filesystem.
The ibiblio resolver called "libraries" is able to find dependencies on the maven 2 repository, but doesn't use maven poms.
modules
The modules tag allows you to configure which resolver should be used for which module. Here the setting tells Ivy to use the "projects" resolver for all modules having an organisation of org.apache and module name of dependee. This actually corresponds to only one module, but a regular expression could be used, or many other types of expressions (like glob expressions).
All other modules (i.e. all modules but org.apache#dependee), will use the default resolver ("libraries").
walkthrough
step 1: preparation
Open a DOS or shell window, and go to the src/example/dependence directory.
step 2: clean directory tree
On the prompt type: ant
This will clean up the entire project directory tree. You can do this each time you want to clean up this example.
step 3: publication of dependee project
Go to dependee directory and publish the project
[ivy@apache:/ivy/dependence/dependee]$ ant publish
Buildfile: /ivy/dependence/dependee/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dependence/settings/ivysettings.xml
[ivy:retrieve] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/dependence/settings/ivysettings.xml)
[ivy:retrieve] :: resolving dependencies :: org.apache#dependee;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in libraries
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] ...................................................................................................................................................................................................................................................................................................................................
[ivy:retrieve] (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar (3260ms)
[ivy:retrieve] :: resolution report :: resolve 530ms :: artifacts dl 3260ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 1 | 1 | 0 | 0 || 1 | 1 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#dependee
[ivy:retrieve] confs: [default]
[ivy:retrieve] 1 artifacts copied, 0 already retrieved (165kB/31ms)
compile:
[mkdir] Created dir: /ivy/dependence/dependee/build/classes
[javac] /ivy/dependence/dependee/build.xml:60: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/dependence/dependee/build/classes
jar:
[propertyfile] Creating new property file: /ivy/dependence/dependee/build/classes/version.properties
[jar] Building jar: /ivy/dependence/dependee/build/dependee.jar
publish:
[ivy:publish] :: delivering :: org.apache#dependee;working@apache :: 1 :: release :: Thu Sep 23 23:15:49 CEST 2010
[ivy:publish] delivering ivy file to /ivy/dependence/dependee/build/ivy.xml
[ivy:publish] :: publishing :: org.apache#dependee
[ivy:publish] published dependee to /ivy/dependence/settings/repository/dependee-1.jar
[ivy:publish] published ivy to /ivy/dependence/settings/repository/dependee-1.xml
[echo] project dependee released with version 1
BUILD SUCCESSFUL
Total time: 6 seconds
What we see here:
- the project depends on 1 library (1 artifact)
- the library was not in the Ivy cache and so was downloaded (1 downloaded)
- the project has been released under version number 1
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 its 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 makes a call to the deliver task which delivers a resolved ivy file to this destination.
- the publication of artifact 'dependee' and its resolved ivy file to the repository.
Both are just copies of the files found in the current project, or more precisely, those in the build directory. This is because the artifactspattern has been set to ${build.dir}/[artifact].[ext], so the dependee artifact is found at build/dependee.jar and the 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\dependee-1.jar and to repository\dependee-1.xml, respecting the artifact and ivy patterns of our settings (see above).
step 4: running the depender project
Go to directory depender and run ant
[ivy@apache:/ivy/dependence/depender]$ ant
Buildfile: /ivy/dependence/depender/build.xml
clean:
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dependence/settings/ivysettings.xml
[ivy:retrieve] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/dependence/settings/ivysettings.xml)
[ivy:retrieve] :: resolving dependencies :: org.apache#depender;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found org.apache#dependee;1 in projects
[ivy:retrieve] [1] org.apache#dependee;latest.integration
[ivy:retrieve] found commons-lang#commons-lang;2.0 in libraries
[ivy:retrieve] downloading /ivy/dependence/settings/repository/dependee-1.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#dependee;1!dependee.jar (16ms)
[ivy:retrieve] :: resolution report :: resolve 343ms :: artifacts dl 47ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 2 | 1 | 1 | 0 || 2 | 1 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#depender
[ivy:retrieve] confs: [default]
[ivy:retrieve] 2 artifacts copied, 0 already retrieved (167kB/47ms)
compile:
[mkdir] Created dir: /ivy/dependence/depender/build/classes
[javac] /ivy/dependence/depender/build.xml:71: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/dependence/depender/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 retrieved version 1 of the project "dependee". The call to standalone.Main.getVersion() has returned 1. If you look in the depender/lib directory, you should see dependee-1.jar which is the version 1 artifact of the project "dependee"
- the call to standalone.Main.capitalizeWords(str) succeed, which means that the required library was in the classpath. If you look at the lib directory, you will see that the library commons-lang-2.0.jar was also retrieved. This library was declared as a dependency of the "dependee" project, so Ivy retrieves it (transitively) along with the dependee artifact.
step 5: new version of dependee project
Like we did before in step 3, publish the dependee project again. This will result in a new version of the project being published.
[ivy@apache:/ivy/dependence/dependee]$ ant publish
Buildfile: /ivy/dependence/dependee/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dependence/settings/ivysettings.xml
[ivy:retrieve] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/dependence/settings/ivysettings.xml)
[ivy:retrieve] :: resolving dependencies :: org.apache#dependee;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in libraries
[ivy:retrieve] :: resolution report :: resolve 109ms :: artifacts dl 0ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 1 | 0 | 0 | 0 || 1 | 0 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#dependee
[ivy:retrieve] confs: [default]
[ivy:retrieve] 0 artifacts copied, 1 already retrieved (0kB/0ms)
compile:
[javac] /ivy/dependence/dependee/build.xml:60: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
jar:
[propertyfile] Updating property file: /ivy/dependence/dependee/build/classes/version.properties
[jar] Building jar: /ivy/dependence/dependee/build/dependee.jar
publish:
[delete] Deleting: /ivy/dependence/dependee/build/ivy.xml
[ivy:publish] :: delivering :: org.apache#dependee;working@apache :: 2 :: release :: Thu Sep 23 23:15:56 CEST 2010
[ivy:publish] delivering ivy file to /ivy/dependence/dependee/build/ivy.xml
[ivy:publish] :: publishing :: org.apache#dependee
[ivy:publish] published dependee to /ivy/dependence/settings/repository/dependee-2.jar
[ivy:publish] published ivy to /ivy/dependence/settings/repository/dependee-2.xml
[echo] project dependee released with version 2
BUILD SUCCESSFUL
Total time: 1 second
Now if you look in your repository folder, you will find 2 versions of the dependee project.
Let's look at it:
I:\dependee>dir ..\settings\repository /w
[.] [..] dependee-1.jar dependee-1.xml dependee-2.jar dependee-2.xml
I:\dependee>
OK, now our repository contains two versions of the project dependee, so other projects can refer to either version.
step 6: get the new version in depender project
What should we expect if we run the depender project again? It should:
- retrieve version 2 as the latest.integration version of the dependee project
- display version 2 of dependee project
Let's try it!!
[ivy@apache:/ivy/dependence/depender]$ ant
Buildfile: /ivy/dependence/depender/build.xml
clean:
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dependence/settings/ivysettings.xml
[ivy:retrieve] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/dependence/settings/ivysettings.xml)
[ivy:retrieve] :: resolving dependencies :: org.apache#depender;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found org.apache#dependee;1 in projects
[ivy:retrieve] [1] org.apache#dependee;latest.integration
[ivy:retrieve] found commons-lang#commons-lang;2.0 in libraries
[ivy:retrieve] :: resolution report :: resolve 94ms :: artifacts dl 15ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 2 | 0 | 0 | 0 || 2 | 0 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#depender
[ivy:retrieve] confs: [default]
[ivy:retrieve] 2 artifacts copied, 0 already retrieved (167kB/31ms)
compile:
[mkdir] Created dir: /ivy/dependence/depender/build/classes
[javac] /ivy/dependence/depender/build.xml:71: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/dependence/depender/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: 2 seconds
OK, we got what we expected as the run target shows that we are using version 2 of the main class of the dependee project. If we take a look at the resolve target results, we see that one artifact has been downloaded to the ivy cache. In fact, this file is the same version 2 of the dependee project that is in the repository, but now all future retrievals will pull it from your ivy-cache directory.
Using Ivy in multiple projects environment
In the previous tutorial, you saw 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 of the code for this tutorial is available in the src/example/multi-project directory of the Ivy distribution.
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 Ant+Ivy can be used to develop an application divided in multiple modules.
Now, here is how these modules relate to each other:
click to enlarge
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 is 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 each containing:
- 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="org.apache.ivy.example"
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="commons-collections" name="commons-collections" rev="3.1" conf="core->default" />
<dependency org="commons-cli" name="commons-cli" rev="1.0" conf="standalone->default" />
</dependencies>
</ivy-module>
build.xml The build file of the project, which consists mainly of 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 example doesn't demonstrate many good practices for software development in general, in particular you won't find any unit test in these 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 the module's build files only import the common build file, and define their dependencies in their ivy files (which you should begin to be familiar with).
So, here are some aspects of this common build file:
ivy settings
<!-- 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 ivysettings file
<ivy:settings file="${common.dir}/ivysettings.xml" id="ivy.instance" />
-->
This declaration configures Ivy by only setting two properties: the location for the local repository and the location for the shared repository. It's the only settings done here, since Ivy is configured by default to work in a team environment (see default settings 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 settings tutorial to see how to use something really different).
Commented out you can see how the settings would have been done if the default setting wasn't OK for our purpose.
resolve dependencies
<target name="resolve" depends="clean-lib, load-ivy" description="--> resolve and retrieve dependencies with ivy">
<mkdir dir="${lib.dir}"/> <!-- not usually necessary, ivy creates the directory IF there are dependencies -->
<!-- the call to resolve is not mandatory, retrieve makes an implicit call if we don't -->
<ivy:resolve file="${ivy.file}"/>
<ivy:retrieve pattern="${lib.dir}/[artifact].[ext]" />
</target>
You should begin to be familiar with using Ivy this way. We call resolve explicitly to use the ivy file configured (the default would have been fine), and then call retrieve to copy resolved dependencies artifacts from the cache to a local lib directory. The pattern is also used to name the artifacts in the lib dir with their name and extension only (without revision), this is easier to use with an IDE, as the IDE configuration won't change when the artifacts version change.
ivy-new-version
<target name="ivy-new-version" depends="load-ivy" unless="ivy.new.revision">
<!-- default module version prefix value -->
<property name="module.version.prefix" value="${module.version.target}-dev-b" />
<!-- asks Ivy for an available version number -->
<ivy:info file="${ivy.file}" />
<ivy:buildnumber
organisation="${ivy.organisation}" module="${ivy.module}"
revision="${module.version.prefix}" defaultBuildNumber="1" revSep=""/>
</target>
This target is used to ask Ivy to find a new version for a module. To get details about the module we are dealing with, we pull information out of the ivy file by using the ivy:info task. Then the buildnumber task is used to get a new revision, based on a prefix we set with a property, by default it will be 1.0-dev-b (have a look at the default value for module.version.target in the common/build.properties file). Each module built by this common build file could easily override this by either setting a different module.version.target in its module specific build.properties, or even overriding module.version.prefix. To get the new revision, Ivy scans the repository to find the latest available version with the given prefix, and then increments this version by 1.
publish
<target name="publish" depends="clean-build, jar" description="--> publish this project in the ivy repository">
<ivy:publish artifactspattern="${build.dir}/[artifact].[ext]"
resolver="shared"
pubrevision="${version}"
status="release"
/>
<echo message="project ${ant.project.name} released with version ${version}" />
</target>
This target publishes the module to the shared repository, with the revision found in the version property, which is set by other targets (based on ivy-new-version we have seen above). It can be used when a module reaches a specific milestone, or whenever you want the team 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">
<ivy:publish artifactspattern="${build.dir}/[artifact].[ext]"
resolver="local"
pubrevision="${version}"
pubdate="${now}"
status="integration"
forcedeliver="true"
/>
<echo message="project ${ant.project.name} published locally with version ${version}" />
</target>
This is very similar to the publish task, except that this publishes the revision to 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" 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, or discard your local changes and want to take advantage of a new version from the 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!
Playing with the projects
You can play with this tutorial by using regular Ant commands. Begin in the base directory of the tutorial (src/example/multi-project), and run ant -p:
[ivy@apache:/ivy/multi-project]$ ant -p
Buildfile: /ivy/multi-project/build.xml
Main targets:
clean clean tutorial: delete repository, ivy cache, and all projects
clean-all clean all projects
publish-all compile, jar and publish all projects in the right order
This gives you an idea of what you can do here. To make sure you have at least one version of all your modules published in your repository (required to build modules having dependencies on the others), you can run ant publish-all (example log here).
You will see that Ivy calls the publish target on all the modules, following the order of the dependencies, so that a dependee is always built and published before its depender. Feel free to make changes in the source code of a module (changing a method name for instance) and in the module using the method, then call publish-all to see how the change in the dependee is compiled first, published, and then available to the depender which can compile successfully.
Then you can go in one of the example project directories (like projects/find for instance), and run ant -p:
[ivy@apache:/ivy/multi-project/projects/find]$ ant -p
Buildfile: /ivy/multi-project/projects/find/build.xml
Main targets:
clean --> clean the project
clean-build --> clean the project built files
clean-lib --> clean the project libraries directory (dependencies)
clean-local --> cleans the local repository for the current module
compile --> compile the project
jar --> make a jar file for this project
publish --> publish this project in the ivy repository
publish-local --> publish this project in the local ivy repository
report --> generates a report of dependencies
resolve --> resolve and retrieve dependencies with ivy
run --> compile and run the project
Default target: compile
You can see the targets available, thanks to the import of the common.xml build file. Play with the project by calling resolve, and publish, and see what happens when you do the same in other projects. An interesting thing to do for instance, is to change the dependencies of a project. If the module version now depends on a new commons library, you will see that all other projects depending on that version will get this library as part of their transitive dependencies once the new revision of the version project is published. Very easy! And if a project introduces a change with which the depender isn't compatible with yet, you can easily change the dependency in the depender to move from latest.integration to a fixed version with which the depender is compatible (probably the latest before the change). Keeping your modules under control is now very easy!
By now, you should be pretty familiar with multi-project development with Ivy. We hope you will appreciate its power and flexibility! And these tutorials are only the beginning of your journey with Ivy, browse the reference documentation to learn more about the features, subscribe to the mailing lists to share your experience and ask questions with the community, browse the source code, open jira issues, submit patches, join in and help make Ivy the best of dependency management tools!
Using Ivy Module Configurations
This tutorial introduces the use of module configurations in ivy files. Ivy module configurations are 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 poured :-)
More seriously, configurations in Ivy can be better understood as views on your module, and you will see how they can be used effectively here.
Reference documentation on configurations can be found here and here.
Introduction
Source code is available in src/example/configurations/multi-projects.
We have two projects :
- filter-framework is a library that defines an api to filter String arrays and two implementations of this api.
- myapp is a very small app that uses filter-framework.
The filter-framework library project produces 3 artifacts:
- the api jar,
- an implementation jar with no external dependencies,
- a second implementation jar that needs commons-collections to perform.
The application only needs the api jar to compile and can use either of the two implementations at runtime.
The library project
The first project we'll look at in this tutorial is filter-framework. In order to have a fine-grained artifacts publication definition, we defined several configurations, each which maps to a set of artifacts that other projects can make use of.
The ivy.xml file
<ivy-module version="1.0">
<info organisation="org.apache" 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="commons-collections" 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 4 configurations, with 3 being public and 1 private. (the junit dependency for testing).
The 2 implementation configurations, homemade-impl and cc-impl extend the api configuration so that all artifacts defined in api will also be part of the extending configuration.
In the publications tag, we defined the artifacts we produce (jars in this case) and we assign them to a configuration. When others use our library they will have a flexible way to ask for what they need.
See it in action
The filter-framework project is built using Ant. Open a shell in the root directory of the project and type ant.
[ivy@apache:/ivy/configurations/multi-projects/filter-framework]$ ant
Buildfile: /ivy/configurations/multi-projects/filter-framework/build.xml
clean:
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#filter-framework;working@apache
[ivy:retrieve] confs: [api, homemade-impl, cc-impl, test]
[ivy:retrieve] found commons-collections#commons-collections;3.1 in public
[ivy:retrieve] found junit#junit;3.8 in public
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-collections/commons-collections/3.1/commons-collections-3.1.jar ...
[ivy:retrieve] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:retrieve] ...................................................................................................................................................................................................................................................................................................................................................................................... (546kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-collections#commons-collections;3.1!commons-collections.jar (3432ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/junit/junit/3.8/junit-3.8.jar ...
[ivy:retrieve] .......................................................................................................................................................................................................................................... (118kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] junit#junit;3.8!junit.jar (2013ms)
[ivy:retrieve] :: resolution report :: resolve 7286ms :: artifacts dl 5460ms
---------------------------------------------------------------------
| | 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 | 2 | 0 || 2 | 2 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#filter-framework
[ivy:retrieve] confs: [api, homemade-impl, cc-impl, test]
[ivy:retrieve] 3 artifacts copied, 0 already retrieved (1211kB/63ms)
build:
[mkdir] Created dir: /ivy/configurations/multi-projects/filter-framework/build
[mkdir] Created dir: /ivy/configurations/multi-projects/filter-framework/distrib
[javac] /ivy/configurations/multi-projects/filter-framework/build.xml:57: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 4 source files to /ivy/configurations/multi-projects/filter-framework/build
[javac] Note: Some input files use unchecked or unsafe operations.
[javac] Note: Recompile with -Xlint:unchecked for details.
[jar] Building jar: /ivy/configurations/multi-projects/filter-framework/distrib/filter-api.jar
[jar] Building jar: /ivy/configurations/multi-projects/filter-framework/distrib/filter-hmimpl.jar
[jar] Building jar: /ivy/configurations/multi-projects/filter-framework/distrib/filter-ccimpl.jar
test:
[mkdir] Created dir: /ivy/configurations/multi-projects/filter-framework/build/test-report
[mkdir] Created dir: /ivy/configurations/multi-projects/filter-framework/build/test-classes
[javac] /ivy/configurations/multi-projects/filter-framework/build.xml:82: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 3 source files to /ivy/configurations/multi-projects/filter-framework/build/test-classes
[junit] Running filter.ccimpl.CCFilterTest
[junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0,109 sec
[junit] Running filter.hmimpl.HMFilterTest
[junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0,093 sec
publish:
[ivy:publish] :: delivering :: org.apache#filter-framework;working@apache :: 1.3 :: release :: Thu Sep 23 23:16:19 CEST 2010
[ivy:publish] delivering ivy file to /ivy/configurations/multi-projects/filter-framework/distrib/ivy.xml
[ivy:publish] :: publishing :: org.apache#filter-framework
[ivy:publish] published filter-api to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part/jars/filter-api.jar
[ivy:publish] published filter-hmimpl to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part/jars/filter-hmimpl.jar
[ivy:publish] published filter-ccimpl to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part/jars/filter-ccimpl.jar
[ivy:publish] published ivy to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part/ivys/ivy.xml
[ivy:publish] publish commited: moved /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part
[ivy:publish] to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3
[echo] project filter-framework released with version 1.3
BUILD SUCCESSFUL
Total time: 18 seconds
The Ant default target is publish. This target uses Ivy to publish our library binaries to a local repository. Since we do not specify any repository path, the default one is used. (${home.dir}/.ivy2/local/org.apache/filter-framework/) At this point, we are ready to use our library.
The application project
Now that we have shipped (published) our fantastic filter library, we want to use it! The tutorial comes with a sample application called myapp.
The ivy.xml file
<ivy-module version="1.0">
<info organisation="org.apache" 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="org.apache" 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 different ways we want to use the application. The build configuration defines the compile-time dependencies, and thus only needs the api conf from the filter-framework project. The other two configurations define runtime dependencies. One will only use our "home-made" jar, and the other will use an external jar.
We also defined a dependency on our previously built library. In this dependency, we use configuration mappings to match ours with the dependency's configurations. You can find more information about configuration mapping here
- build->api : here we tell Ivy that our build configuration depends on the api configuration of the dependency
- noexternaljar->homemade-impl : here we tell Ivy that our noexternaljar configuration depends on the homemade-impl configuration of the dependency.
- withexternaljar->cc-impl : here we tell Ivy that our withexternaljar configuration depends on the cc-impl configuration of the dependency
Note that we never declare any of the dependency's artifacts we need in each configuration: it's the dependency module's ivy file which declares the published artifacts and which should be used in each configuration.
In the Ant build.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 then retrieve all the artifacts. The artifacts retrieved are kept in separate folders according to the configurations they belong to. Here is how your lib directory should look after a call to this target:
Repertoire 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
Repertoire 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
Repertoire 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
Repertoire 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. The default Ant target is run-cc and will launch the application using the Apache commons-collections implementation.
[ivy@apache:/ivy/configurations/multi-projects/myapp]$ ant
Buildfile: /ivy/configurations/multi-projects/myapp/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#myapp;working@apache
[ivy:retrieve] confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] found org.apache#filter-framework;1.3 in local
[ivy:retrieve] [1.3] org.apache#filter-framework;latest.integration
[ivy:retrieve] found commons-collections#commons-collections;3.1 in public
[ivy:retrieve] downloading /home/ivy/.ivy2/local/org.apache/filter-framework/1.3/jars/filter-ccimpl.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#filter-framework;1.3!filter-ccimpl.jar (16ms)
[ivy:retrieve] downloading /home/ivy/.ivy2/local/org.apache/filter-framework/1.3/jars/filter-hmimpl.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#filter-framework;1.3!filter-hmimpl.jar (15ms)
[ivy:retrieve] downloading /home/ivy/.ivy2/local/org.apache/filter-framework/1.3/jars/filter-api.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#filter-framework;1.3!filter-api.jar (31ms)
[ivy:retrieve] :: resolution report :: resolve 156ms :: artifacts dl 62ms
---------------------------------------------------------------------
| | 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 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#myapp
[ivy:retrieve] confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] 6 artifacts copied, 0 already retrieved (552kB/94ms)
build:
[mkdir] Created dir: /ivy/configurations/multi-projects/myapp/build
[javac] /ivy/configurations/multi-projects/myapp/build.xml:56: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/configurations/multi-projects/myapp/build
run-cc:
[java] Filtering with:class filter.ccimpl.CCFilter
[java] Result :[two, tree]
BUILD SUCCESSFUL
Total time: 3 seconds
Launching the application using the homemade implementation is also straightforward.
type ant run-hm
[ivy@apache:/ivy/configurations/multi-projects/myapp]$ ant run-hm
Buildfile: /ivy/configurations/multi-projects/myapp/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#myapp;working@apache
[ivy:retrieve] confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] found org.apache#filter-framework;1.3 in local
[ivy:retrieve] [1.3] org.apache#filter-framework;latest.integration
[ivy:retrieve] found commons-collections#commons-collections;3.1 in public
[ivy:retrieve] :: resolution report :: resolve 156ms :: artifacts dl 0ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| build | 1 | 0 | 0 | 0 || 1 | 0 |
| noexternaljar | 1 | 0 | 0 | 0 || 2 | 0 |
| withexternaljar | 2 | 0 | 0 | 0 || 3 | 0 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#myapp
[ivy:retrieve] confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] 0 artifacts copied, 6 already retrieved (0kB/31ms)
build:
[javac] /ivy/configurations/multi-projects/myapp/build.xml:56: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
run-hm:
[java] Filtering with:class filter.hmimpl.HMFilter
[java] Result :[two, tree]
BUILD SUCCESSFUL
Total time: 2 seconds
Nice! We got the same result, but we can see that the implementation classes are different.
Conclusion
You should use configurations as often as possible. Configurations are a very important concept in Ivy. They allow you to group artifacts and give the group a meaning. When you write ivy files for projects that are intended for use by others, use configurations to allow people to get only what they need, without having to specify them one by one in their own dependency list.
Building a repository
The install Ant task lets you copy a module or a set of modules from one repository to another. This is very useful to build and maintain an enterprise or team repository. If you don't want to give access to the public maven 2 repository to the developers on your team (to keep control over which modules are in use in your company or your team for instance), it can sometimes become tiresome to answer the developers request to add new modules or new versions by hand.
Fortunately the install task is here to help: you can use specific settings for your repository maintenance build which will be used to maintain your target enterprise repository. These settings will point to another repository (for instance the maven 2 public repository) so that you will just have to ask Ivy to install the modules you want with a simple command line.
To demonstrate this, we will first use a basic ivy settings file to show how it works, and then we will use the advanced namespaces features to demonstrate how to deal with naming mismatches between the source and target repository.
The project used
The project that we will use is pretty simple. It is composed of an Ant build file, and two ivy settings files.
Here are the public targets that we will use:
Z:\ivy-repository>ant -p
Buildfile: build.xml
Main targets:
clean-cache --> clean the cache
clean-repo --> clean the destination repository
maven2 --> install module from maven 2 repository
maven2-deps --> install module from maven 2 repository with dependencies
maven2-namespace --> install module from maven 2 using namespaces
maven2-namespace-deps --> install module with dependencies from maven2 repo using namespaces
Default target: basic
This project is accessible in the src/example/build-a-ivy-repository
Next steps:
Basic repository copy
Using namespaces
Basic repository copy
In this first step, we use the install Ant task to install modules from the maven 2 repository to a file system based repository. We first install a module by itself, excluding dependencies, then again with its dependencies.
Basic: ivysettings.xml file used
The ivy settings file that we will use is very simple here. It defines two resolvers, libraries and my-repository. The first one is used as the source, the second one as the destination. In a typical setup, the second one would be configured using an include that included an existing settings file used by the development team.
<ivysettings>
<settings defaultCache="${ivy.cache.dir}/no-namespace"
defaultResolver="libraries"
defaultConflictManager="all" /> <!-- in order to get all revisions without any eviction -->
<resolvers>
<ibiblio name="libraries" m2compatible="true" />
<filesystem name="my-repository">
<ivy pattern="${dest.repo.dir}/no-namespace/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${dest.repo.dir}/no-namespace/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
</filesystem>
</resolvers>
</ivysettings>
install a simple module with no dependencies
Let's have a look at the maven2 target.
<target name="maven2" depends="init-ivy"
description="--> install module from maven 2 repository">
<ivy:install settingsRef="basic.settings"
organisation="commons-lang" module="commons-lang" revision="1.0"
from="${from.resolver}" to="${to.resolver}" />
</target>
Pretty simple, we call the [[ant:install] task with the settings we have loaded using ivy:settings as usual. We then set the source and destination repositories using the from and to attributes. We used Ant properties for these values here, which helps ease the maintenance of the script, but it's basically the name of our resolvers: 'libraries' for the source and 'my-repository' for the destination.
Here is the Ant call output :
[ivy@apache:/ivy/build-a-ivy-repository]$ ant maven2
Buildfile: /ivy/build-a-ivy-repository/build.xml
load-ivy:
init-ivy:
maven2:
[ivy:install] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:install] :: loading settings :: file = /ivy/build-a-ivy-repository/settings/ivysettings-basic.xml
[ivy:install] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/build-a-ivy-repository/settings/ivysettings-basic.xml)
[ivy:install] :: installing commons-lang#commons-lang;1.0 ::
[ivy:install] :: resolving dependencies ::
[ivy:install] found commons-lang#commons-lang;1.0 in libraries
[ivy:install] :: downloading artifacts to cache ::
[ivy:install] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0-javadoc.jar ...
[ivy:install] .............................................................................................................................................................................................................................................................................................................................................................. (170kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] commons-lang#commons-lang;1.0!commons-lang.jar(javadoc) (4134ms)
[ivy:install] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0.jar ...
[ivy:install] .......................................................................................................................... (62kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] commons-lang#commons-lang;1.0!commons-lang.jar (1576ms)
[ivy:install] :: installing in my-repository ::
[ivy:install] published commons-lang to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/javadocs/commons-lang-1.0.jar
[ivy:install] published commons-lang to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/jars/commons-lang-1.0.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/ivys/ivy-1.0.xml
[ivy:install] :: install resolution report ::
[ivy:install] :: resolution report :: resolve 0ms :: artifacts dl 5725ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 1 | 1 | 1 | 0 || 2 | 2 |
---------------------------------------------------------------------
BUILD SUCCESSFUL
Total time: 10 seconds
The trace tells us that the module definition was found using the "libraries" resolver and that the corresponding artifact was downloaded from the maven 2 repository. Then both were published to the filesystem repository (my-repository).
Let's have a look at our repository :
[ivy@apache:/]$ find /ivy/build-a-ivy-repository/myrepository/no-namespace -type f -print
/ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/ivys/ivy-1.0.xml
/ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/ivys/ivy-1.0.xml.md5
/ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/ivys/ivy-1.0.xml.sha1
/ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/jars/commons-lang-1.0.jar
/ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/jars/commons-lang-1.0.jar.md5
/ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/jars/commons-lang-1.0.jar.sha1
/ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/javadocs/commons-lang-1.0.jar
/ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/javadocs/commons-lang-1.0.jar.md5
/ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/javadocs/commons-lang-1.0.jar.sha1
We can see that we now have the commons-lang module version 1.0 in our repository, with a generated ivy.xml file, its jar, and all the md5 and sha1 checksums for future consistency checks when developers use this repository to resolve modules.
install a module with dependencies
Now let's say that we want to be sure all the dependencies of the module we install are available in our repository after the installation. We could either install without dependencies on a staging repository and check the missing dependencies (more control), or use transitive dependency management and ask Ivy to install everything for us (much simpler).
The maven2-deps target is very similar to the one described above, except that we explicitly ask for transitive installation.
<target name="maven2-deps" depends="init-ivy"
description="--> install module from maven 2 repository with dependencies">
<ivy:install settingsRef="basic.settings"
organisation="org.hibernate" module="hibernate" revision="3.2.5.ga"
from="${from.resolver}" to="${to.resolver}" transitive="true" />
</target>
If you call this target, you will see that Ivy installs not only the hibernate module but also its dependencies:
[ivy@apache:/ivy/build-a-ivy-repository]$ ant maven2-deps
Buildfile: /ivy/build-a-ivy-repository/build.xml
load-ivy:
init-ivy:
maven2-deps:
[ivy:install] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:install] :: loading settings :: file = /ivy/build-a-ivy-repository/settings/ivysettings-basic.xml
[ivy:install] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/build-a-ivy-repository/settings/ivysettings-basic.xml)
[ivy:install] :: installing org.hibernate#hibernate;3.2.5.ga ::
[ivy:install] :: resolving dependencies ::
[ivy:install] found org.hibernate#hibernate;3.2.5.ga in libraries
[ivy:install] found net.sf.ehcache#ehcache;1.2.3 in libraries
[ivy:install] found commons-logging#commons-logging;1.0.4 in libraries
[ivy:install] found commons-collections#commons-collections;2.1 in libraries
[ivy:install] found javax.transaction#jta;1.0.1B in libraries
[ivy:install] found asm#asm-attrs;1.5.3 in libraries
[ivy:install] found dom4j#dom4j;1.6.1 in libraries
[ivy:install] found antlr#antlr;2.7.6 in libraries
[ivy:install] found cglib#cglib;2.1_3 in libraries
[ivy:install] found asm#asm;1.5.3 in libraries
[ivy:install] found commons-collections#commons-collections;2.1.1 in libraries
[ivy:install] found ant#ant;1.6.5 in libraries
[ivy:install] found swarmcache#swarmcache;1.0RC2 in libraries
[ivy:install] found commons-logging#commons-logging;1.0.2 in libraries
[ivy:install] found jgroups#jgroups-all;2.2.8 in libraries
[ivy:install] found jboss#jboss-cache;1.2.2 in libraries
[ivy:install] found jboss#jboss-system;4.0.2 in libraries
[ivy:install] found jboss#jboss-common;4.0.2 in libraries
[ivy:install] found slide#webdavlib;2.0 in libraries
[ivy:install] found xerces#xercesImpl;2.6.2 in libraries
[ivy:install] found jboss#jboss-minimal;4.0.2 in libraries
[ivy:install] found jboss#jboss-j2se;200504122039 in libraries
[ivy:install] found concurrent#concurrent;1.3.4 in libraries
[ivy:install] found jgroups#jgroups-all;2.2.7 in libraries
[ivy:install] found c3p0#c3p0;0.9.1 in libraries
[ivy:install] found javax.security#jacc;1.0 in libraries
[ivy:install] found opensymphony#oscache;2.1 in libraries
[ivy:install] found proxool#proxool;0.8.3 in libraries
[ivy:install] :: downloading artifacts to cache ::
[ivy:install] downloading http://repo1.maven.org/maven2/org/hibernate/hibernate/3.2.5.ga/hibernate-3.2.5.ga-sources.jar ...
[ivy:install] .........................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ...........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .................................................................................................................................................................................................................................................................................................................................. (1470kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] org.hibernate#hibernate;3.2.5.ga!hibernate.jar(source) (6427ms)
[ivy:install] downloading http://repo1.maven.org/maven2/org/hibernate/hibernate/3.2.5.ga/hibernate-3.2.5.ga-javadoc.jar ...
[ivy:install] .............................................................................................................................................................................................................................................................
[ivy:install] ...............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ....................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ...........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (7352kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] org.hibernate#hibernate;3.2.5.ga!hibernate.jar(javadoc) (22511ms)
[ivy:install] downloading http://repo1.maven.org/maven2/org/hibernate/hibernate/3.2.5.ga/hibernate-3.2.5.ga.jar ...
[ivy:install] ...........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (2202kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] org.hibernate#hibernate;3.2.5.ga!hibernate.jar (7300ms)
[ivy:install] downloading http://repo1.maven.org/maven2/net/sf/ehcache/ehcache/1.2.3/ehcache-1.2.3.jar ...
[ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................ (203kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] net.sf.ehcache#ehcache;1.2.3!ehcache.jar (2746ms)
[ivy:install] downloading http://repo1.maven.org/maven2/commons-logging/commons-logging/1.0.4/commons-logging-1.0.4.jar ...
[ivy:install] .......................................................................... (37kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] commons-logging#commons-logging;1.0.4!commons-logging.jar (1825ms)
[ivy:install] downloading http://repo1.maven.org/maven2/asm/asm-attrs/1.5.3/asm-attrs-1.5.3.jar ...
[ivy:install] .............................. (16kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] asm#asm-attrs;1.5.3!asm-attrs.jar (1857ms)
[ivy:install] downloading http://repo1.maven.org/maven2/dom4j/dom4j/1.6.1/dom4j-1.6.1.jar ...
[ivy:install] ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .................................................................................................................................................. (306kB)
[ivy:install] ... (0kB)
[ivy:install] [SUCCESSFUL ] dom4j#dom4j;1.6.1!dom4j.jar (3463ms)
[ivy:install] downloading http://repo1.maven.org/maven2/antlr/antlr/2.7.6/antlr-2.7.6.jar ...
[ivy:install] .......................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (433kB)
[ivy:install] ... (0kB)
[ivy:install] [SUCCESSFUL ] antlr#antlr;2.7.6!antlr.jar (4711ms)
[ivy:install] downloading http://repo1.maven.org/maven2/cglib/cglib/2.1_3/cglib-2.1_3.jar ...
[ivy:install] .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (275kB)
[ivy:install] ... (0kB)
[ivy:install] [SUCCESSFUL ] cglib#cglib;2.1_3!cglib.jar (2449ms)
[ivy:install] downloading http://repo1.maven.org/maven2/asm/asm/1.5.3/asm-1.5.3.jar ...
[ivy:install] ..................................................... (25kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] asm#asm;1.5.3!asm.jar (9157ms)
[ivy:install] downloading http://repo1.maven.org/maven2/commons-collections/commons-collections/2.1.1/commons-collections-2.1.1.jar ...
[ivy:install] .......................................................................................................................................................................................................................................................................................................................... (171kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] commons-collections#commons-collections;2.1.1!commons-collections.jar (2356ms)
[ivy:install] downloading http://repo1.maven.org/maven2/commons-collections/commons-collections/2.1/commons-collections-2.1.jar ...
[ivy:install] .................................................................................................................................................................................................................................................................................................. (161kB)
[ivy:install] ... (0kB)
[ivy:install] [SUCCESSFUL ] commons-collections#commons-collections;2.1!commons-collections.jar (1638ms)
[ivy:install] downloading http://repo1.maven.org/maven2/ant/ant/1.6.5/ant-1.6.5.jar ...
[ivy:install] ..............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................ (1009kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] ant#ant;1.6.5!ant.jar (5304ms)
[ivy:install] downloading http://repo1.maven.org/maven2/swarmcache/swarmcache/1.0RC2/swarmcache-1.0RC2.jar ...
[ivy:install] ......................................................... (29kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] swarmcache#swarmcache;1.0RC2!swarmcache.jar (1670ms)
[ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-cache/1.2.2/jboss-cache-1.2.2.jar ...
[ivy:install] ......................................................................................................
[ivy:install] .................................................................................................
[ivy:install] ................................................................................................................................................................................................................................
[ivy:install] ...................................................................................................................................................................................................................................................................................................................................
[ivy:install] ..... (365kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] jboss#jboss-cache;1.2.2!jboss-cache.jar (8470ms)
[ivy:install] downloading http://repo1.maven.org/maven2/jgroups/jgroups-all/2.2.8/jgroups-all-2.2.8.jar ...
[ivy:install] ........................................................................................................................................................................................................................................................................................................................................
[ivy:install] .............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ...........................................................................................................................................................................................................................................................................................................................
[ivy:install] .........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (1573kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] jgroups#jgroups-all;2.2.8!jgroups-all.jar (8954ms)
[ivy:install] downloading http://repo1.maven.org/maven2/c3p0/c3p0/0.9.1/c3p0-0.9.1.jar ...
[ivy:install] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (594kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] c3p0#c3p0;0.9.1!c3p0.jar (4836ms)
[ivy:install] downloading http://repo1.maven.org/maven2/opensymphony/oscache/2.1/oscache-2.1.jar ...
[ivy:install] ............................................................................................................................................................................................................................. (111kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] opensymphony#oscache;2.1!oscache.jar (1856ms)
[ivy:install] downloading http://repo1.maven.org/maven2/proxool/proxool/0.8.3/proxool-0.8.3.jar ...
[ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (464kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] proxool#proxool;0.8.3!proxool.jar (7238ms)
[ivy:install] downloading http://repo1.maven.org/maven2/commons-logging/commons-logging/1.0.2/commons-logging-1.0.2.jar ...
[ivy:install] .................................................. (25kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] commons-logging#commons-logging;1.0.2!commons-logging.jar (4790ms)
[ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-system/4.0.2/jboss-system-4.0.2.jar ...
[ivy:install] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (227kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] jboss#jboss-system;4.0.2!jboss-system.jar (2917ms)
[ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-common/4.0.2/jboss-common-4.0.2.jar ...
[ivy:install] ..................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (457kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] jboss#jboss-common;4.0.2!jboss-common.jar (3666ms)
[ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-minimal/4.0.2/jboss-minimal-4.0.2.jar ...
[ivy:install] .......................................................................................................................................................................................................................................................................................................................... (163kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] jboss#jboss-minimal;4.0.2!jboss-minimal.jar (2215ms)
[ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-j2se/200504122039/jboss-j2se-200504122039.jar ...
[ivy:install] .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (350kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] jboss#jboss-j2se;200504122039!jboss-j2se.jar (2714ms)
[ivy:install] downloading http://repo1.maven.org/maven2/concurrent/concurrent/1.3.4/concurrent-1.3.4.jar ...
[ivy:install] ........................................................................................................................................................................................................................................................................................................................................... (184kB)
[ivy:install] ... (0kB)
[ivy:install] [SUCCESSFUL ] concurrent#concurrent;1.3.4!concurrent.jar (2574ms)
[ivy:install] downloading http://repo1.maven.org/maven2/jgroups/jgroups-all/2.2.7/jgroups-all-2.2.7.jar ...
[ivy:install] .......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] .....................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ................................................................................................................................................................................... (1613kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] jgroups#jgroups-all;2.2.7!jgroups-all.jar (7052ms)
[ivy:install] downloading http://repo1.maven.org/maven2/slide/webdavlib/2.0/webdavlib-2.0.jar ...
[ivy:install] ......................................................................................................................................................................................................................................................................... (128kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] slide#webdavlib;2.0!webdavlib.jar (2792ms)
[ivy:install] downloading http://repo1.maven.org/maven2/xerces/xercesImpl/2.6.2/xercesImpl-2.6.2.jar ...
[ivy:install] .............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ (986kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] xerces#xercesImpl;2.6.2!xercesImpl.jar (4087ms)
[ivy:install] :: installing in my-repository ::
[ivy:install] published hibernate to /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/sources/hibernate-3.2.5.ga.jar
[ivy:install] published hibernate to /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/javadocs/hibernate-3.2.5.ga.jar
[ivy:install] published hibernate to /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/jars/hibernate-3.2.5.ga.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/ivys/ivy-3.2.5.ga.xml
[ivy:install] published ehcache to /ivy/build-a-ivy-repository/myrepository/no-namespace/net.sf.ehcache/ehcache/jars/ehcache-1.2.3.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/net.sf.ehcache/ehcache/ivys/ivy-1.2.3.xml
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/javax.transaction/jta/ivys/ivy-1.0.1B.xml
[ivy:install] published commons-logging to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-logging/commons-logging/jars/commons-logging-1.0.4.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-logging/commons-logging/ivys/ivy-1.0.4.xml
[ivy:install] published asm-attrs to /ivy/build-a-ivy-repository/myrepository/no-namespace/asm/asm-attrs/jars/asm-attrs-1.5.3.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/asm/asm-attrs/ivys/ivy-1.5.3.xml
[ivy:install] published dom4j to /ivy/build-a-ivy-repository/myrepository/no-namespace/dom4j/dom4j/jars/dom4j-1.6.1.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/dom4j/dom4j/ivys/ivy-1.6.1.xml
[ivy:install] published antlr to /ivy/build-a-ivy-repository/myrepository/no-namespace/antlr/antlr/jars/antlr-2.7.6.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/antlr/antlr/ivys/ivy-2.7.6.xml
[ivy:install] published cglib to /ivy/build-a-ivy-repository/myrepository/no-namespace/cglib/cglib/jars/cglib-2.1_3.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/cglib/cglib/ivys/ivy-2.1_3.xml
[ivy:install] published asm to /ivy/build-a-ivy-repository/myrepository/no-namespace/asm/asm/jars/asm-1.5.3.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/asm/asm/ivys/ivy-1.5.3.xml
[ivy:install] published commons-collections to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-collections/commons-collections/jars/commons-collections-2.1.1.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-collections/commons-collections/ivys/ivy-2.1.1.xml
[ivy:install] published commons-collections to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-collections/commons-collections/jars/commons-collections-2.1.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-collections/commons-collections/ivys/ivy-2.1.xml
[ivy:install] published ant to /ivy/build-a-ivy-repository/myrepository/no-namespace/ant/ant/jars/ant-1.6.5.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/ant/ant/ivys/ivy-1.6.5.xml
[ivy:install] published swarmcache to /ivy/build-a-ivy-repository/myrepository/no-namespace/swarmcache/swarmcache/jars/swarmcache-1.0RC2.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/swarmcache/swarmcache/ivys/ivy-1.0RC2.xml
[ivy:install] published jboss-cache to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-cache/jars/jboss-cache-1.2.2.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-cache/ivys/ivy-1.2.2.xml
[ivy:install] published jgroups-all to /ivy/build-a-ivy-repository/myrepository/no-namespace/jgroups/jgroups-all/jars/jgroups-all-2.2.8.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jgroups/jgroups-all/ivys/ivy-2.2.8.xml
[ivy:install] published c3p0 to /ivy/build-a-ivy-repository/myrepository/no-namespace/c3p0/c3p0/jars/c3p0-0.9.1.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/c3p0/c3p0/ivys/ivy-0.9.1.xml
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/javax.security/jacc/ivys/ivy-1.0.xml
[ivy:install] published oscache to /ivy/build-a-ivy-repository/myrepository/no-namespace/opensymphony/oscache/jars/oscache-2.1.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/opensymphony/oscache/ivys/ivy-2.1.xml
[ivy:install] published proxool to /ivy/build-a-ivy-repository/myrepository/no-namespace/proxool/proxool/jars/proxool-0.8.3.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/proxool/proxool/ivys/ivy-0.8.3.xml
[ivy:install] published commons-logging to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-logging/commons-logging/jars/commons-logging-1.0.2.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-logging/commons-logging/ivys/ivy-1.0.2.xml
[ivy:install] published jboss-system to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-system/jars/jboss-system-4.0.2.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-system/ivys/ivy-4.0.2.xml
[ivy:install] published jboss-common to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-common/jars/jboss-common-4.0.2.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-common/ivys/ivy-4.0.2.xml
[ivy:install] published jboss-minimal to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-minimal/jars/jboss-minimal-4.0.2.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-minimal/ivys/ivy-4.0.2.xml
[ivy:install] published jboss-j2se to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-j2se/jars/jboss-j2se-200504122039.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-j2se/ivys/ivy-200504122039.xml
[ivy:install] published concurrent to /ivy/build-a-ivy-repository/myrepository/no-namespace/concurrent/concurrent/jars/concurrent-1.3.4.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/concurrent/concurrent/ivys/ivy-1.3.4.xml
[ivy:install] published jgroups-all to /ivy/build-a-ivy-repository/myrepository/no-namespace/jgroups/jgroups-all/jars/jgroups-all-2.2.7.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jgroups/jgroups-all/ivys/ivy-2.2.7.xml
[ivy:install] published webdavlib to /ivy/build-a-ivy-repository/myrepository/no-namespace/slide/webdavlib/jars/webdavlib-2.0.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/slide/webdavlib/ivys/ivy-2.0.xml
[ivy:install] published xercesImpl to /ivy/build-a-ivy-repository/myrepository/no-namespace/xerces/xercesImpl/jars/xercesImpl-2.6.2.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/xerces/xercesImpl/ivys/ivy-2.6.2.xml
[ivy:install] :: install resolution report ::
[ivy:install] :: resolution report :: resolve 0ms :: artifacts dl 137701ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 28 | 28 | 28 | 0 || 30 | 28 |
---------------------------------------------------------------------
[ivy:install]
[ivy:install] :: problems summary ::
[ivy:install] :::: WARNINGS
[ivy:install] [NOT FOUND ] javax.transaction#jta;1.0.1B!jta.jar (0ms)
[ivy:install] ==== libraries: tried
[ivy:install] http://repo1.maven.org/maven2/javax/transaction/jta/1.0.1B/jta-1.0.1B.jar
[ivy:install] [NOT FOUND ] javax.security#jacc;1.0!jacc.jar (0ms)
[ivy:install] ==== libraries: tried
[ivy:install] http://repo1.maven.org/maven2/javax/security/jacc/1.0/jacc-1.0.jar
[ivy:install] ::::::::::::::::::::::::::::::::::::::::::::::
[ivy:install] :: FAILED DOWNLOADS ::
[ivy:install] :: ^ see resolution messages for details ^ ::
[ivy:install] ::::::::::::::::::::::::::::::::::::::::::::::
[ivy:install] :: javax.transaction#jta;1.0.1B!jta.jar
[ivy:install] :: javax.security#jacc;1.0!jacc.jar
[ivy:install] ::::::::::::::::::::::::::::::::::::::::::::::
[ivy:install]
[ivy:install]
[ivy:install] :: USE VERBOSE OR DEBUG MESSAGE LEVEL FOR MORE DETAILS
As you can see the installation has failed, if you look at the log you will see that there are missing artifacts on the source repository. This means that you will need to download those artifacts manually, and copy them to your destination repository to complete the installation. Fortunately Ivy uses a best effort algorithm during install, so that everything gets installed except the missing artifacts. (Note: these missing artifacts are not in the public maven repository due to licensing issues)
You may also have noticed that Ivy installed 2 different revisions of commons-logging (1.0.2, 1.0.4). This is due to the fact that we used the "no conflict" conflict manager in the ivysettings file.
We do not want to evict any modules because we are building our own repository. Indeed if we get both commons-logging 1.0.2 and 1.0.4 it's because some modules among the transitive dependencies of hibernate depend on 1.0.2 and others on 1.0.4. If we got only 1.0.4, the module depending on 1.0.2 would be inconsistent in your own repository (depending on a version you don't have installed). Thus developers using this module directly would run into a problem.
If you now have a closer look at your repository, you will probably notice that it isn't an exact replication of the original one. Let's have a look at the directory of one module:
[ivy@apache:/]$ find /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate -type f -print
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/ivys/ivy-3.2.5.ga.xml
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/ivys/ivy-3.2.5.ga.xml.md5
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/ivys/ivy-3.2.5.ga.xml.sha1
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/jars/hibernate-3.2.5.ga.jar
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/jars/hibernate-3.2.5.ga.jar.md5
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/jars/hibernate-3.2.5.ga.jar.sha1
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/javadocs/hibernate-3.2.5.ga.jar
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/javadocs/hibernate-3.2.5.ga.jar.md5
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/javadocs/hibernate-3.2.5.ga.jar.sha1
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/sources/hibernate-3.2.5.ga.jar
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/sources/hibernate-3.2.5.ga.jar.md5
/ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/sources/hibernate-3.2.5.ga.jar.sha1
As you can see there is no pom here (pom is the module metadata format used by maven 2, available on the maven 2 repository). Instead you can see there's an ivy file, which is actually the original hibernate pom converted into an ivy file. So now you have a true Ivy repository with ivy files, where you can use the full power of Ivy if you want to adjust the module metadata (module configurations, fine grain exclusions and transitivity control, per module conflict manager, ...).
OK, enough for this simple repository installation, the next tutorial will show how you can deal with more complex cases where your source and destination repositories do not follow the same naming conventions.
Using namespaces
Now that you have seen how simple it is to create your own repository from an existing one, you may wonder how you can handle more complex cases, like when the source and destination repositories don't follow the same naming conventions.
On the road to a professional repository
In this section, you will learn how to build a professional repository. What is a professional repository? Our vision is to say that a good quality repository must follow clear rules about projects naming and must offer correct, useable, configurations 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 always the expected one, especially concerning the naming rules used.
This problem is pretty normal when you have an existing repository, and want to benefit from large public repositories which do not follow the same naming conventions. It also shows up because many public repositories do not use a consistent naming scheme. For example, why don't all the apache commons modules use the org.apache.commons organization? Well.. for historical reasons. But if you setup your own repository, you may not want to suffer from the mistakes of history.
Fortunately, Ivy has a very powerful answer to this problem: namespaces.
Using namespaces
If you look at the repository built with the previous tutorial, you will see exactly what we were talking about: all apache commons modules use their own name as their organization.
So let's see what Ivy can do using namespaces (we will dig into details later):
[ivy@apache:/ivy/build-a-ivy-repository]$ ant maven2-namespace
Buildfile: /ivy/build-a-ivy-repository/build.xml
load-ivy:
init-ivy:
maven2-namespace:
[ivy:install] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:install] :: loading settings :: file = /ivy/build-a-ivy-repository/settings/ivysettings-advanced.xml
[ivy:install] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/build-a-ivy-repository/settings/ivysettings-advanced.xml)
[ivy:install] :: installing apache#commons-lang;1.0 ::
[ivy:install] :: resolving dependencies ::
[ivy:install] found apache#commons-lang;1.0 in libraries
[ivy:install] :: downloading artifacts to cache ::
[ivy:install] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0.jar ...
[ivy:install] ....................................................................................................................... (62kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] apache#commons-lang;1.0!commons-lang.jar (3151ms)
[ivy:install] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0-javadoc.jar ...
[ivy:install] ..................................................................................................................................................................................................................................................................................................................................................................... (170kB)
[ivy:install] .. (0kB)
[ivy:install] [SUCCESSFUL ] apache#commons-lang;1.0!commons-lang.jar(javadoc) (3104ms)
[ivy:install] :: installing in my-repository ::
[ivy:install] published commons-lang to /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/jars/commons-lang-1.0.jar
[ivy:install] published commons-lang to /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/javadocs/commons-lang-1.0.jar
[ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/ivys/ivy-1.0.xml
[ivy:install] :: install resolution report ::
[ivy:install] :: resolution report :: resolve 0ms :: artifacts dl 6255ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 1 | 1 | 1 | 0 || 2 | 2 |
---------------------------------------------------------------------
BUILD SUCCESSFUL
Total time: 10 seconds
Now if we look at our repository, it seems to look fine.
$ find /ivy/build-a-ivy-repository/myrepository/advanced -type f -print
/ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/ivys/ivy-1.0.xml
/ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/ivys/ivy-1.0.xml.md5
/ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/ivys/ivy-1.0.xml.sha1
/ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/jars/commons-lang-1.0.jar
/ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/jars/commons-lang-1.0.jar.md5
/ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/jars/commons-lang-1.0.jar.sha1
/ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/javadocs/commons-lang-1.0.jar
/ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/javadocs/commons-lang-1.0.jar.md5
/ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/javadocs/commons-lang-1.0.jar.sha1
We can even have a look at the commons-lang ivy file in our repository:
<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="1.0">
<info organisation="apache"
module="commons-lang"
revision="1.0"
status="integration"
publication="20051124062021"
namespace="ibiblio-maven2"
/>
...
Alright, we see that the organisation is now 'apache'. But where did Ivy pick this up?
How does this work ?
Actually, Ivy uses the same repository as before for the source repository, with only one difference: the namespace parameter:
<ibiblio name="libraries"
root="${ibiblio-maven2-root}"
m2compatible="true"
namespace="maven2"
/>
A namespace is defined by a set of rules. These rules are based on regular expressions and tell Ivy how to convert data from the repository namespace to what is called the system namespace, i.e. the namespace in which Ivy runs most of the time (Note: the Ivy cache always uses the system namespace).
For the namespace we call maven2, we have declared several rules. Below is one of the rules:
rule handling the 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 organization, module, and revision, the notation Ivy uses prefixes the matching regular expression with the letters 'o', 'm' and 'r'.
$o0 : the whole matching value in the organization attribute
$o1 : the first matching expression group that was marked in the organization attribute
...
The same applies for modules : $m0, $m1, ...
and for revisions : $r0, $r1, ...
To understand namespaces,
- fromsystem : we define here that the projects defined in the system namespace under the organization called "apache" are transformed into the destination namespace into projects whose organization is named with the module name, whatever the revision is. For example, the project apache#commons-lang;1.0 in the system namespace will be translated into commons-lang#commons-lang;1.0 in the maven2 resolver namespace.
- tosystem : we define here the reverse mapping, i.e. how to translate apache projects from maven 2 repo into apache projects in the system namespace. The rule used here tells Ivy that all projects matching commons-.+ (see it as java regular expression) for their organization 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 defined for others apache projects like ant, etc.
OK, you should now get the idea behind namespaces, so go ahead and look at the ivysettings-advanced.xml file in this example. You can test the installation of a module and its dependencies using namespaces.
Run
ant maven2-namespace-deps
and you will see the resulting repository is cleaner than the first one we built.
From our experience, investing in creating a namespace is worth the time it costs if you often need to add new modules or revisions of third party libraries in your own repository, where naming rules already exist or are rather strict.
More examples
If you have successfully followed and understood all the tutorials, you still might need to get a better picture of how to use Ivy in the real world.
Here are some links which might 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.
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 makes 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.
Reference
Welcome to the Ivy reference documentation!
If you don't know Ivy at all, take a look at its features, the faq and the tutorials before digging into this reference documentation.
Reference Overview
This documentation is broken into several parts:
- Introduction
- Terminology
This part gives you the meaning of some words used all over the Ivy documentation, such as organization, module, configurations, settings, ...
- Main Concepts
This part introduces the main concepts used in Ivy: dependency resolvers, variables, patterns, and also a good introduction to a central ivy concept: module configurations.
- How does it work ?
As the title suggests, here you will find an explanation of how Ivy does work internally, which can help to better understand and customize its use.
- Installation
This part describes how to install Ivy.
- Settings Files
This part is dedicated to the specification of the settings file of Ivy (usually called ivysettings.xml). It also gives the list of built-in dependency resolvers available in Ivy.
- Ivy Files
This part is the reference for the module descriptors, the Ivy files in which you describe your dependencies. If you have any questions about what can be done or not in an ivy file, you will find the answer here.
- Ant Tasks
This part describes how to use Ivy from ant. It's in this section that all ant tasks provided by Ivy are specified.
- Using standalone
Even though Ivy is most often used from ant, it can also be used from the command line. This page describes how you can do this.
Introduction
Terminology
Here are some terms used in Ivy, with their definitions in Ivy:
- Organisation
- Module
- Module Descriptor
- Artifact
- Type of an artifact
- Artifact file name extension
- Module Revision
- Branch
- Status of a revision
- Configurations of a module
- Ivy Settings
- Repository
Overview
The following illustration shows all the key terminology in one diagram:
Organisation
An organisation is either a company, an individual, or simply any group of people that produces software. In principle, Ivy handles only a single level of organisation, meaning that they have a flat namespace in Ivy module descriptors. So, with Ivy descriptors, you can only describe a tree-like organisation structure, if you use a hierarchical naming convention. The organisation name is used for keeping together software produced by the same team, just to help locate their published works.
Often organisations will use their inverted domain name as their organisation name in Ivy, since domain names by definition are unique. A company whose domain name is www.example.com might want to use com.example, or if they had multiple teams, all their organisation names could begin with com.example (e.g. com.example.rd, com.example.infra, com.example.services). The organisation name does neither really have to be an inverted domain name, nor even globally unique, but unique naming is highly recommended. Widely recognized trademark or trade name owners may choose to use their brand name instead.
Examples: org.apache, ibm, jayasoft
Note that the Ivy "organisation" is very similar to Maven POM "groupId".
Module
A module is a self-contained, reusable unit of software that, as a whole unit, follows a revision control scheme.
Ivy is only concerned about the module deliverables known as artifacts, and the module descriptor that declares them. These deliverables, for each revision of the module, are managed in repositories. In other words, to Ivy, a module is a chain of revisions each comprising a descriptor and one or more artifacts.
Examples: hibernate-entitymanager, ant
Module Descriptor
A module descriptor is a generic way of identifying what describes a module: the identifier (organisation, module name, branch and revision), the published artifacts, possible configurations and their dependencies.
The most common module descriptors in Ivy are Ivy Files, xml files with an Ivy specific syntax, and usually called ivy.xml.
But since Ivy is also compatible with maven 2 metadata format (called pom, for Project Object Model), pom files fall into the category of module descriptors.
And because Ivy accepts pluggable module descriptor parsers, you can use almost whatever you want as module descriptors.
Artifact
An artifact is a single file ready for delivery with the publication of a module revision, as a product of development.
Compressed package formats are often preferred because they are easier to manage, transfer and store. For the same reasons, only one or a few artifacts per module are commonly used. However, artifacts can be of any file type and any number of them can be declared in a single module.
In the Java world, common artifacts are Java archives or JAR files. In many cases, each revision of a module publishes only one artifact (like jakarta-log4j-1.2.6.tar.gz, for instance), but some of them publish many artifacts dependending on the use of the module (like apache-ant binary and source distributions in zip, gz and bz2 package formats, for instance).
Examples: ant-1.7.0-bin.zip, apache-ant-1.7.0-src.tar.gz
Type of an artifact
The artifact type is a category of a particular kind of artifact specimen. It is a classification based on the intended purpose of an artifact or why it is provided, not a category of packaging format or how the artifact is delivered.
Although the type of an artifact may (rather accidentally) imply its file format, they are two different concepts. The artifact file name extension is more closely associated with its format. For example, in the case of Java archives the artifact type "jar" indicates that it is indeed a Java archive as per the JAR File specification. The file name extension happens to be "jar" as well. On the other hand, with source code distributions, the artifact type may be "source" while the file name extensions vary from "tar.gz", "zip", "java", "c", or "xml" to pretty much anything. So, the type of an artifact is basically an abstract functional category to explain its purpose, while the artifact file name extension is a more concrete technical indication of its format and, of course, naming.
Defining appropriate artifact types for a module is up to its development organisation. Common choices may include: "jar", "binary", "bin", "rc", "exe", "dll", "source", "src", "config", "conf", "cfg", "doc", "api", "spec", "manual", "man", "data", "var", "resource", "res", "sql", "schema", "deploy", "install", "setup", "distrib", "distro", "distr", "dist", "bundle", etc.
Module descriptors are not really artifacts, but they are comparable to an artifact type, i.e. "descriptor" (an ivy file or a Maven POM).
Electronic signatures or digests are not really artifacts themselves, but can be found with them in repositories. They also are comparable to an artifact type, i.e. "digest" (md5 or sha1).
Artifact file name extension
In some cases the artifact type already implies its file name extension, but not always. More generic types may include several different file formats, e.g. documentation can contain tarballs, zip packages or any common document formats.
Examples: zip, tar, tar.gz, rar, jar, war, ear, txt, doc, xml, html
Module Revision and Status
Module revision
A unique revision number or version name is assigned to each delivered unique state of a module. Ivy can help in generating revision numbers for module delivery and publishing revisions to repositories, but other aspects of revision control, especially source revisioning, must be managed with a separate version control system.
Therefore, to Ivy, a revision always corresponds to a delivered version of a module. It can be a public, shared or local delivery, a release, a milestone, or an integration build, an alpha or a beta version, a nightly build, or even a continuous build. All of them are considered revisions by Ivy.
Source revision
Source files kept under a version control system (like Subversion, CVS, SourceSafe, Perforce, etc.) have a separate revisioning scheme that is independent of the module revisions visible to Ivy. Ivy is unaware of any revisions of a module's source files.
In some cases, the SCM's source revision number could be used also as the module revision number, but that usage is very rare. They are still two different concepts, even if the module revision number was wholly or partially copied from the respective source revision number.
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.
Status of a revision
A module's 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: a revision fully tested and labelled fall in this category
Since 1.4 This list is configurable in your settings file.
Configurations of a module
A module configuration is a way to use or construct a module. If the same module has different dependencies based on how it's used, those distinct dependency-sets are called its configurations in Ivy.
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 different ways to use or build a module are called module configurations in ivy.
For more details on configurations and how they are used in ivy, please refer to the main concepts page.
Ivy Settings
Ivy settings files are xml files used to configure ivy to indicate where the modules can be found and how.
History of settings
Prior to Ivy 2.0, the settings files were called configuration files and usually named ivyconf.xml. This resulted in confusion between module configurations and Ivy configuration files, so they were renamed to settings files. If you happen to fall on an ivyconf file or something called a configuration file, most of the time it's only unupdated information (documentation, tutorial or article). Feel free to report any problem like this if you find such an inconsistency.
Repository
What is called a repository in Ivy is a distribution site location where Ivy is able to find your required modules' artifacts and descriptors (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: an artifact can be on a web site, or on the local file system of your machine. The download is thus the act of bring a file from a repository to the ivy cache.
Moreover, the fact that it is the responsibility of the resolver to find ivy files and download artifacts helps to implement various resolving strategies.
As you see, a dependency resolver can be thought of as a class responsible for 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 because ivy can't work without configurations. 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 get better dependencies resolution, configurations will meet most of your needs.
For details on how to declare your module configurations, how to 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 you 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 overridden, whereas ant
properties can't, and that they are defined in separate environments.
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 the 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 encounters 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 (actually they are first loaded as ant properties and then imported as ivy variables, see Ant Tasks), 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 ivysettings.properties file. Some variables will really only be able to be overridden via ant properties because of this.
Moreover, it's also important to understand the difference between ivy variables and ivy pattern tokens.
See the Patterns chapter below for 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 a hyphen, then the revision, a dot, and the artifact extension.
Not too difficult to understand is 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)
The difference between type and extension is explained in the ivy file documentation.
since 1.2 [organization] can be used instead of [organisation].
since 1.3 Optional parts can be used in patterns.
This provides 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]
lets 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 of artifact names.
since 1.4 Extra attributes can be used as any other token in a pattern.
Latest Strategy
Ivy often needs to know which revision between two is considered the "latest". To know that, it uses the concept of latest strategy. Indeed, there are several ways to consider a revision to be the latest. You can choose an existing one or plug in your own.
But before knowing which revision is the latest, ivy needs to be able to consider several revisions 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 does 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 the revisions is the latest one.
Ivy has three built-in latest strategies:
- latest-time
This 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 of being costly to compute for 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
This compares the revisions as strings, using an algorithm close to the one used in the php version_compare function.
This algorithm takes into account special meanings 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
This compares the revisions as strings, using lexicographic order (the one used by the 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 select a list of revisions, even if most conflict managers 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.
For more details on how to setup your conflict managers by module, see the conflicts section in the ivy file reference.
Pattern matcher
since 1.3
In several places Ivy uses a 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 a pluggable pattern matcher to match those object names. 3 are defined by default:
- exact
This matcher matches only using strings
- regexp
This matcher lets you use a regular expression as supported by the Pattern class of java 1.4 or greater
- glob
This matcher lets you use a 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.
since 2.0
It's possible and recommended to use xml namespaces for your extra attributes. Using an Ivy extra namespace is the easiest way to add your own extra attributes.
Example:
Here is an ivy file with the attribute 'color' set to blue:
<ivy-module version="2.0" xmlns:e="http://ant.apache.org/ivy/extra">
<info organisation="apache"
module="foo"
e:color="blue"
status="integration"
revision="1.59"
/>
</ivy-module>
Then you must use the extra attribute when you declare a dependency on foo. Those extra attributes
will indeed be used as identifiers for the module like the org the name and the revision:
<dependency org="apache" name="foo" e:color="blue" rev="1.5+" />
And you can define your repository pattern as:
${repository.dir}/[organisation]/[module]/[color]/[revision]/[artifact].[ext]
Note that in patterns you must use the unqualified attribute name (no namespace prefix).
If you don't want to use xml namespaces, it's possible but you will need to disable ivy file validation, since your files won't fulffill anymore the official ivy xsd. See the settings documentation to see how to disable validation.
Checksums
since 1.4
Ivy allows the use of checksums, also known as digests, to verify the correctness of a downloaded file.
For the moment Ivy supports the md5 and sha1 algorithms.
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 algorithms 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 an 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 allows, for example, you 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 events 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 a 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.
Cache and Change Management
Ivy heavily relies on local caching to avoid accessing remote repositories too often, thus saving a lot of network bandwidth and time.
Cache types
An Ivy cache is composed of two different parts:
- the repository cache
The repository cache is where Ivy stores data downloaded from module repositories, along with some meta information concerning these artifacts, like their original location.
This part of the cache can be shared if you use a well suited lock strategy.
- the resolution cache
This part of the cache is used to store resolution data, which is used by Ivy to reuse the results of a resolve process.
This part of the cache is overwritten each time a new resolve is performed, and should never be used by multiple processes at the same time.
While there is always only one resolution cache, you can define multiple repository caches, each resolver being able to use a separate cache.
Change management
To optimize the dependency resolution and the way the cache is used, Ivy assumes by default that a revision never changes. So once Ivy has a module in its cache (metadata and artifacts), it trusts the cache and does not even query the repository. This optimization is very useful in most cases, and causes no problem as long as you respect this paradigm: a revision never changes. Besides performance, there are several good reasons to follow this principle.
However, depending on your current build system and your dependency management strategy, you may prefer to update your modules sometimes. There are two kinds of changes to consider:
Changes in module metadata
Since pretty often module metadata are not considered by module providers with as much attention as their API or behavior (if they even provide module metadata), it happens more than we would like that we have to update module metadata: a dependency has been forgotten, or another one is missing, ...
In this case, setting checkModified="true" on your dependency resolver will be the solution. This flag tells Ivy to check if module metadata has been modified compared to the cache. Ivy first checks the metadata last modified timestamp on the repository to download it only if necessary, and then updates it when needed.
Changes in artifacts
Some people, especially those coming from maven 2 land, like to use one special revision to handle often updated modules. In maven 2 this is called a SNAPSHOT version, and some argue that it helps save disk space to keep only one version for the high number of intermediary builds you can make whilst developing.
Ivy supports this kind of approach with the notion of "changing revision". A changing revision is just that: a revision for which Ivy should consider that the artifacts may change over time. To handle this, you can either specify a dependency as changing on the dependency tag, or use the changingPattern and changingMatcher attributes on your resolvers to indicate which revision or group of revisions should be considered as changing.
Once Ivy knows that a revision is changing, it will follow this principle to avoid checking your repository too often: if the module metadata has not changed, it will considered the whole module (including artifacts) as not changed. Even if the module descriptor file has changed, it will check the publication data of the module to see if this is a new publication of the same revision or not. Then if the publication date has changed, it will check the artifacts' last modified timestamps, and download them accordingly.
So if you want to use changing revisions, use the publish task to publish your modules, it will take care of updating the publication date, and everything will work fine. And remember to set checkModified=true" on your resolver too!
Paths handling
As a dependency manager, Ivy has a lot of file related operations, which most of the time use paths or path patterns to locate the file on the filesystem.
These paths can obviously be relative or absolute. We recommend to always use absolute paths, so that you don't have to worry about what is the base of your relative paths. Ivy provides some variables which can be used as the base of your absolute paths. For instance, Ivy has a concept of base directory, which is basically the same as for Ant. You have access to this base directory with the ivy.basedir variable. So if you have a path like ${ivy.basedir}/ivy.xml, you have an absolute path. In settings files, you also have a variable called ivy.settings.dir which points to the directory in which your settings file is located, which makes defining paths relative to this directory very easy.
If you really want to use relative paths, the base directory used to actually locate the file depends on where the relative path is defined:
- In an Ivy file, paths are relative to the Ivy file itself (the only possible path in an Ivy file is for configurations declaration inclusion)
- In settings files, paths for file inclusion (namely properties file loading and settings inclusion) are relative to the directory in which the settings file is located. All other paths must be absolute unless explicitly noted.
- In Ivy Ant tasks and Ivy parameters or options, paths are relative to Ivy base directory, which when called from Ant is the same as your Ant basedir.
Text Conventions
Very often some concepts discussed in Ivy here, and especially those involving modules and dependencies, require to be discussed by text (e-mail, textual doc, console, ...), and so benefit from convention in this area.
The conventions have been adopted with Ivy 2.0 are the following:
what
pattern
example
a module without revision
[organisation]#[module]
org.apache.ant#ant
a module with revision
[organisation]#[module];[revision]
org.apache.ant#ant;1.7.0
a module with (some) configurations
[organisation]#[module][ [confs] ]
org.apache.ant#ant[master,compile,build]
a module with revision and (some) configurations
[organisation]#[module];[revision][ [confs] ]
org.apache.ant#ant;1.7.0[master,compile,build]
a module's artifact
[organisation]#[module]![artifact].[ext]([type])
org.apache.ant#ant!ant.jar(source)
a module's artifact with revision
[organisation]#[module];[revision]![artifact].[ext]([type])
org.apache.ant#ant;1.7.0!ant.jar(source)
Another usual text representation used is to represent dependencies using a dash followed by greater than sign: ->
To group a set of set of modules, we recommend using curly braces { }
With these conventions, it's easy to give a concise and detailed overview of a set of modules and their dependencies.
For instance:
#A;2-> { #B;[1.0,1.5] #C;[2.0,2.5] }
#B;1.4->#D;1.5
#B;1.5->#D;2.0
#C;2.5->#D;[1.0,1.6]
In full words here is how it could be written:
module A revision 2 depends on module B with the version constraint [1.0,1.5], and on module C with the version constraint [2.0,2.5].
module B revision 1.4 depends on module D revision 1.5.
module B revision 1.5 depends on module D revision 2.0.
module C revision 2.5 depends on module D with the version constraint [1.0,1.6].
As you can see, using text conventions is much more concise.
Another benefit is that these conventions are usually used in Ivy console output, and can also be used in some cases to be parsed into Ivy objects (we use it for test cases for instance). To make sure text parsing works fine, we recommend using only a limited range of characters for each attributes of your module identifiers.
Here is the recommended characters set for each attribute:
- organisation
a-z A-Z 0-9 - / . _ + =
- module
a-z A-Z 0-9 - / . _ + =
- branch
a-z A-Z 0-9 - / . _ + =
- revision
a-z A-Z 0-9 - / . _ + = , [ ] { } ( ) : @
- artifact
a-z A-Z 0-9 - / . _ + =
- extension
a-z A-Z 0-9 - / . _ + =
- type
a-z A-Z 0-9 - / . _ + =
How does it work ?
Now that you have been introduced to the main ivy terminology and concepts, it is time to give some explanation of how ivy works.
Usual cycle of modules between different locations
Configure
Ivy needs to be configured to be able to resolve your dependencies. This configuration is usually done with a settings file, which defines a set of dependency resolvers. Each resolver is able to find ivy files and/or artifacts, given simple information such as organisation, 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 resolves 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 settings) 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 the ivy cache. Then ivy checks if the dependency module has dependencies, in which case it recursilvely traverses the graph of dependencies.
All over this traversal, conflict management is done to prevent access to a module as soon as possible.
When ivy has traversed the whole graph, it asks the resolvers to download the artifacts corresponding to each of the dependencies which are not already in the cache and which have not been evicted by conflict managers. All downloads are made to the ivy cache.
Finally, an xml report is generated in the cache, which allows ivy to easily know what are all the dependencies of a module, without traversing the graph again.
After this resolve step, two main steps are possible: either build a path with artifacts in the cache, or copy them to another directory structure.
Retrieve
What is called retrieve in ivy is the act of copying 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 the 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 the 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 when building plug-ins for IDEs.
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 future resolving. This task is usually called either manually or from a continuous integration server.
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 produces as artifacts 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 such module descriptors themselves.
First, it will seem like extra work and require time. But when you have several modules using the same third party library, then 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 adding ivy files for all the modules in your repository. You can even enforce this rule by setting the descriptor attribute to required 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:
- control
The main problem with these kinds of public repositories is that you don't have control over the repository. This means that if a module descriptor is broken you cannot easily fix it. Sure you can use a chain between a shared repository and the public one and put your fixed module descriptor in the shared repository so that it hides the one on the public repository, but this makes repository browsing and maintenance cumbersome.
Even more problematic is the possible updates of the repository. We know that versions published in such repositories should be stable and not be updated, but we also frequently see that a module descriptor is buggy, or an artifact corrupted. We even see sometimes a new version published with the same name as the preceding one because the previous one was simply badly packaged. This can occur even to the best; it occurred to us with Ivy 1.2 :-) But then we decided to publish the new version with a different name, 1.2a. But if the repository manager allows such updates, this means that what worked before can break. It can thus break your build reproducibility.
- reliability
The Maven repository is not particularly well known for its reliability (we often experience major slow downs or even complete failures of the site), and ivyrep is only supported by a small company (yes we are only a small company!). So slow down and site hangs occur also. And if the repository you rely on is down, this can cause major slow downs in your development or release process.
- accuracy
A public repository usually contains much more than what you actually need. Is this a problem? We think so. We think that in an enterprise environment the libraries you use should step through some kind of validation process before being used in every projects of your company. And what better way to do so? Setup an enterprise repository with only the libraries you actually want to use. This will not only ensure better quality for your application dependencies, but help to have the same versions everywhere, and even help when declaring your module dependencies, if you use a tool like IvyDE, the code completion will only show relevant information about your repository, with only the libraries you actually want to see.
- security
The artifacts you download from a module repository are often executable, and are thus a security concern. Imagine a hacker replacing commons-lang by another version containing a virus? If you rely on a public repository to build your software, you expose it to a security risk. You can read more about that in this Forrester article.
Note that using an enterprise repository doesn't mean you have to build it entirely by hand. Ivy features an install task which can be used to install modules from one 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 always using the organisation and the module name in your pattern, even for a private repository where you put only your own modules (which all have the same organisation). Why? Because the Ivy listing feature relies 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 repreport.
Public ivysettings.xml with public repositories
If you create a public repository, provide a URL to the ivysettings.xml file. It's pretty easy to do, and if someone wants to leverage your repository, he will just have to load it with settings with the URL of your ivysettings.xml file, 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:
- use a naming convention like a special suffix
the idea is pretty simple, each time you publish a new integration of your module you give the same name to the version (in maven world this is for example 1.0-SNAPSHOT). The dependency manager should then be aware that this version is special because it changes over time, so that it does not trust its local cache if it already has the version, but checks the date of the version on the repository and sees if it has changed. In Ivy this is supported using the changing attribute on a dependency or by configuring the changing pattern to use for all your modules.
- automatically create a new version for each
in this case you use either a build number or a timestamp to publish each new integration version with a new version name. Then you can use one of the numerous ways in Ivy to express a version constraint. Usually selecting the very latest one (using 'latest.integration' as version constraint) is enough.
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 using 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 ones. And this is interesting because it enables, with some work in your build system, the ability 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 who comes on a Monday morning and asks for the latest version of your software, for testing or demonstration purposes. Obviously he needs it for the afternoon :-) Now if you have a continuous integration process and good tracking of your changes and your artifacts, it may occur to you that you are actually able to fulfill his request without needing the use of a DeLorean to give you some more time :-) But it may also occur to you that your latest version is stable enough to be used for the purpose of the customer, but was actually built a few days ago, because the very latest just broke a feature or introduced a new one you don't want to deliver. You can deliver this 'stable' integration build if you want, but rest assured 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 asks 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 for 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 you 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:
- separate revision cycle
if your dependencies may change more often than your build, it's a good idea to separate the two, to isolate the two concepts: describing how to build / describing your project dependencies
- possibility to publish
if you describe dependencies of a module which can itself be reused, you may want to use ant to publish it to a repository. In this case the publication is only possible if you have a separate ivy file
- more flexible
inline dependencies can only be used to express one dependency and only one. An ivy file can be used to express much more complex dependencies
On the other hand, using inline dependencies is very useful when:
- you want to use a custom task in your ant build
Without ivy you usually either copy the custom task jar in ant lib, which requires maintenance of your workstation installation, or use a manual copy or download and a taskdef with the appropriate classpath, which is better. But if you have several custom tasks, or if they have themselves dependencies, it can become cumbersome. Using Ivy with an inline dependency is an elegant way to solve this problem.
- you want to easily deploy an application
If you already build your application and its modules using Ivy, it is really easy to leverage your ivy repository to download your application and all its dependencies on the local filesystem, ready to be executed. If you also put your configuration files as artifacts in your repository (maybee packaged as a zip), the whole installation process can rely on ivy, easing the automatic installation of any version of your application available in your repository!
Hire an expert
Build and dependency management is often given too low a 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 savings 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.
Feedback
These best practices reflect 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.
Installation
There are basically two ways 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 into 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:org.apache.ivy.ant"
- add taskdefs for ivy tasks:
<taskdef name="ivy-configure" classname="org.apache.ivy.ant.IvyConfigure"/>
<taskdef name="ivy-resolve" classname="org.apache.ivy.ant.IvyResolve"/>
<taskdef name="ivy-retrieve" classname="org.apache.ivy.ant.IvyRetrieve"/>
<taskdef name="ivy-publish" classname="org.apache.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 might be the problem with the ivyrep resolver.
Ivy dependendencies
One of the two binary versions of Ivy doesn't include the optional dependencies. To download them using Ivy, all you need is to run the Ant build file provided in the distribution. This will use Ivy itself to download the dependencies. Then you should see the Ivy optional dependencies in the lib directory, organized per configuration (see the ivy.xml for details about the configurations and their use).
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="2.1.0-rc2" />
<condition property="ivy.home" value="${env.IVY_HOME}">
<isset property="env.IVY_HOME" />
</condition>
<property name="ivy.home" value="${user.home}/.ant" />
<property name="ivy.jar.dir" value="${ivy.home}/lib" />
<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://repo2.maven.org/maven2/org/apache/ivy/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="org/apache/ivy/ant/antlib.xml"
uri="antlib:org.apache.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 the ivy namespace to your build script. See the self contained go-ivy example for details about this.
Settings Files
In order to work as you want, ivy sometimes needs some settings. Actually, ivy can work with no specific settings at all, see the default settings documentation for details about that. But ivy is able to work in very different contexts. You just have to configure it properly.
Settings are specified through an xml file, usually called ivysettings.xml. To configure ivy from ant, you just have to use the settings datatype with the path of your settings file.
Here is an example of the settings file:
<ivysettings>
<properties file="${ivy.settings.dir}/ivysettings-file.properties" />
<settings 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>
</ivysettings>
Mainly, the settings enable you to configure the default cache directory used by ivy and the dependency resolvers that it will use to resolve dependencies.
Note: To work, this settings file needs a property file named ivysettings-file.properties in the same directory as the settings file, with ivy variables you want in it.
Some useful variables are available in settings files:
- ivy.settings.dir
this variable references the directory in which the ivysettings itself is. This is available if the settings has been loaded as a file. In case of a URL, it takes the part before the last slash of the URL, if any. If the URL has no slash, then this variable is not set.
- ivy.settings.file
the path of the settings file itself if it has been loaded as a file only. If it has been loaded as a URL, this variable is not set
- ivy.settings.url
the URL pointing to the settings file. This is set both when it has been loaded as a file or a URL
since 1.4 Note that all java system properties are available as ivy variables in your settings file.
Settings file structure
The settings file is structured in some parts and left open in others. Indeed, each resolver has its own structure, thus it's not the settings file itself which defines the structure for the resolvers.
ivysettings
property
properties
settings
include
classpath
typedef
credentials
lock-strategies
caches
cache
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
ivysettings
Tag: ivysettings
Root tag of any ivysettings file.
Child elements
Element Description Cardinality property set an ivy variable
0..n properties loads a properties file as ivy variables
0..n settings configures ivy with some defaults
0..1 include includes another settings file
0..n classpath add a location in the classpath used to load plugins
0..n typedef defines new types in ivy
0..n lock-strategies defines lock strategies
0..1 caches defines repository cache managers
0..1 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 you to avoid overriding the previous value of the variable, which makes the definition behave like an ant property, 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 the variables chapter above for details about ivy variables.
Since 2.0: it is possible to access environment variables. This can be done by specifying the environment attribute. This attribute specifies the prefix which can be used to access these environment variables. For instance, if you specify environment="env", you can access the PATH environment variable with the env.PATH property name.
Attributes
Attribute Description Required file a path to a properties file to load
One of these environment the prefix to use when retrieving environment variables (since 2.0) override indicates if the variable found in the properties file should override its previous value, if any (since 1.3)
No, defaults to true
settings
Tag: settings
Configures some important ivy info: default resolver, latest strategy, conflict manager...
The default resolver is used whenever nothing else is configured in the modules section of the settings file. It should give the name of a dependency resolver defined in the resolvers section of the settings file.
The default latest strategy and conflict manager can also be configured here.
validate indicates if ivy files should generally be validated against the xsd or not. This setting is only a default value, and can be overridden:
1) in ant tasks
2) in resolvers
So if there is a setting in the resolver, it always wins against all other settings.
Attributes
Attribute Description Required 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 defaultResolveMode the default resolve mode to use for all modules, except if they have a module specific resolve mode setting. since 2.0
No, defaults to 'default' 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 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 httpRequestMethod specifies the HTTP method to use to retrieve information about an URL. Possible values are 'GET' and 'HEAD'. This setting can be used to solve problems with firewalls and proxies. (since 2.0)
No, defaults to 'HEAD' defaultCachea path to a directory to use as default basedir for both resolution and repository cache(s).
Deprecated, we recommend using defaultCacheDir on the caches tag instead
No, defaults to .ivy2/cache in user home checkUpToDateIndicates if date should be checked before retrieving artifacts from cache.
Deprecated, we recommend using overwriteMode on the retrieve task instead
No, defaults to true cacheIvyPatterna pattern to indicate where ivy files should be put in cache.
Deprecated, we recommend using ivyPattern on the caches tag instead
No, defaults to [organisation]/[module]/ivy-[revision].xml cacheArtifactPatterna pattern to indicate where artifact files should be put in cache.
Deprecated, we recommend using artifactPattern on the caches tag instead
No, defaults to [organisation]/[module]/[type]s/[artifact]-[revision].[ext]
include
Tag: include
Includes another ivysettings file as if it were part of this one. since 1.3
The included ivysettings file has to be a complete well formed ivysettings file, i.e. it does have to include the <ivysettings>
tag.
Attributes
Attribute Description Required url a URL to the ivysettings file to include
Yes, unless file is specified file a path to the ivysettings file to include
Yes, unless url is specified
Examples
<ivysettings>
<property name="myrepository" value="path/to/my/real/rep"/>
<settings defaultResolver="default"/>
<include file="path/to/ivysettings-default.xml"/>
</ivysettings>
with ivysettings-default.xml:
<ivysettings>
<property name="myrepository" value="path/to/rep" overwrite="false"/>
<resolvers>
<ivyrep name="default" ivyroot="${myrepository}"/>
</resolvers>
</ivysettings>
The included ivysettings 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 override the value given in the main ivysettings including this one, so the value used for myrepository will be path/to/my/real/rep.
<ivysettings>
<include file="ivysettings-macro.xml"/>
<resolvers>
<mymacro name="includeworks" mymainrep="included/myrep" mysecondrep="included/secondrep"/>
</resolvers>
</ivysettings>
with ivysettings-macro.xml being the ivysettings example given on the macrodef documentation page.
This lets us easily reuse the custom macro resolver.
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 an external classpath (the ant classpath for instance), therefore easing the use of ivy in multiple execution environments (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
<ivysettings>
<classpath file="${ivy.settings.dir}/custom-resolver.jar"/>
<typedef name="custom" classname="org.apache.ivy.resolver.CustomResolver"/>
<resolvers>
<custom name="custom"/>
</resolvers>
</ivysettings>
Adds the custom-resolver.jar (found in the same directory as the ivysettings.xml file) to the classpath, then defines a custom resolver and uses it.
<ivysettings>
<classpath url="http://www.myserver.com/ivy/custom-resolver.jar"/>
<typedef name="custom" classname="org.apache.ivy.resolver.CustomResolver"/>
<resolvers>
<custom name="custom"/>
</resolvers>
</ivysettings>
Same as above, but finds 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
Attribute Description Required name the name of the type to define. This name is then used as an xml tag.
Yes classname the fully qualified class name of the type to define.
Yes
credentials
Tag: credentials
Configures HTTP authentication credentials. since 2.0.
Attributes
Attribute Description Required host the name of the host
Yes realm the name of the realm
No username the username
Yes passwd the password
Yes
signers
Tag: signers
since 2.2
Defines a list of detached signature generators usable in ivy. Each generator is identified by its name, given as an attribute.
The child tags used to configure the signature generator must be equal to the name of a signature generator type (either built-in or added with the typedef tag).
Ivy supports the following signature generator out of the box:
- pgp
generates an OpenPGP compatible ASCII armored detached signature.
Child elements
Element Description Cardinality any signature generator adds a signature generator to the list of registered generators
1..n
Built-in Generators
PGP
This generator is capable of generating an OpenPGP compatible ASCII armored detached signature.
Remark: This generator uses the BouncyCastle OpenPGP library. Before this generator can be used, these libraries must be available on Ivy's classpath.
Attribute Description Required name The name of the signature generator.
Yes
secring The location of the secret keyring.
No, defaults to ${user.home}/.gnupg/secring.gpg
keyId The identifier of the key to use. The keyword 'auto' can be used to indicate a key will be selected automatically.
No, defaults to 'auto'.
password The password of the private key.
Yes
Examples
<signers>
<pgp name="mypgp" password="my-password" />
</signers>
Defines a detached signature generator with name 'mypgp' which uses the secret key ring on the default location and automatically selects a private key.
<signers>
<pgp name="mypgp" password="my-password" keyId="123ABC45"/>
</signers>
Same as before, but this time the key '123ABC45' is used to generate the detached signature.
lock-strategies
Tag: lock-strategies since 2.0
Defines a list of lock strategies usable in Ivy.
A lock strategy is used by a cache manager to decide when and how locking should be performed (see settings/cache to see how to configure the lock strategy to use).
Two lock strategies are registered by default:
- no-lock
This lock strategy actually performs no locking at all, and thus should not be used in an environment where the cache is shared by multiple processes.
This strategy is implemented by (NoLockStrategy)
- artifact-lock
This strategy acquires a lock whenever a module descriptor or an artifact is downloaded to the cache, which makes a good solution when you want to share your repository cache.
Note that this strategy is based on file locking, performed by default using the java.io.File.createNewFile() atomicity (which is documented as atomic in the javadoc, but not recommended to perform locks). A java.nio.FileLock based implementation is also provided, but according to our tests the createNewFile based one performs better and more reliably. We heavily recommend making your own testing in your target environment before relying on this lock strategy for heavily concurrent operations.
This strategy is implemented by (ArtifactLockStrategy)
The child tag used for the lock strategy must be equal to a name of a lock strategy type (added with the typedef tag).
Child elements
Element Description Cardinality any lock strategy adds a lock strategy to the list of available ones
0..n
caches
Tag: caches
Configures the Ivy cache system. since 2.0.
See cache concept for details on the Ivy cache concept.
By default, Ivy defines one repository cache instance, called 'default-cache', which uses the default cache settings defined using attributes on this tag. This default instance is defined as long as you don't define your own default cache using the 'default' attribute, and have at least one dependency resolver which doesn't specify which cache instance to use.
defaultCacheDir is the default directory used for both the resolution and repository cache(s). It usually points to a directory in your filesystem. If you want to isolate resolution cache from repository cache, we recommend setting both the resolutionCacheDir and repositoryCacheDir attributes on this tag instead of using defaultCacheDir.
Since repository cache implementations are pluggable, you can either define new cache instances based on the default implementation provided in Ivy using the cache child element, or use custom cache implementations using child elements as you have defined using typedef.
ivyPattern and artifactPattern are used to configure the default way Ivy stores ivy files and artifacts in repository cache(s). Usually you do not have to change this, unless you want to use the cache directly from another tool, which is not recommended. These patterns are relative to the repository cache base directory.
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.
Attributes
Attribute Description Required default the name of the default cache to use on all resolvers not defining the cache instance to use
No, defaults to a default cache manager instance named 'default-cache' defaultCacheDir a path to a directory to use as default basedir for both resolution and repository cache(s)
No, defaults to .ivy2/cache in the user's home directory resolutionCacheDir the path of the directory to use for all resolution cache data
No, defaults to defaultCacheDir repositoryCacheDir the path of the default directory to use for repository cache data. This should not point to a directory used as a repository!
No, defaults to defaultCacheDir ivyPattern default pattern used to indicate where ivy files should be put in the repository cache(s)
No, defaults to [organisation]/[module]/ivy-[revision].xml artifactPattern default pattern used to indicate where artifact files should be put in the repository cache(s)
No, defaults to [organisation]/[module]/[type]s/[artifact]-[revision].[ext] checkUpToDateIndicates if date should be checked before retrieving artifacts from cache.
Deprecated, we recommend using overwriteMode on the retrieve task instead
No, defaults to true useOrigin the default value to use for useOrigin for caches in which it isn't specifically defined.
Use true to avoid the copy of local artifacts to the cache and use directly their original location.
No, defaults to false lockStrategy the name of the default lock strategy to use when accessing repository cache(s)
No, defaults to no-lock
Child elements
Element Description Cardinality cache defines a new repository cache instance, based on the default repository cache implementation
0..n
Examples
<caches>
<cache name="mycache" basedir="path/to/my/cache/1" />
<cache name="mycache2" basedir="path/to/my/cache/2" />
</caches>
Define 2 cache instances, named mycache and mycache2, using two different directories as base directory, and using the default patterns and lock strategies. The default cache instance will still be defined as long as at least one dependency resolver does not declare which cache manager to use.
cache
Tag: cache
Since 2.0.
Defines a repository cache instance based on the default repository cache implementation.
The default repository cache implementation caches files on the local filesystem in subdirectories of a configured base directory.
By default also, the parsed module descriptor read from the cache are kept in a memory cache in case they are reused. This may enhance the performance of multi-module build, provided that all modules are build using the same ivy instance. The size of this memory cache is configurable in term of number of module descriptors. A size of 0 means no memory caching.
Attributes
Attribute Description Required name name of the cache instance
Yes basedir the path of the base directory to use to put repository cache data. This should not point to a directory used as a repository!
No, defaults to repositoryCacheDir defined in caches ivyPattern the pattern to use to store cached ivy files
No, defaults to default cache ivy pattern as configured in caches artifactPattern the pattern to use to store cached artifacts
No, defaults to default cache artifact pattern as configured in caches useOrigin true to avoid the copy of local artifacts to the cache and use directly their original location, false otherwise.
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 use the cache for some non local resolvers. In this case the cache will behave as usual, copying files to the cache. Note also that this only applies to artifacts, not to ivy files, which are still copied in the cache.
No. defaults to the default value configured in caches lockStrategy the name of the lock strategy to use for this cache
No, defaults to default lock strategy as configured in caches defaultTTL the default TTL to use when no specific one is defined
No, defaults to ${ivy.cache.ttl.default} memorySize the number of parsed module descriptors to keep in a memory cache. No, default to 150
Child elements
Element Description Cardinality ttl defines a TTL rule
0..n
Examples
<cache name="mycache"
basedir="/path/to/mycache"
ivyPattern="[module]/ivy-[revision].xml"
artifactPattern="[module]/[artifact]-[revision].[ext]"
lockStrategy="no-lock"
defaultTTL="1s">
<ttl revision="latest.integration" duration="200ms" />
<ttl organisation="org1" duration="10m 20s" />
<ttl organisation="org2" duration="5h" />
<ttl organisation="org3" duration="2d 12h" />
</cache>
Defines a cache called 'mycache', storing files in the '/path/to/mycache' directory using '[module]/ivy-[revision].xml' as pattern to store Ivy files and '[module]/[artifact]-[revision].[ext]' as pattern to store other artifacts.
The lock strategy used by this cache is the 'no-lock' strategy, which does not perform any locking.
The defaultTTL used is of 1s, meaning that by default dynamic revision result will be stored and used for one second. TTL rules then define that all 'latest.integration' revisions will be stored and used for 200ms, while other dynamic revisions from org1 org2 and org3 modules will be stored respectively for 10 minutes 20 seconds; 5 hours; and 2 days and 12 hours.
ttl
Tag: ttl
Since 2.0 Defines a TTL (Time To Live) rule for resolved revision caching.
When Ivy resolves a dynamic version constraint (like latest.integration or a version range), it can store the result of the resolution (like latest.integration=1.5.1) for a given time, called TTL. It means that Ivy will reuse this dynamic revision resolution result without accessing the repositories for the duration of the TTL, unless running resolve in refresh mode.
This tag let you define a rule to define a TTL specific to a set of dynamic revision, based on the whole module revision information (organization, module name, revision, ...). The revision considered in the rule is the revision before the resolution (for instance 'latest.integration') and not the resolved revision (for instance '1.5.1').
The rules are evaluated in order, the first matching rule being used to define the TTL. If no rule matches, the cache defaultTTL will be used.
The format used to specify the TTL is of the form:
XXd XXh XXm XXs XXXms
Where 'd' stands for days, 'h' for hours, 'm' for minutes, 's' for seconds and 'ms' for milliseconds. Any part of the specification can be omitted, so '12d', '2h 5m' and '1d 5ms' are all valid.
The TTL duration can also be set to 'eternal', in which case once resolved the revision is always use, except when resolving in refresh mode.
Using a 0ms TTL disable resolved revision caching for the given rule.
Attributes
Attribute Description Required organisation the organisation to match to apply the rule.
No, defaults to * module the module's name to match to apply the rule.
No, defaults to * revision the module's revision to match to apply the rule. Note that the version is not resolved when evaluating the rule ('latest.integration' for instance).
No, defaults to * any extra attribute an extra attribute to match to apply the rule.
No, defaults to * matcher the matcher to use to match the modules to which the resolver should be applied
No, defaults to exact duration the TTL to apply (see above for format)
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 included in Ivy by default 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's drawback is that it can be slow when dealing with remote repositories. If you use ivyrep,
for example, Ivy has to ask the http server for the date of each ivy file before knowing which is the latest.
- latest-revision
compares the revisions as strings, using an algorithm close to the one used in php's version_compare function.
This algorithm takes into account the 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 strings, 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 remove 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 both a maven2 repository and an ivyrep, 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, their organisation is same as 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] and that it isn't available.
...
Ivy's answer to this issue is called namespaces. In short, you can attach 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, so is the best place to see an example 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 can be referenced by one of the resolvers.
An overview of Namespaces is given in the namespaces documentation.
A namespace mainly consists of a list of rules, each rule defining a translation between a system namespace and the defined namespace, and vice versa.
There are two main possibilities for using these rules. By default, a namespace iterates through the rules, and when it finds one that translates the given name, it returns the translated name. But the namespace can be configured to 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 the namespace doc for details.
Child elements
Element Description Cardinality fromsystem defines the translation to apply from the system namespace to the defined namespace
1 tosystem defines the translation to apply from the defined namespace to the 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 another. This definition is very similar to the macrodef feature of ant for defining macro tasks. since 1.3
This task eases the process of creating a new dependency resolver, because it avoids writing java code.
It is generally used in combination with the include feature to help reuse a macro in multiple settings files.
A macro is defined by declaring an existing resolver within it. Then you can use attributes to pass parameters to the newly defined resolver type. Attributes are defined with a name, and optionally a default value, and are used using the following syntax:
@{attributename}
Resolvers names
Since you can use the same macro several times it can define several resolvers (in a chain for instance), the resolver names need to be chosen carefully to avoid name conflicts (each resolver must have a unique name).
Here is how Ivy deals with the names of the resolvers defined in a macro:
- if there is no name attribute on a resolver in the macrodef, then Ivy will use the name given when using the macro. This is what usually should be done for the main resolver defined in the macro
- if there is a name attribute on a resolver in the macrodef, but this name doesn't contain a @{name} inside, then Ivy will use the provided name prefixed with the name of the macro separated by a dash
- if there is a name attribute on a resolver in the macrodef, and this name contains @{name} somewhere, then Ivy will use this name, and replace @{name} with the name provided when using the macro.
Example:
<ivysettings>
<macrodef name="mymacro">
<chain>
<ibiblio name="ex1" />
<ibiblio name="ex2.@{name}" m2compatible="true" />
</chain>
</macrodef>
<resolvers>
<mymacro name="default" />
<mymacro name="other" />
</resolvers>
</ivysettings>
This is equivalent to:
<ivysettings>
<resolvers>
<chain name="default">
<ibiblio name="default-ex1" />
<ibiblio name="ex2.default" m2compatible="true" />
</chain>
<chain name="other">
<ibiblio name="other-ex1" />
<ibiblio name="ex2.other" m2compatible="true" />
</chain>
</resolvers>
</ivysettings>
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:
<ivysettings>
<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>
</ivysettings>
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 already been defined and NOT if it is defined later in the ivysettings 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 that handle most common needs.
If you don't find the one you want here, you can also check if someone has contributed it on the links page, or even write your own.
There are basically two types of resolvers in Ivy: composite and standard. 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. Packager Standard Finds ivy files and packaging instructions via URLs, then creates artifacts by following the instructions. 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 features and attributes
All resolvers of the same type share some common features and attributes detailed here.
Features
validation
All standard resolvers support several options for validation.
The validate attribute is used to configure if ivy files should be checked against the ivy file xml schema.
The checkconsistency attribute allows you to enable or disable consistency checking between what is expected by Ivy when it finds a module descriptor, and what the module descriptor actually contains.
The descriptor attribute lets you define if module descriptors are mandatory or optional.
The checksums attribute is used to define the list of checksums files to use to check if the content of downloaded files has not been corrupted (eg during transfer).
force
Any standard resolver can be used in force mode, which is used mainly to handle local development builds. In force mode, the resolver attempts to find a dependency whatever the requested revision is (internally it replace the requested revision by 'latest.integration'), and if it finds one, it forces this revision to be returned, even when used in a chain with returnFirst=false.
By using such a resolver at the beginning of a chain, you can be sure that Ivy will pick up whatever module is available in this resolver (usually a private local build) instead of the real requested revision. This allows to handle use case like a developer working on modules A and C, where A -> B -> C, and pick up the local build for C without having to publish a local version of B.
since 2.0
Attributes
Attribute Description Required Composite Standard name the name which identifies the resolver
Yes
Yes
Yes
validate indicates if resolved ivy files should be validated against ivy xsd
No, defaults to call setting
Yes
Yes
force Indicates if this resolver should be used in force mode (see above). since 2.0
No, defaults to false
No
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. See cache and change management for details.
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. See cache and change management for details.
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 belons 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
descriptor 'optional' if a module descriptor (usually an ivy file) is optional for this resolver, 'required' to refuse modules without module descriptor since 2.0
No, defaults to 'optional'
No (except dual)
Yes
allownomd DEPRECATED. Use descriptor="required | optional" instead.
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
cache The name of the cache manager to use.
No, defaults to the value of the default attribute of caches
No
Yes
signer The name of the detached signature generator to use when publishing artifacts. (since 2.2)
No, by default published artifacts will not get signed by Ivy.
No
Yes
Examples
<resolvers>
<filesystem name="1" cache="cache-1">
<ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${ivy.settings.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 combines the filesystem resolver with an ivyrep resolver, and second which combines 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). Resolver 1 will use a cache named 'cache-1' which should have been defined under the caches element.
IvyRep Resolver
Tag ivyrep Handle latest yes, at least if the repository server is apache based Handle publish no
This resolver usually uses an URL based repository usually similar in structure to ivyrep to find ivy files, and ibiblio to find artifacts.
It can also be configured to use other similar repositories.
Since ivyrep is not maintained anymore, the ivyroot attribute is mandatory, and the use of this resolver is not recommended (we recommend using url resolver as replacement in most cases).
Attributes
This resolver shares the common attributes of standard resolvers.
Attribute Description Required ivyroot the root of the ivy repository.
Yes, but may be provided through ${ivy.ivyrep.default.ivy.root} since 2.0 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" 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.
since 1.3 Using the m2compatible attribute, you can benefit from maven 2 repository compatibility (convert dots in organisation into slashes, search for poms, use transitive dependencies of poms). This setting also affects the default place where the resolver looks 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 a url resolver configured like this:
<url name="test" m2compatible="true">
<artifact pattern="http://repo1.maven.org/maven2/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
</url>
since 2.0 When used in m2compatible mode with the default pattern, this resolver uses maven-metadata.xml files (if present) to list the revisions available on the repository. This is especially useful when using a maven specific proxy, which does not serve directory listing. This can be disabled by using the useMavenMetadata flag.
Limitation: in m2compatible mode, this resolver is not able list available organizations. It means some features like repreport are not available.
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 useMavenMetadata True if this resolver should use maven-metadata.xml files to list available revisions, false to use directory listing since 2.0
No, defaults to true
Examples
<ibiblio name="maven2" m2compatible="true"/>
Defines a resolver called "maven2" using the maven 2 public repository to find module metadata (using maven 2 poms) and artifacts.
<ibiblio name="maven" m2compatible="true" usepoms="false"/>
Same as above, but doesn't use poms, only artifacts.
Packager resolver
Tag packager Handle latest yes with http urls (and apache server) and with file urls, no with other urls Handle publish no
Since 2.0.
This resolver accesses ivy files and "packaging instructions" from an online "packager" repository. "Packager" repositories contain no actual artifacts. To get the artifacts, the packaging instructions are downloaded from the repository and executed locally. These instructions specify additional resource(s) to download and how to create the artifacts from them, for example, by downloading a project's original distribution archive directly from their web site and extracting the desired artifacts.
Packager repositories allow the creation of Ivy repositories that require neither the participation of any of the modules' creators nor setting up a huge mirror site. One such repository on the web is Ivy RoundUp. Of course, private packager repositories are feasible as well.
The Packager resolver supports a "resource cache", where downloaded archives can be stored to avoid duplicate downloads. This cache is entirely separate from the normal Ivy cache: it is "private" to the Packager resolver, and it stores unmodified original software archives, not Ivy artifacts. See the resourceCache attribute below for details.
The packaging instructions are contained in "packager.xml" in a simple XML format. At resolve time this file gets converted into a "build.xml" file via XSLT and then executed using ant. Therefore, ant must be available as an executable on the platform. The ant task executes in a separate ant project and so is not affected by properties, etc. that may be set in any existing ant environment in which Ivy is running. However, Ivy will define a few properties for convenience; see the "Properties" listed below.
For security reasons, the XSLT transform ensures that (a) all downloaded archives have verified SHA1 checksums (including cached resources); and (b) only a very limited set of ant tasks can be performed during the artifact "build" phase; currently these include move, copy, mkdir, zip, unzip, tar, and untar (this restriction may be overridden however; see below).
The Packager resolver is based on the URL resolver and is configured similarly, except the artifact child tags specify where to find the packager.xml files, rather than the artifacts themselves.
Because the packaging process is relatively slow, it is important to use Ivy's caching support to avoid repeated execution of the packaging instructions.
Attributes
This resolver shares the common attributes of standard resolvers, plus the following:
Attribute Description Required
buildRoot
Defines the root of the temporary build directory hierarchy
Yes
resourceCache
Directory where downloaded resources should be cached
No; defaults to none
resourceURL
Ivy pattern that specifies a base URL to use for downloading all resources; overrides the URLs in the packaging instructions
No; defaults to none
restricted
True if this resolver should only allow "safe" ant tasks in the packaging instructions. Warning: setting restricted to false creates a security problem due to ant tasks like delete, exec, etc. Do not use this setting when your configuration points to an untrusted repository.
No; defaults to true
verbose
True to run ant with the -verbose flag
No; defaults to false
quiet
True to run ant with the -quiet flag
No; defaults to false
validate
True if this resolver should validate (via XSD) the downloaded XML packaging instructions
No; defaults to true
preserveBuildDirectories
True if this resolver should not delete the temporary build directories in which the ant tasks are executed (for debugging purposes)
No; defaults to false
Setting a resourceURL will cause the resolver to override the URLs for resources specified by the packaging instructions. Instead, all resources will be downloaded from an URL constructed by first resolving the resourceURL pattern into a base URL, and then resolving the resource filename relative to that base URL. In other words, the resourceURL pattern specifies the URL "directory", so it should always end in a forward slash.
If a resourceURL download fails, the resolver will fall back to the original URL from the packaging instructions.
Configure a resourceURL in situations where you don't want to rely on (or wait for) the web sites configured in the packaging instructions, and have access to a better (perhaps private) mirror site.
Child elements
Element Description Cardinality ivy Defines a pattern for ivy.xml files, using the pattern attribute
1..n artifact Defines a pattern for packager.xml files, using the pattern attribute
1..n
Examples
<packager name="ivyroundup"
buildRoot="${user.home}/.ivy2/packager/build"
resourceCache="${user.home}/.ivy2/packager/cache"
resourceURL="ftp://mirror.example.com/pub/resources/[organisation]/[module]/">
<ivy pattern="http://ivyroundup.googlecode.com/svn/trunk/repo/modules/[organisation]/[module]/[revision]/ivy.xml"/>
<artifact pattern="http://ivyroundup.googlecode.com/svn/trunk/repo/modules/[organisation]/[module]/[revision]/packager.xml"/>
</packager>
Defines a packager resolver which points to the Ivy RoundUp online repository. Builds will occur in a subdirectory of ${user.home}/.ivy2/packager/build downloaded resources will be cached in ${user.home}/.ivy2/packager/cache and the mirror site ftp://mirror.example.com/pub/resources/[organisation]/[module]/
will be tried first for all resources.
Packaging Instructions
The goal of the packaging instructions is to download the required archives, extract the artifacts, and put the artifacts into a subdirectory. Each artifact should be written to artifacts/[type]s/[artifact].[ext] when the ant build completes.
Below is an example of packaging instructions for TestNG 2.5:
<packager-module version="1.0">
<property name="name" value="${ivy.packager.module}"/>
<property name="version" value="${ivy.packager.revision}"/>
<property name="zipname" value="${name}-${version}"/>
<resource dest="archive" url="http://testng.org/${zipname}.zip" sha1="2ea19275dc17453306f8bb780fe6ef6e9af7756b">
<url href="http://mirror.example.com/archives/${zipname}.zip"/>
<include name="${zipname}/src/main/**/*"/>
<include name="${zipname}/src/jdk15/**/*"/>
<include name="${zipname}/javadocs/**/*"/>
<include name="${zipname}/*.jar"/>
</resource>
<build>
<!-- jar -->
<move file="archive/${zipname}/${zipname}-jdk14.jar" tofile="artifacts/jars/${name}-jdk14.jar"/>
<move file="archive/${zipname}/${zipname}-jdk15.jar" tofile="artifacts/jars/${name}-jdk15.jar"/>
<!-- source -->
<zip destfile="artifacts/sources/${name}.zip">
<fileset dir="archive/${zipname}/src/main">
<include name="**/*.java"/>
</fileset>
<fileset dir="archive/${zipname}/src/jdk15">
<include name="**/*.java"/>
</fileset>
</zip>
<!-- javadoc -->
<zip destfile="artifacts/javadocs/javadoc.zip">
<fileset dir="archive/${zipname}/javadocs"/>
</zip>
</build>
</packager-module>
Of course, packaging instructions must produce artifacts consistent with those listed in the associated ivy.xml file.
Build-time properties
This resolver ensures following ant properties are defined when it executes the ant build task.
Property Description
ivy.packager.organisation
Organization of the ivy module whose artifacts are being built
ivy.packager.module
Module of the ivy module whose artifacts are being built
ivy.packager.revision
Revision of the ivy module whose artifacts are being built
ivy.packager.branch
Branch of the ivy module whose artifacts are being built
ivy.packager.resourceCache
The configured resourceCache if any; otherwise not defined
ivy.packager.resourceURL
The resolved resourceURL pattern if any; otherwise not defined
Packager XML Elements
The packager.xml document element can contain the following child tags.
Element Description Cardinality
property
Set an ant property
0..n
resource
Define a resource to download and (optionally) unpack
0..n
m2resource
Define a Maven2 resource to download and (optionally) unpack
0..n
build
Specify ant tasks that ultimately result in each artifact being placed into artifacts/[type]s/[artifact].[ext]
0..1
Which ant tasks are allowed within the build tag is controlled by the restricted configuration attribute. When true (the default), only the following ant tasks are allowed: copy, jar, mkdir, move, tar, unjar, untar, unwar, unzip, war, and zip. When false, all ant tasks are allowed.
Warning: setting restricted to false creates a security problem due to ant tasks like delete, exec, etc. Do not use this setting when your configuration points to an untrusted repository.
Resource XML Elements
The resource XML tag supports the following attributes:
Attribute Description Required
url
Primary URL for the resource
Yes
sha1
SHA1 checksum of the resource
Yes
dest
Defines the name of the subdirectory into which the artifact should be unpacked
No; defaults to "archive"
tofile
Where to put the file directly; if present no extraction will be performed
No; if present, "dest" is ignored
filename
Name of the file to download
No; if not present, same as the last component of the URL
type
Type of archive: "zip", "jar", "war", "tar", "tgz", "tar.gz", "tar.bz2"
No; if not present, will be automatically determined from the filename suffix
The resource XML tag may contain child elements. An url tag with an href attribute specifies an alternate URL for the resource (see TestNG example above). Any other tags will be included as children of an automatically generated fileset tag.
Maven2 Resources
Special support is included for maven2 resources. For these resources, use the m2resource tag instead of the resource tag. Each m2resource tag specifies one or more artifacts that are downloaded from the Maven2 repository.
M2Resource XML Elements
The m2resource XML tag supports the following attributes:
Attribute Description Required
groupId
Maven group ID
No; defaults to ${ivy.packager.organisation}
artifactId
Maven artifact ID
No; defaults to ${ivy.packager.module}
version
Maven version
No; defaults to ${ivy.packager.revision}
repo
Maven repository URL
No; defaults to http://repo1.maven.org/maven2/
Each m2resource XML tag must have one or more artifact tags that define the artifacts to directly download. The URL for each artifact is constructed automatically based on the attributes in the m2resource and artifact tags.
M2Resource Artifact Attributes
The artifact children of m2resource tags support the following attributes:
Attribute Description Required
ext
Maven filename extension
No; defaults to "jar"
classifier
Maven classifier (e.g., "sources", "javadoc")
No; defaults to none
sha1
SHA1 checksum of the resource
Yes
dest
Defines the name of the subdirectory into which the artifact should be unpacked
Exactly one of "dest" or "tofile" must be supplied
tofile
Where to put the file; no extraction will be performed
type
Type of archive: "zip", "jar", "war", "tar", "tgz", "tar.gz", "tar.bz2"
No; if not present, will be automatically determined from the filename suffix
Below is an example of packaging instructions for the Apache Commons Email module. Note that no build tag is required because all of the maven2 artifacts are usable directly (i.e., without unpacking anything).
<packager-module version="1.0">
<m2resource>
<artifact tofile="artifacts/jars/${ivy.packager.module}.jar" sha1="a05c4de7bf2e0579ac0f21e16f3737ec6fa0ff98"/>
<artifact classifier="javadoc" tofile="artifacts/javadocs/javadoc.zip" sha1="8f09630f1600bcd0472a36fb2fa2d2a6f2836535"/>
<artifact classifier="sources" tofile="artifacts/sources/source.zip" sha1="15d67ca689a792ed8f29d0d21e2d0116fa117b7e"/>
</m2resource>
</packager-module>
File System resolver
Tag filesystem Handle latest yes Handle publish yes
This resolver uses the file system to resolve ivy files and artifacts. An advantage of this resolver is that it usually provides very good performance. Moreover, it is easy to setup using basic OS file sharing mechanisms.
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. These patterns must be absolute paths (since 2.0). You can indicate a list of patterns which will be checked one after the other.
since 1.3 Using the m2compatible attribute, this resolver will convert dots found in organisation into 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.
Limitation: in m2compatible mode, this resolver is not able list available organizations. It means some features like repreport are not available.
Atomic publish support
since 2.0 This resolver supports atomic publish, which is useful for environments with a lot of concurrent publish and resolve actions. The atomic publish relies on the atomicity of the rename operation in the underlying filesystem (which includes NTFS and POSIX based filesystems).
In this case the resolver starts by publishing the module according to the pattern, but where a '.part' suffix is appended to the revision. Then the publish is committed with a rename to the final location.
Limitations
Atomic publish is currently limited in several ways:
- you need to use a pattern for both the artifact and the ivy files which uses the revision as a directory. For instance "${repository.dir}/[module]/[revision]/[artifact].[ext]" works, "${repository.dir}/[module]/[artifact]-[revision].[ext]" doesn't
- both the artifact and ivy pattern should have the same prefix until the [revision] token.
- overwrite during publish is not supported
- you should not use revision names ending with '.part'
The transactional attribute can be used to configure the atomicity behavior:
- auto
use transaction if possible (according to limitation), otherwise don't
- true
always use transaction, fail the build if a limitation is not fulfilled
- false
don't use transaction at all
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 caches element for details.
No, defaults to true transactional true to force the use of transaction, false to prevent the use of transaction, auto to get transaction when possible since 2.0. See above for details.
No, defaults to auto
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 yes with http urls whose destination supports publishing (as of Ivy 2.0)
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.
Limitation: in m2compatible mode, this resolver is not able list available organizations. It means some features like repreport are not available.
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.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${ivy.settings.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.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${ivy.settings.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.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${ivy.settings.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
Tag dual Handle latest depends on sub resolvers Handle publish delegates 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.
Child elements
Element Description Cardinality any resolver two 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 widespread 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 widespread 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 publishPermissions A four digit string (e.g., 0644, see "man chmod", "man open") specifying the permissions of the published files. (since 2.0)
No, defaults to scp standard behaviour
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 built-in conflicts managers (which do not require anything in the configuration file):
- all
this conflicts manager resolve conflicts by selecting all revisions. Also called the NoConflictManager, it doesn't evict any modules.
- 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.
- latest-compatible
this conflict manager selects the latest version in the conflicts which can result in a compatible set of dependencies. This means that in the end, this conflict manager does not allow any conflicts (similar to the strict conflict manager), except that it follows a best effort strategy to try to find a set of compatible modules (according to the version constraints)
- 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 that the revision given in the direct dependency should be preferred 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"/>
compatible-cm The latest compatible conflict manager uses a latest strategy to select the latest revision among several ones. It takes 'latest' as an attribute to define which latest strategy should be used. Example:
<compatible-cm name="my-latest-compatible-conflict-manager" latest="my-latest-strategy"/>
regexp-cm This conflict manager is based on a regular expression and throws 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 expression is (.*)\.\d, because the matching group will match different strings (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 warn 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 a pattern for module organisation and name, and giving some settings for the set, like the name of the corresponding resolver to use.
If no rules match a given module, the default setting will be used.
Note: You can greatly improve the performance of dependency resolution by configuring multiple smaller resolvers instead of one large resolver (i.e. chain). For instance, if you have a local repository for your modules and a remote repository for third party libraries, it is a good idea to have two separate resolvers, one for all of 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, name, revision and any extra attribute identifying your modules. The rule matching is performed in order, and is using a pattern matcher. Hence you can use * to specify all, or simply avoid specifying the attribute.
The revision and extra attributes are only used for rules defining the resolver to use. For other settings, use only organisation and module name.
It also gives the specific setting to use for this module set.
For each module set, you can configure:
- the resolver to use
- the conflict manager to use
- the default branch to use
- the resolve mode to use
Attributes
Attribute Description Required organisation the organisation to match to apply the rule.
No, defaults to * name the module's name to match to apply the rule.
No, defaults to * revision the module's revision to match to apply the rule. Note that the version may not be resolved yet (be latest.integration for instance), so be very careful when using this attribute. since 2.0
No, defaults to * any extra attribute an extra attribute to match to apply the rule. since 2.0
No, defaults to * matcher the matcher to use to match the modules to which the resolver should be applied since 1.3
No, defaults to exactOrRegexp 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 resolveMode the resolve mode to use. since 2.0
No
Examples
<modules>
<module organisation="apache" name="*" resolver="myprojectsresolver"/>
</modules>
Uses myprojectresolver for all modules from apache.
<modules>
<module organisation="apache" name="commons-*" matcher="glob" resolver="myapachecommonsresolver"/>
</modules>
Uses myapachecommonsresolver for all modules beginning with 'commons-' from 'apache'.
<modules>
<module organisation="apache" name="commons-[a-z]+" myextra="val.*" matcher="regexp" resolver="myapachecommonsresolver"/>
</modules>
Uses myapachecommonsresolver for all modules from apache beginning with 'commons-' followed by any number of alphabetic lowercase characters, and with the extra attribute 'myextra' having a value beginning with 'val.'.
<modules>
<module organisation="apache" name="ivy*" matcher="glob" conflict-manager="latest-time"/>
</modules>
Uses latest-time conflict manager for all modules from apache whose name begins with 'ivy'.
<modules>
<module organisation="apache" name="ivy*" matcher="glob" branch="fix-103"/>
</modules>
Uses 'fix-103' as default branch for all modules from apache whose 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 build 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
signers
Tag: signers
since 2.2
Defines a list of detached signature generators usable in ivy. Each generator is identified by its name, given as an attribute.
The child tags used to configure the signature generator must be equal to the name of a signature generator type (either built-in or added with the typedef tag).
Ivy supports the following signature generator out of the box:
- pgp
generates an OpenPGP compatible ASCII armored detached signature.
Child elements
Element Description Cardinality any signature generator adds a signature generator to the list of registered generators
1..n
Built-in Generators
PGP
This generator is capable of generating an OpenPGP compatible ASCII armored detached signature.
Remark: This generator uses the BouncyCastle OpenPGP library. Before this generator can be used, these libraries must be available on Ivy's classpath.
Attribute Description Required name The name of the signature generator.
Yes
secring The location of the secret keyring.
No, defaults to ${user.home}/.gnupg/secring.gpg
keyId The identifier of the key to use. The keyword 'auto' can be used to indicate a key will be selected automatically.
No, defaults to 'auto'.
password The password of the private key.
Yes
Examples
<signers>
<pgp name="mypgp" password="my-password" />
</signers>
Defines a detached signature generator with name 'mypgp' which uses the secret key ring on the default location and automatically selects a private key.
<signers>
<pgp name="mypgp" password="my-password" keyId="123ABC45"/>
</signers>
Same as before, but this time the key '123ABC45' is used to generate the detached signature.
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 ivysettings 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.<status> 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 3 type of triggers out of the box:
- ant-call
calls a target in the same build as the original one whenever a particular event occurs.
- ant-build
calls an ant build which may be in another ant build script.
- log
echo a message, usually in a file
If you want to use a different trigger, you can implement your own.
The following events are available in Ivy:
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 at the beginning of the resolve process, before module dependencies and transitive dependencies are resolved.
pre-resolve-dependency
- organisation
the organisation of the dependency resolved
- module
the name of the dependency resolved
- req-revision
the requested revision for the dependency since 2.0 (provided for consistency with post-resolve-dependency)
- req-revision-default
the default requested revision constraint for the dependency since 2.0
- req-revision-dynamic
the requested revision dynamic constraint for the dependency since 2.0
- revision
the requested revision for the dependency
- resolver
the name of the resolver used to resolve the dependency
Fired before each dependency is resolved. In this case resolved means resolving the actual revision if the requested revision is a version constraint and not a static version, and downloading all necessary metadata information.
post-resolve-dependency
- organisation
the organisation of the dependency resolved
- module
the name of the dependency resolved
- req-revision
the requested revision for the dependency since 2.0
- req-revision-default
the default requested revision constraint for the dependency since 2.0
- req-revision-dynamic
the requested revision dynamic constraint for the dependency since 2.0
- revision
the revision of the dependency resolved, or the requested revision if the resolution was not successful
- resolved
true if the resolution was successful, false otherwise
- duration
the time elapsed to resolve the dependency (in ms) since 2.0
- resolver
the name of the resolver used to resolve the dependency
- any extra attribute
all extra attributes found on the info tag of the resolved dependency are available since 2.0
Fired after each dependency is resolved
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
- resolve-id
the identifier of the resolution process since 2.0
- nb-dependencies
total number of dependencies, including transitive and evicted ones since 2.0
- nb-artifacts
total number of artifacts resolved, excluding metadata artifacts since 2.0
- resolve-duration
the time (in ms) elapsed to resolve dependencies, before dowloading artifacts since 2.0
- download-duration
the time (in ms) elapsed to download all artifacts, excluding metadata artifacts downloaded during the first phase of the resolution process since 2.0
- download-size
the total size (in bytes) of all downloaded artifacts, excluding metadata artifacts. Only artifacts actually downloaded (not in cache or used from their original location) are considered since 2.0
Fired at the end of the resolve process, when all module dependencies have 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
- metadata
true if the artifact to be downloaded is a metadata artifact, false for published artifacts since 2.0
- 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
- metadata
true if the downloaded artifact is a metadata artifact, false for published artifacts since 2.0
- 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
- duration
the time elapsed to download the artifact (in ms) since 2.0
- file
the file to which it has been downloaded
Fired after an artifact has been downloaded from a repository to the cache
pre-retrieve
since 2.0
- organisation
the organisation of the module for which the dependencies will be retrieved
- module
the name of the module for which the dependencies will be retrieved
- revision
the revision of the module for which the dependencies will be retrieved
- conf
comma separated list of configurations which will be retrieved
- symlink
true if Ivy will use symbolic links instead of copies on supported platforms, false otherwise
- sync
true if the retrieve process will be performed in sync mode, false otherwise
Fired at the beginning of the retrieve process.
post-retrieve
since 2.0
- organisation
the organisation of the module for which the dependencies have been retrieved
- module
the name of the module for which the dependencies will be retrieved
- revision
the revision of the module for which the dependencies have been retrieved
- conf
comma separated list of configurations which have been retrieved
- symlink
true if Ivy used symbolic links instead of copies on supported platforms, false otherwise
- sync
true if the retrieve process has been performed in sync mode, false otherwise
- duration
the time elapsed in ms during the retrieve process
- size
the total size of artifacts which have actually been copied (or symlinked)
- nbCopied
the number of artifacts copied or symlinked
- nbUptodate
the number of artifacts which were already present and up to date at the destination location
Fired at the end of the retrieve process.
pre-retrieve-artifact
since 2.1
- organisation
the organisation of the artifact which is about to be retrieved
- module
the name of the module of the artifact which is about to be retrieved
- revision
the revision of the the artifact which is about to be retrieved
- artifact
the name of the the artifact which is about to be retrieved
- type
the type of the the artifact which is about to be retrieved
- ext
the extension of the the artifact which is about to be retrieved
- metadata
true if the retrieved artifact is a metadata artifact, false for published artifacts
- size
the size in bytes of the retrieved artifact
- from
the absolute path from which it will be retrieved (usually a location in cache)
- to
the absolute path to which it will be retrieved
Fired before an artifact is retrieved from the cache to a local location
post-retrieve-artifact
since 2.1
- organisation
the organisation of the artifact which has just been retrieved
- module
the name of the module of the artifact which has just been retrieved
- revision
the revision of the the artifact which has just been retrieved
- artifact
the name of the the artifact which has just been retrieved
- type
the type of the the artifact which has just been retrieved
- ext
the extension of the the artifact which has just been retrieved
- metadata
true if the retrieved artifact is a metadata artifact, false for published artifacts
- size
the size in bytes of the retrieved artifact
- from
the absolute path from which it has just been retrieved (usually a location in cache)
- to
the absolute path to which it has just been retrieved
Fired after an artifact is retrieved from the cache to a local location
pre-publish-artifact
since 2.0
- organisation
the organisation of the artifact which is about to be published
- module
the name of the module of the artifact which is about to be published
- revision
the revision of the the artifact which is about to be published
- artifact
the name of the the artifact which is about to be published
- type
the type of the the artifact which is about to be published
- ext
the extension of the the artifact which is about to be published
- resolver
the name of the resolver into which the artifact is about to be published
- file
the absolute path of the source file for the artifact
- overwrite
"true" if the new data will overwrite existing artifacts, "false" otherwise
Fired before an artifact is published into a repository
post-publish-artifact
since 2.0
- organisation
the organisation of the artifact that was published
- module
the name of the module of the artifact that was published
- revision
the revision of the the artifact that was published
- artifact
the name of the the artifact that was published
- type
the type of the the artifact that was published
- ext
the extension of the the artifact that was published
- resolver
the name of the resolver into which the artifact was published
- file
the absolute path of the source file for the artifact
- overwrite
"true" if the new data overwrote existing artifacts, "false" otherwise
- status
"successful" if the artifact published successfully; "failed" if the artifact failed to publish, or if the status is unknown
Fired after an artifact is published into a repository. Note that this event is fired whether or not the publication succeeded. The "status" property can be checked to verify success.
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 3 built-in triggers:
Name Description ant-build Triggers an ant build. Note that by default the ant build is triggered only once per build file, the property onlyonce can be set to false to change this. ant-call Calls a target in the current ant build. log Logs a message on the console or in a log file.
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.settings.dir}/[module]/build.xml" target="publish"
event="pre-resolve-dependency" filter="revision=latest.integration"/>
</triggers>
Triggers an ant build of the ant file ${ivy.settings.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.
Note that by default the ant build is triggered only once per build file. See below to see how to trigger the build more than once.
<triggers>
<ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish"
event="pre-resolve-dependency" filter="revision=latest.integration"
onlyonce="false" />
</triggers>
Same as before, but this time the builds will be triggered as many time as the dependency is resolved, instead of only once.
<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>
<triggers>
<log file="ivy.log"
message='downloaded "${origin}" to "${file}" (${duration}ms - ${size}B)'
event="post-download-artifact" filter="status=successful"/>
</triggers>
Logs any successful artifact download, with information on the source and destination, and details on download size and duration.
The file attribute is optional, the log trigger will output messages to console if it isn't provided.
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 dependency version constraint matches a dependency version.
Child elements
Element Description Cardinality any version matcher adds a version matcher to the list of available ones
0..n
Built-in Version Matchers
Exact Revesion Matcher
A matcher that matches a dependency revision id to the module revision id using simple string equality.
Sub Revision Matcher
A matcher that matches all revisions starting with a specific prefix. The syntax is: [prefix]+
Revision Matches 1.0.+ all revisions starting with '1.0.', like 1.0.1, 1.0.5, 1.0.a 1.1+ all revisions starting with '1.1', like 1.1, 1.1.5, but also 1.10, 1.11
Latest (Status) Matcher
A matcher that matches versions based on their status. The predefined statuses in Ivy are 'release', 'milestone' and 'integration'. It's possible to define your own statuses, see statuses for more details.
Revision Matches latest.integration all versions latest.milestone all modules having at least 'milestone' as status latest.release all modules having at least 'release' as status latest.[any status] all modules having at least the specified status
Version Range Matcher
Range types are exhaustively listed by example in the table below.
Revision Matches [1.0,2.0] all versions greater or equal to 1.0 and lower or equal to 2.0 [1.0,2.0[ all versions greater or equal to 1.0 and lower than 2.0 ]1.0,2.0] all versions greater than 1.0 and lower or equal to 2.0
]1.0,2.0[ all versions greater than 1.0 and lower than 2.0 [1.0,) all versions greater or equal to 1.0 ]1.0,) all versions greater than 1.0 (,2.0] all versions lower or equal to 2.0 (,2.0[ all versions lower than 2.0
Version Pattern Matcher
The version pattern matcher allows for more flexibility in pattern matching at the cost of adding a matcher declaration in Ivy settings. A simple example is given below.
Settings.xml
<pattern-vm>
<match revision="foo" pattern="${major}\.${minor}\.\d+" args="major, minor" matcher="regexp" />
</pattern-vm>
Ivy.xml
<dependency org="acme" name="tool" rev="foo(1, 3)" />
The version pattern matcher may contain more than one match element. The matcher will attempt to match a dependency revision against each match in sequence, checking the revision tag (e.g. foo(..)) and then the pattern.
Matcher types may be one of "regexp", "exact", "glob", or "exactOrRegexp". Glob pattern matching requires Apache ORO 2.0.8 or higher to be on the classpath.
Ivy Files
Ivy use is entirely based on module descriptors known as "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="2.0">
<info organisation="myorg"
module="mymodule"
/>
</ivy-module>
If you want to see a sample module descriptor 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="2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation=
"http://ant.apache.org/ivy/schemas/ivy.xsd">
<info organisation="myorg"
module="mymodule"
/>
</ivy-module>
Dynamic and resolved ivy files
A module descriptor (ivy file) is needed both before and after the publication of each revision of the module. Depending on the case, a module descriptor can be either dynamic or resolved:
Dynamic descriptor for module development
During the module development time, between publications, the descriptor helps in managing all the possibly changing dependencies of the module. For that purpose, development time ivy files can declare dynamic dependencies to allow for a greater flexibility of use. Dynamic revision references like "latest.integration" or "1.0.+" are possible and may resolve to different artifacts at different times. Variables can be used for even more flexibility. Development time ivy files are hence called "dynamic", because they can produce different results over time. The dynamic ivy files are normally considered source files and kept with them (under SCM control).
Resolved descriptors for publishing
At each publication, another kind of a module descriptor is needed to document the dependencies of the particular published revision of the module. For that purpose, the descriptor usually needs to be fixed as its dependencies should no longer change. In doing so, the published module revision gets fixed, explicitly resolved dependencies. No variables are allowed either. Such publication-friendly, static ivy files are called "resolved", because they should always produce the same results. The resolved ivy files are comparable to published artifacts and are kept with them in a repository.
Resolved ivy files are generated from their original dynamic ivy files via the deliver task.
Note that although it is technically possible to publish module revisions with dynamic ivy files, it is not a generally recommended practice.
Hierarchical Index
ivy-module
info
license
ivyauthor
repository
description
configurations
conf
publications
artifact
conf
dependencies
dependency
conf
mapped
artifact
conf
include
conf
exclude
conf
exclude
override
conflict
conflicts
manager
ivy-module
Tag: ivy-module
The root tag of any ivy file (module descriptor).
Attributes
Attribute Description Required version the version of the ivy file specification - should be '2.0' 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 identification and basic information about the module this ivy file describes.
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 setting, 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 extends identifies a parent Ivy file from which this descriptor inherits content
0..n 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
After the description, you can also place your own tags in your own namespace. This allow to provide some custom information about the module.
extends
Tag: extends Parent: info
since 2.2 Identifies an optional parent descriptor for this module. For complicated projects composed of many modules that have common configurations or dependencies, inheritance allows modules to share this information. Which parts of the parent descriptor are inherited can be controlled with the extendType attribute. Supported extendType values are:
Value Description info Attributes of the info element are inherited from the parent. When an attribute appears in both child and parent, the child value is used. description The content of the info/description element is inherited from the parent. configurations Configurations defined in the parent descriptor are added to any configurations defined in the child descriptor. dependencies Dependencies defined in the parent descriptor are added to any dependencies defined in the child descriptor. all info, description, configurations, and dependencies from the parent descriptor are merged into the child descriptor.
Attributes
Attribute Description Required organisation the organisation of the parent module
Yes module the name of the parent module
Yes revision the revision of the parent module. Can be fixed, a dynamic value, or range of revisions; see dependency for information on specifying revisions.
Yes extendType which part(s) of the parent descriptor are inherited. Valid values are info, description,
configurations, dependencies, and all.
No, default is all location A local filesystem path that should be searched for the parent descriptor. If the parent descriptor cannot be found at this location, it will be located using dependency resolvers like any normal dependency.
This attribute is intended for development use. For example, child module descriptors appear in a source control directory with the parent module descriptor at a higher level. location will then contain the relative path to the parent descriptor for use during development builds.
No, as long as the parent descriptor exists in an Ivy resolver
license
Tag: license Parent: info
Gives information about a license of the described module.
Attributes
Attribute Description Required name the name of the license. Try to respect spelling when using a classical license.
Yes url an 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
Attribute Description Required name the name of the author, as a person or a company.
Yes url an 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
Attribute Description Required name the name of the repository. Try to respect spelling for common repositories (ibiblio, ivyrep, ...)
Yes url an url pointing to the repository.
Yes pattern an ivy pattern to find modules on this repository
No, but it's recommended to indicate it. ivys true if ivy file can be found on this repository
No, defaults to false. artifacts true 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
Attribute Description Required homepage the url of the homepage of the module
No, but it's recommended to indicate it.
configurations
Tag: configurations Parent: ivy-module
A container for configuration elements. If this container is not present, it is assumed that the module has one public configuration called 'default'.
since 2.2 You can define the default conf on this container by specifying the defaultconf attribute. This attribute defines the conf mapping to use when no conf mapping is specified for a dependency in this ivy file.
since 1.3 You can define a default conf mapping on this container by specifying the defaultconfmapping attribute.
This attribute modifies 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.
In order to maintain backwards compatibility with Ivy 2.1.0 and earlier, the defaultconfmapping also provides one additional function. If no defaultconf is specified (on either the configurations tag or the dependencies tag), the defaultconfmapping becomes the default configuration for dependencies in this ivy file when no configuration is specified. In other words, in addition to altering the interpretation of individual configurations with no mapping, defaultconfmapping also performs exactly like defaultconf in the absence of a definition for defaultconf.
If several defaultconfmapping or defaultconf attributes are defined (in the configurations tag, one or several in an included configurations file, and/or in the dependency tag, then it's only the last definition of each property which is taken into account. The others will have no effect at all.
See examples below to clarify the behavior of these two attributes together.
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.
Attributes
Attribute Description Required defaultconf the default conf to use in this ivy file since 2.2 No, defaults to no default conf 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
Configuration mappings details
When Ivy parses your Ivy file, it will create (internally) modify the configuration mapping of your dependencies.
For instance, say you have:
<configurations defaultconfmapping="conf1->other1;conf2->other2">
<conf name="conf1" />
<conf name="conf2" extends="conf1" />
</configurations>
<dependencies>
<dependency name="other-module" conf="conf1" />
</dependencies>
When Ivy parses this file, it will construct the following dependency (in-memory only):
<dependency name="other-module" conf="conf1->other1" />
So, if you now resolve the conf2 configuration, you will only get the other1 dependencies of your other-module.
But when you set confmappingoverride to true, Ivy will construct the following dependency in memory:
<dependency name="other-module" conf="conf1->other1;conf2->other2" />
As you can see, the defaultmappings of the extending configurations are also added (although you didn't explicitly defined them)
When you now resolve the conf2 configuration, you'll get the other2 dependencies of your other-module.
Examples involving defaultconf and defaultconfmapping
The table below indicates how Ivy interprets the conf attribute according to how defaultconfmapping and defaultconf are set:defaultconf defaultconfmapping conf ivy interpretation *->*
runtime runtime->runtime
test test->test
runtime
runtime->runtime
runtime
runtime->*;test->default
runtime->* runtime
runtime->*;test->default
test test->default runtime->*;test->default
runtime->*;test->default
runtime->*;test->default
runtime runtime->*
runtime->*;test->default
test test->default
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 module 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.
Attributes
Attribute Description Required defaultconf comma separated list of public configurations in which artifacts are published by default (when no specific configurations are set on the artifact element).
'*' wildcard can be used to designate all public configurations of this module. since 2.0
No, defaults to '*'
Child elements
Element Description Cardinality artifact declares 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 two are equivalent, it is only a matter of preference. However, do not mix both for one artifact.
since 1.4 The artifact element has 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.
since 1.4 This tag supports extra attributes.
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 defaultconf attribute value on parent publications element. 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
Attribute Description Required name the 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 provides for two similar behaviors. An overview is given here. (See configurations doc page for more details about these behaviors).
since 1.1defaultconf
Defines the 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.
since 1.3defaultconfmapping
Influences the way that a conf mapping with no mapped conf is interpreted.
In Ivy 2.1.0 and earlier, if both defaultconf and defaultconfmapping are defined, it's the defaultconfmapping that is used. Since Ivy 2.2.0, these attributes can be used together.
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 file. since 1.3
No, defaults to no default conf mapping
Child elements
Element Description Cardinality dependency declares a dependency for this module
0..n exclude excludes artifacts, modules or whole organizations from the set of dependencies of this module since 2.0
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] since 1.4
selects the latest revision of the dependency module with at least the specified status.
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 since 1.4
mathematical notation for ranges can be used to match a range of version.
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.
Revision constraint
since 2.0 The dependency tag supports two revision attributes: rev, corresponding to the default required dependency revision, and revConstraint, corresponding to a dynamic revision constraint applied on this dependency.
Depending on the resolve mode used, the actual revision used during dependency resolution may vary. These revisions usually differ only for modules published in a repository. When deliver is used, dynamic version constraints are replaced by a stic version constraint, to help build reproducibility. However, the information of the original version constraint is not lost, but rather put in the revConstraint attribute. This both ensure better metadata in the repository while still allowing easier build reproducibility.
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.
The examples on the dependency on the configurations page explain how ivy interprets the conf attribute according to how defaultconfmapping and defaultconf is set.
- 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).
If you don't understand really how this works, do not use it :-)
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 2.1 It is also possible to define dependencies on configurations intersection. A configuration intersection is defined using a '+' sign to separate the configuration (eg 'A+B' means the intersection of configuration 'A' and 'B'). In that case only artifacts and dependencies defined in both configurations in the dependency will be part of the master configuration defining the dependency on the configuration intersection.
Configuration intersections can also be used when specifying the confs to resolve.
Moreover, the mapping '*->@' is handled as a specific case with configuration intersections: it maps also the intersections. So if one resolve conf A+B in a module which defines a dependency with mapping *->@, the mapping *->@ is interpreted as A+B->A+B so the intersection of A and B will be resolved in the dependency.
since 2.1 you can refer to a group of configurations sharing the same value for an attribute as left side part of the dependency mapping.
The syntax is
*[att=value]
where att is the name of the attribute shared by the configurations of the group, and value
For instance, if you have:
<configurations>
<conf name="red" e:axis="color" />
<conf name="blue" e:axis="color" />
<conf name="windows" e:axis="platform" />
<conf name="linux" e:axis="platform"/>
</configurations>
Then you can do:
<dependency org="acme" name="foo" rev="2.0" conf="*[axis=platform]->default"/>
To map the windows and linux configurations (the one which have the attribute axis equal to platform) to the default configuration of foo.
since 1.4 you can add simple conditions in the right side of 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 setting for the dependency. rev the revision of the dependency. See above for details.
Yes revConstraint the dynamic revision constraint originally used for this dependency. See above for details.
No, defaults to the value of rev 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). See cache and change management for details.
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
Attribute Description Required name the name of the master configuration to map.
'*' wildcard can be used to designate all configurations of this module
Yes mapped a 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
Element Description Cardinality mapped map dependency configurations for this master configuration
0..n
mapped
Tag: mapped Parent: conf
Describes a mapped dependency configuration for a master configuration.
Attributes
Attribute Description Required name the 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 the url if it cannot be found at the standard location in the repository.
since 1.4 This tag supports extra attributes.
since 2.0 This feature can also be used for modules having their own module descriptor, but which doesn't declare an artifact you know that is published. Note that in this case artifacts declared to be published by the dependency will be ignored, so do not forget to include all artifacts you want.
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.
<dependency org="foo" name="bar" rev="1.0">
<include name="*"/>
<artifact name="baz" type="source" ext="jar"/>
</dependency>
Declares a dependency on module bar for which all artifacts declared will be used (thanks to the include tag) plus an artifact baz of type source and ext jar (which is not declared in module bar module descriptor).
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 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>
since 2.0 A module wide exclude can also be used to exclude dependencies for the whole module (and not only in the context of one dependency as it is the case here).
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 an expression matching this name (see matcher attribute below)
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 an expression matching this name (see matcher attribute below)
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 excluded.
'*' 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 excluded
0..n
conf
Tag: conf Parent: artifact
Specify a configuration in which the enclosing artifact exclusion should be included.
Attributes
Attribute Description Required name the 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 an expression matching this name (see matcher attribute below)
No, defaults to .* type the type of the artifact of the dependency module to add to the include list, or an expression matching this name (see matcher attribute below)
No, defaults to .* ext the extension of the artifact of the dependency module to add to the include list, or an expression matching this name (see matcher attribute below)
No, defaults to type matcher the matcher to use to match the modules to include since 2.0
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: 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
exclude
Tag: exclude Parent: dependencies
since 2.0 This feature gives you more control on a dependency for which you do not control its ivy file.
It allows to exclude artifacts, modules or organizations from the list of dependencies for the whole module.
It is very similar to the dependency exclude element, except that it applies to a whole module, which can be very useful when a lot of dependencies transitively bring a module you don't want.
Attributes
Attribute Description Required org the organization of the dependency module or artifact to exclude, or a regexp matching this organization
No, defaults to * module the name of the dependency module or the artifact to exclude, or a regexp matching this module name
No, defaults to * artifact the name of an artifact of the dependency module to add to the exclude list, or an expression matching this name (see matcher attribute below)
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 an expression matching this name (see matcher attribute below)
No, defaults to type matcher the matcher to use to match the modules to excludes
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
override
Tag: override Parent: dependencies
(since 2.0)
Specify an override mediation rule, overriding the revision and/or branch requested for a transitive dependency.
This can be useful when a direct dependency is bringing a transitive dependency for which you want to change the revision, without actually declaring a dependency on it (because the module doesn't actually depend on it) and without using conflict management for this purpose (maybe because there is no conflict at all, or because you want to by pass conflict management for this particular transitive dependency).
Overriding is done before any else, in a phase called dependency descriptor mediation. The transitive dependency then behave exactly as if it were declared with the new value.
Note that even though no attribute is required, it makes no sense to set no attributes at all. It would mean that overriding is triggered for all transitive dependencies, but doesn't override anything. Most of the time, at least org or module should be set to override only a subset of transitive dependencies, and at least branch or rev should be set to actually override something.
Attributes
Attribute Description Required org the name, or an expression matching the name of organisation to which overriding should be applied (see matcher attribute below)
No, defaults to * (match all) module the name, or an expression matching the name of module to which overriding should be applied (see matcher attribute below)
No, defaults to * (match all) branch the branch to set for all the overriden dependency descriptors
No, by default branch is not overriden rev the revision to set for all the overriden dependency descriptors
No, by default revision is not overriden matcher the matcher to use to match the modules for which the conflict manager should be used
No, defaults to exact
conflict
Tag: conflict Parent: dependencies
(since 2.0)
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.
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 no specific conflict manager is defined, a default conflict manager is used for all modules.
The current default conflict manager is the "latest-revision" conflict manager.
Attributes
Attribute Description Required org the name, or an expression matching the name of organisation to which this conflict manager should apply (see matcher attribute below)
No, defaults to * (match all) module the name, or an expression matching the name of module to which this conflict manager should apply (see matcher attribute below)
No, defaults to * (match all) manager the name of the conflict manager to use
Exactly one of two rev a comma separated list of revisions this conflict manager should select matcher the matcher to use to match the modules for which the conflict manager should be used
No, defaults to exact
conflicts
Tag: conflicts Parent: ivy-module
(since 2.0) the conflicts section is deprecated. Use the conflict instead.
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
Element Description Cardinality manager declares a conflict manager for this module
1..n
manager
Tag: manager Parent: conflicts
(since 2.0) the conflicts section is deprecated. Use the conflict instead.
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
Attribute Description Required org the name, or an expression matching the name of organisation to which this conflict manager should apply (see matcher attribute below)
No, defaults to * (match all) module the name, or an expression matching the name of module to which this conflict manager should apply (see matcher attribute below)
No, defaults to * (match all) name the name of the conflict manager to use
Exactly one of two rev a comma separated list of revisions this conflict manager should select matcher the 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
Ant Tasks
The main and most frequent way to use ivy is from an ant build file. However, ivy can also be called as a standalone application
If you use ant version 1.6.0 or superior, you just have to add ivy namespace to your project (xmlns:ivy="antlib:org.apache.ivy.ant"
attribute of your project tag), and you can call ivy tasks.
If you want to make your build handle ivy.jar in either ant lib dir or a local lib dir, you can use a taskdef like this:
<path id="ivy.lib.path">
<fileset dir="path/to/dir/with/ivy/jar" includes="*.jar"/>
</path>
<taskdef resource="org/apache/ivy/ant/antlib.xml"
uri="antlib:org.apache.ivy.ant" classpathref="ivy.lib.path"/>
Combined with the antlib definition in the project namespace, it will load Ivy classes either from your ant lib or a local directory (path/to/dir/with/ivy/jar in this example).
If you use ant 1.5.1 or superior, you have to define the tasks you use in your build file. For instance:
<taskdef name="ivy-configure" classname="org.apache.ivy.ant.IvyConfigure"/>
<taskdef name="ivy-resolve" classname="org.apache.ivy.ant.IvyResolve"/>
<taskdef name="ivy-retrieve" classname="org.apache.ivy.ant.IvyRetrieve"/>
<taskdef name="ivy-deliver" classname="org.apache.ivy.ant.IvyDeliver"/>
<taskdef name="ivy-publish" classname="org.apache.ivy.ant.IvyPublish"/>
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 the ivy retrieving dependencies process:
- First the configure task tells it how it can find dependencies giving it a path to an xml settings file.
- Then the resolve task actually resolves dependencies described by an ivy file, and puts those dependencies in the ivy cache (a directory configured in the settings 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.settings.file = ivysettings.xml
ivy.retrieve.pattern = ${ivy.lib.dir}/[artifact]-[revision].[ext]
ivy.deliver.ivy.pattern = ${ivy.distrib.dir}/[type]s/[artifact]-[revision].[ext]
ivy.publish.src.artifacts.pattern = ${ivy.distrib.dir}/[type]s/[artifact]-[revision].[ext]
ivy.report.output.pattern = [organisation]-[module]-[conf].[ext]
ivy.buildlist.ivyfilepath = ivy.xml
ivy.checksums=sha1,md5
For the latest version of these properties, you can check the svn version.
since 2.0 After calling the first Ivy task, the property ivy.version will be available and contains the version of the used Ivy library.
Ivy tasks attributes : generalities
Some tasks attributes values may be given through different places. The three possible places are :
- task attribute
- ivy instance
- project property
The 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:org.apache.ivy.ant" name="sample" default="resolve">
<target name="resolve">
<ivy:configure file="../ivysettings.xml" />
<ivy:resolve file="my-ivy.xml" conf="default, myconf" />
</target>
<target name="retrieve-default" depends="resolve">
<ivy:retrieve pattern="lib/default/[artifact]-[revision].[ext]" conf="default" />
</target>
<target name="retrieve-myconf" depends="resolve">
<ivy:retrieve pattern="lib/myconf/[artifact]-[revision].[ext]" conf="myconf" />
</target>
<target name="retrieve-all" depends="resolve">
<ivy:retrieve pattern="lib/[conf]/[artifact]-[revision].[ext]" conf="*" />
</target>
<target name="deliver" depends="retrieve-all">
<ivy:deliver deliverpattern="distrib/[artifact]-[revision].[ext]"
pubrevision="1.1b4" pubdate="20050115123254" status="milestone" />
</target>
<target name="publish" depends="deliver">
<ivy:publish resolver="internal"
artifactspattern="distrib/[artifact]-[revision].[ext]"
pubrevision="1.1b4" />
</target>
</project>
All ivy tasks are documented in the following pages.
artifactproperty
since 1.1
Sets an ant property for each dependency artifacts previously resolved.
since 2.0 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).
The property name and value are generated using the classical pattern concept, all artifact tokens and ivy variables being available.
since 2.0 This tag will follow the ant usual behavior for properties. If a property of the same name already exist, it's value will be unchanged. This behavior can be changed using the 'overwrite' attribute.
WARNING : Before 2.0, the behavior was to overwrite the properties. Since 2.0, the default is to not overwrite to properties
Attributes
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) settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default. overwrite Overwrite the value of the property if it already exist (since 2.0). Before 2.0, the properties were always overwritten. No, 'false' by default.
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.
since 2.0 This is a post resolve task, with all the behaviour and attributes common to all post resolve tasks.
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">
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>
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 settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default.
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.
When the ivy.xml of the modules that you want to order doesn't contains a revision numbers, the rev attributes declared in the dependency is not used.
When the ivy.xml of the modules that you want to order contains a revision numbers, the revision numbers are used. If the revision number doesn't match a dependency description a warning is logged and the modules is considered as different modules.
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.
since 2.0 The root and leaf attributes can be a delimited list of modules to use as roots. These modules, and all their dependencies will be included in the build list.
since 2.0 By default, all the modules included in a circular dependency are grouped together so that any dependency of any module in the loop will apear before the modules in the loop. This garantee that if there is a depedendency path between a module A and a module B (but no dependency path from B to A), B will alway apear before A even if A is included in a loop in the provided set of modules to sort.
Note that circular dependency can also trigger a failure depending on the value configured in the circularDependencyStrategy of your settings
since 2.0 When you are specifying root or leaf modules you can limit the resulting list to only direct dependencies of the roots modules or to modules that directly depends on your leaf modules.
since 2.0 You can also specify a restartFrom modules. The difference with root or leaf, is that you get a list starting at the restartFrom module followed by all the modules that would be after if the parameter would not be there (even if there is no dependency between the restartFrom and the following module).
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 2.0 the names of the modules which should be considered as the root of the buildlist.
since 1.3 Was limited to only one module name before 2.0. 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 2.0 the names of the modules which should be considered as the leaf of the buildlist.
since 1.4.1 Was limited to only one module name before 2.0. No. Defaults to no leaf (all modules are used in the build list) onlydirectdep since 2.0 true if the
resulting list should be restricted to direct dependencies of root modules or modules that directly depends on the leaf modules.
This field is ignored when neither root neither leaf is filled.
No. Defaults to no false delimiter since 2.0 delimiter to use when specifying multiple module names in the root and leaf properties. No. Defaults to the comma (,) character. 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 Deprecated, use onMissingDescriptor instead. 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 onMissingDescriptor since 2.0 Specify the action to take when no module descriptor file is found for a file of the fileset. Possible values are:
- head
put at the head of the built filelist.
- tail
put at the tail of the built filelist.
- skip
skip the file, which won't be put in the build filelist at all.
- warn
warn and put at the head of the build filelist.
- fail
halt the build with a failure.
No. Defaults to 'head' 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 restartFrom since 2.0 The name of the module which should be considered as the starting point in the buildlist. This allows for the build to be started at any point in the dependency chain.
No. Defaults to '*' meaning no restart point (all modules are used in the build list). settingsRef since 2.0 A reference to the ivy settings that must be used by this task No, 'ivy.instance' is taken by default.
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 settingsRef A reference to the ivy settings that must be used by this task (since 2.0). No, 'ivy.instance' is taken by default. resolver the name of the resolver to use for build number calculation (since 2.1)
No, all available resolvers will be used by default.
Examples
Here is how it can be used (suppose 1.3.1 is the latest version of ivy in the repository):
<ivy:buildnumber organisation="apache" 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="apache" 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="apache" 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="apache" 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="apache" 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="apache" 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 * settingsRef (since 2.0) A reference to the ivy settings that must be used by this task No, 'ivy.instance' is taken by default.
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.
If you want to make your build more independent from Ivy, you could consider using the retrieve task. Once the artifacts are properly retrieved, you can use standard Ant path creation which makes Ivy not necessary any more.
Built path is registered in ant with a given id, and can thus be used like any other ant path using refid.
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 * settingsRef (since 2.0) A reference to the ivy settings that must be used by this task No, 'ivy.instance' is taken by default.
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.
cleancache
since 2.0
Cleans the Ivy cache.
This task is roughly equivalent to:
<delete dir="${ivy.cache.dir}" />
Using the regular Ant delete task is more flexible, since it allows to specify the files to delete. But it requires an Ivy settings to be loaded, and settings scoping is possible only by using suffixed ant property for the cache directory.
This task loads the Ivy settings as any other post settings task, and allows easy scoping with the attribute settingsRef.
Attributes
Attribute Description Required settingsRef A reference to the ivy settings that must be used by this task No, 'ivy.instance' is taken by default.
Examples
<ivy:cleancache />
Cleans the cache directory as defined in the loaded settings (by default ~/.ivy2/cache)
<ivy:cleancache settingsRef="mysettings"/>
Cleans the cache directory as defined in the loaded settings identified as 'mysettings'
configure
The configure task is used to configure ivy with an xml settings file.
See Settings Files for details about the settings file itself.
since 2.0 The file loaded used to be called configuration file in versions prior to 2.0. The name 'settings' and the use of the ivy.settings.file is new to 2.0.
since 2.0 It is also possible to configure Ivy with the settings declaration. The difference with this task is that when using the settings declaration, the configuration of Ivy will be done when the settings are first needed (for instance when you do a resolve), while the configure task will perform a configuration of Ivy instantly, which makes it easier to see the problem if something goes wrong.
Attribute Description Required settingsId The settings id useable in the settingsRef attributes of the ivy task that needs a setting. Note that the ivy tasks will search by default for the settings with the id "ivy.instance", which is the default value. No, defaults to "ivy.instance" file path to the settings 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.settings.file}, and if this file does not exist, it uses a default settings file url url of the settings file to use override Specify what to do when another settings with the same id has already been loaded.- true
the current settings will take precedence over any previously defined setting with this id- false
the current settings will not override a previously defined setting with this id- notallowed
an error is raised if a settings has already been defined with this id
No, defaults to "notallowed" host http authentication host No, unless authentication is required realm http authentication realm username http authentication user name passwd http authentication password
HTTP Authentication
Note: HTTP Authentication can be used only if commons-httpclient.jar is in your classpath
If any of the url you use in ivy (especially in dependency resolvers) need http
authentication, then you have to provide the host, realm, username and passwd
attributes of the configure task. These settings will then be used in any
further call to ivy tasks.
Since 1.4:
It's also possible to configure authentication settings for multiple urls. This can be done with the subelements. See the examples for more details.
Examples
Simplest settings
<ivy:configure />
Use either ${ivy.settings.file} if it exists, or the default settings 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/ivysettings.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
Deliver a resolved descriptor of the current module, and possibly perform a recursive delivery of dependencies.
This task does two main things:
Generate a resolved ivy file
This task generates a resolved descriptor 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. This is an exception to the recommended standard that published module descriptors be fully resolved, so use it with caution.
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 pubbranch the branch to use for the publication
No. Defaults to ${ivy.deliver.branch} if set, or the branch resolved if set, or nothing (branch info won't be updated) 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 dynamic revisions by static ones in the delivered file, false to avoid this replacement (since 1.3)
No. Defaults to true replaceForcedRev true to replace revisions (static or dynamic) by the revision of the resolver in forced mode, false to avoid this replacement (since 2.2)
No. Defaults to false merge if a descriptor extends a parent, merge the inherited information directly into the delivered descriptor. The extends element itself will be commented out in the delivered descriptor. (since 2.2)
No. Defaults to true. settingsRef A reference to the ivy settings that must be used by this task (since 2.0)
No, 'ivy.instance' is taken by default. conf comma-separated list of configurations to include in the delivered file. Accepts wildcards. (since 2.0)
No. Defaults to all configurations generateRevConstraint true to automatically generate a 'revConstraint' attribute in the deliverd file (see the dependency page for more info about this attribute), false to never generate this attribute (since 2.1.0)
No. Defaults to true
Example
Deliver an ivy file without the private configurations:
<deliver conf="*(public)" />
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 settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default.
Examples
<ivy:findrevision organisation="apache" 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="apache" 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:
Property Description 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.branch The branch of the module if any, 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.status The status of the module, as found in the info tag of the ivy file parsed. ivy.publication The publication time of the module, as found in the info tag of the ivy file parsed. (Since 2.2) ivy.extra.[any extra attribute] Corresponding extra attribute value, 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 ivy.configuration.[config name].desc For each configuration with a description, a property is created containing this description. (Since 2.2) ivy.artifact.[index].name For each published artifact, a property is created containing its name. (Since 2.2) ivy.artifact.[index].type For each published artifact, a property is created containing its type. (Since 2.2) ivy.artifact.[index].ext For each published artifact, a property is created containing its ext. (Since 2.2) ivy.artifact.[index].conf For each published artifact, a property is created containing its conf. (Since 2.2) ivy.artifact.[index].extra.[any extra attribute] For each extra attribute of the published artifact, a property is created containing its name. (Since 2.2)
since 2.0
Since Ivy 2.0 this task has been enhanced to allow you to retrieve information about ivy modules in a repository. Instead of specifying a local ivy file you may specify the organisation, module, revision pattern and (optionally) the branch of the ivy module in the repository you wish to retrieve the information for.
The revision pattern is what is used when declaring a dependency on a module, identical to how the findrevision task works. In fact this task can now be used in place of the findrevision task.
If no matching module is found then no property values are set.
You may now also set the property attribute to change the first part of the property names that are set by this task e.g. if you set the property attribute to 'mymodule' this task will set the ant properties mymodule.organisation, mymodule.module, mymodule.revision etc.
since 2.2
Since Ivy 2.2 this task has been enhanced to also retrieve detailed information about the module's published artifacts, as well as the publication time.
Attributes
Attribute Description Required file the ivy file to parse
Yes, if you wish to parse an ivy file.
No, if you are retrieving information about a module from an ivy repository. organisation the organisation of the module to find (since 2.0)
No, if you wish to parse an ivy file.
Yes, if you are retrieving information about a module from an ivy repository. module the the name of the module to find (since 2.0)
No, if you wish to parse an ivy file.
Yes, if you are retrieving information about a module from an ivy repository. branch the branch of the module to find (since 2.0)
No, defaults to the default branch for the given module if you are retrieving information about a module from an ivy repository. revision the revision constraint to apply (since 2.0)
No, if you wish to parse an ivy file.
Yes, if you are retrieving information about a module from an ivy repository. property the name to use as the base of the property names set by this task (since 2.0)
No, will default to 'ivy' if not set. settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default.
Examples
Given this ivy.xml file:
<ivy-module version="1.0" xmlns:e="http://ant.apache.org/ivy/extra">
<info organisation="apache"
module="info-all"
branch="trunk"
revision="1.0"
status="release"
e:myextraatt="myvalue"
/>
<configurations>
<conf name="default" />
<conf name="test" />
<conf name="private" visibility="private"/>
</configurations>
<publications>
<artifact name="thing1" type="jar" ext="jar" conf="default" e:data="main"/>
<artifact name="thing2" type="jar" ext="jar" conf="default" e:data="client"/>
</publications>
<dependencies>
<dependency org="org1" name="mod1.2" rev="2.0"/>
</dependencies>
</ivy-module>
<ivy:info file="${basedir}/path/to/ivy.xml" />
Parses ${basedir}/path/to/ivy.xml and set properties as described above accordingly:
ivy.organisation=apache
ivy.module=info-all
ivy.branch=trunk
ivy.revision=1.0
ivy.status=release
ivy.extra.myextraatt=myvalue
ivy.configurations=default, test, private
ivy.public.configurations=default, test
ivy.artifact.1.name=thing1
ivy.artifact.1.type=jar
ivy.artifact.1.ext=jar
ivy.artifact.1.conf=default
ivy.artifact.1.extra.data=main
ivy.artifact.2.name=thing2
ivy.artifact.2.type=jar
ivy.artifact.2.ext=jar
ivy.artifact.2.conf=default
ivy.artifact.2.extra.data=client
Given the same ivy module in a repository:
<ivy:info organisation="apache" module="info-all" revision="1.0" />
will set the exact same set of properties as above. Using:
<ivy:info organisation="apache" module="info-all" revision="1.0" property="infotest"/>
will set:
infotest.organisation=apache
infotest.module=info-all
infotest.branch=trunk
infotest.revision=1.0
infotest.status=release
infotest.extra.myextraatt=myvalue
infotest.configurations=default, test, private
infotest.public.configurations=default, test
infotest.artifact.1.name=thing1
infotest.artifact.1.type=jar
infotest.artifact.1.ext=jar
infotest.artifact.1.conf=default
infotest.artifact.1.extra.data=main
infotest.artifact.2.name=thing2
infotest.artifact.2.type=jar
infotest.artifact.2.ext=jar
infotest.artifact.2.conf=default
infotest.artifact.2.extra.data=client
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 branch the branch of the module to install since 2.0
No, defaults to default branch with exact matcher, '*' with any other matcher revision the revision of the module to install
Yes type the type(s) of artefact(s) to install. You can give multiple values separated by commas
No, defaults to '*' meaning all types 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 settingsRef A reference to the ivy settings that must be used by this task (since 2.0)
No, 'ivy.instance' is taken by default. haltonfailure true to fail build on unresolved dependencies since 2.0
No, defaults to true
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 settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default. resolver The name of the resolver to use for searching the modules (since 2.2.0) No, all available resolvers will be used by default.
Examples
<ivy:listmodules organisation="apache" module="ivy" revision="*" property="ivy.[revision]" value="found"/>
will find all revisions of the module ivy in the org apache, 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=apache
modules.ivyde=apache
modules.ivytools=ivytools
makepom
since 2.0
The makepom task allows to convert an ivy file to a pom file.
An example of use is to publish an Ivy managed module to a maven 2 repository.
Note that all Ivy features are not supported by maven poms, so the converted pom may not resolve to the exact same dependencies as the original ivy file.
since 2.2
It is possible to specify a template file defining the structure of the generated POM. The following processing is done on this template:
- properties like ${property.name} are replaced if they are defined in Ant or by the ivy:makepom task (see below for the standard properties)
- lines containg the string SKIP_LINE are skipped.
- the defined dependencies will be added to the first
element encountered in the pom template. If the template doesn't contain a element, it is generated a the end of the pom.
The ivy:makepom task defines following properties that can be used in the template.
- ivy.pom.groupId: defaults to the organisation as defined in the ivy.xml file
- ivy.pom.artifactId: defaults to the value of the 'atifactName' attribute of this task, or the name of the module as defined in the ivy.xml file
- ivy.pom.packaging: defaults to the value of the 'artifactPackaging' attribute of this task, or the extenstion of the artifact
- ivy.pom.version: defaults to the revision as defined in the ivy.xml file
- ivy.pom.name: defaults to 'SKIP_LINE'
- ivy.pom.description: defaults to the value of the 'description' attribute of this task, or 'SKIP_LINE' when not specified
- ivy.pom.url: defaults to the homepage as defined in the ivy.xml file
- ivy.pom.license: the content of the specified headerFile, or 'SKIP_LINE' if not specified
- ivy.pom.header: some Ivy information, or 'SKIP_LINE' if the 'printIvyInfo' attribute is set to false.
Note that each property can be given a value manually in the Ant build file. In that case, Ivy will use the value specified in the build file instead of the default value.
The default template that ships with Ivy looks like this:
${ivy.pom.license}
${ivy.pom.header}
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>${ivy.pom.groupId}</groupId>
<artifactId>${ivy.pom.artifactId}</artifactId>
<packaging>${ivy.pom.packaging}</packaging>
<version>${ivy.pom.version}</version>
<name>${ivy.pom.name}</name>
<description>${ivy.pom.description}</description>
<url>${ivy.pom.url}</url>
</project>
Attributes
Attribute Description Required ivyfile the source ivy file to convert
Yes pomfile the destination pom file to write
Yes templatefile the template file to use when generating the pom (since 2.2)
No, defaults to the internal template file. artifactName The name of the artifact which is represented by the generated pom file. (since 2.2)
No, defaults to the module name in the source ivy file. artifactPackaging The packaging of the artifact which is represented by the generated pom file. (since 2.2)
No, the artifact ext is taken by default. Defaults to 'pom' if no such artifact is defined. conf a comma separated list of the configurations to include in the generated pom. Wildcards are supported here. (since 2.2)
No, defaults to all configurations. settingsRef A reference to the ivy settings that must be used by this task
No, 'ivy.instance' is taken by default. printIvyInfo Add some information about Ivy to the generated POM. (since 2.2)
No, defaults to 'true'. headerFile the header of the generated pom file
No description The description that will be added to the generated pom. (since 2.2)
No, defaults to no description.
Child elements
Element Description Cardinality mapping
describes the mapping from an Ivy module configuration to a Maven POM scope.
These elements takes two attributes: - conf
the configuration to map- scope
the scope to which it should be mapped
0..n dependency
describes extra dependencies that should be added to the generated Maven POM file.
These elements takes the following attributes: - group
the groupId. Default organisation as defined in info- artifact
the name of the artifact- version
the version. Default revision as defined in info- scope
the scope- optional
is the artifact optional. Default false
0..n
Examples
<ivy:makepom ivyfile="${basedir}/path/to/ivy.xml" pomfile="${basedir}/path/to/module.pom" conf="default,runtime">
<mapping conf="default" scope="compile"/>
<mapping conf="runtime" scope="runtime"/>
<dependency group="com.acme" artifact="acme-logging" version="1.0" optional="true"/>
</ivy:makepom>
Converts ${basedir}/path/to/ivy.xml to a pom and writes the result to ${basedir}/path/to/module.pom. The configuration 'default' in the parsed ivy file will be mapped to the scope 'compile', the configuration 'runtime' will be mapped to 'runtime', and other configurations will be excluded.
The com.acme.acme-logging artifact with version 1.0 will be added as an optional dependency.
post resolve tasks
Several tasks in Ivy are considered as post resolve task and share a common behaviour and settings accordingly.
These tasks are:
- retrieve
- cachefileset
- cachepath
- artifactproperty (since 2.0)
- artifactreport (since 2.0)
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. You 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 or '*'.
Since 2.0 you can also use '*(public)' or '*(private)'. Note that '*' is interpreted as '*(public)' when inline is true.
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 branch the name of the branch to resolve in inline mode (since 2.1) Defaults to no branch in inline mode, nothing in standard mode. changing indicates that the module may change when resolving in inline mode. See cache and change management for details. Ignored when resolving in standard mode. (since 2.2.0) No. Defaults to false. transitive true to resolve dependencies transitively, false otherwise since 1.4 No. Defaults to true resolveMode the resolve mode to use when an automatic resolve is triggered (since 2.1) No. defaults to using the resolve mode set in the settings keep true to keep the results of the automatic resolve in memory, false to discard them. When this is false, the standard ivy properties won't be set and other postresolve-tasks (like retrieve and cachepath) won't be able to resuse the results of this resolve! No. defaults to false for an inline resolve and to true in any other case 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) refresh true to force Ivy to resolve dynamic revision in this resolve process, false to use cached resolved revision since 2.1 No. defaults to false file the file to resolve if a resolve is necessary since 2.0 No. Defaults to the previous resolved Ivy file or to ${ivy.dep.file} settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default. resolveId The id which was used for a previous resolve, or the resolveId if a new resolve is performed (since 2.0) No, defaults to '[org]-[module]'. log the log setting to use during the resolve process. (since 2.0)
Available options are:
- default
the default log settings, where all usual messages are output to the console
- download-only
disable all usual messages but download ones. A resolve with everything in cache won't output any message.
- quiet
disable all usual messages, making the whole resolve process quiet unless errors occur
No, defaults to 'default'.
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 module's artifacts and the resolved descriptor (delivered ivy file).
This task is meant to publish the current module descriptor together with its declared publication artifacts to a repository.
All the artifacts must have been created before calling this task. It does not create the artifacts themselves, but expects to find them at the location indicated by the artifacts pattern.
The target repository is given through the name of a resolver declared in current ivy settings. See Settings Files 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. See the illustration below:
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 organisation the name of the organisation of the module to publish No. Defaults to ${ivy.organisation} or the last resolved module organisation. module the name of the module to publish No. Defaults to ${ivy.module} or the last resolved module name. revision the revision of the module to publish and also the published revision unless pubrevision is set No. Defaults to ${ivy.revision} or the last resolve module revision. 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} pubbranch the branch to use for the publication
No. Defaults to the ${ivy.deliver.branch} 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 update true to update ivy file metadata (revision, branch, publication date and status) before publishing, false otherwise. This is usually not necessary when using deliver before publish.
No. Defaults to false merge if this descriptor extends a parent, merge the inherited information directly into this descriptor on publish. The extends element itself will be commented out in the published descriptor. (since 2.2)
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 settings file) replacedynamicrev true to replace dynamic 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 (since 1.4.1). Accepts wildcards (since 2.2).
No. Defaults to all configurations 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 settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default.
Child elements
Element Description Cardinality artifact
Describe additional artifacts to publish
These elements can have any attribute: standard artifact attributes and (since 2.2) extra attributes are supported.
0..n artifacts
Specify the pattern used to find the artifact.
These elements have a pattern attribute containing the pattern used to find the artifact.
0..n
Examples
<ivy:publish resolver="local" pubrevision="1.0">
<artifacts pattern="build/artifacts/jars/[artifact].[ext]" />
<artifacts pattern="build/artifacts/zips/[artifact].[ext]" />
</ivy:publish>
Publishes the last resolved module in the local resolver with revision 1.0, looking for artifacts in directories build/artifacts/jars and build/artifacts/zips.
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.
Limitation: this task requires to be able to browse the repository, and is thus limited to resolvers supporting repository listing. In particular, it means it doesn't work to report all organizations in a repository using m2compatible mode.
Moreover, to be able to list organizations, this task requires an [organisation] token in the resolver(s) used.
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) settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default.
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
Since 1.2:
An additional property is set to true if the resolved dependencies are changes since the last resolve, and to false otherwise: ivy.deps.changed
Since 2.0:
The property ivy.deps.changed will not be set (and not be computed) if you set the parameter checkIfChanged to false. (by default it is true to keep backward compatibility). This allow to optimize your build when you have multi-module build with multiple configurations.
Since 2.0:
In addition, if the resolveId attribute has been set, the following properties are set as well:
- ivy.organisation.${resolveId}
- ivy.module.${resolveId}
- ivy.revision.${resolveId}
- ivy.resolved.configurations.${resolveId}
- ivy.deps.changed.${resolveId}
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)
- dwnlded
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.
Inline mode
since 1.4 The 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 an 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.
Remark: if you want the standard ivy properties to be set or to reuse the results of an inline resolve by other post-resolve tasks like retrieve, cachepath, report, ..., you must set the keep attribute to true!
Resolve mode
since 2.0 The resolve mode allows to define how Ivy should use dependency revision constraints when performing the resolution.
Two modes are available:
- default
In this mode the default revision constraint (expressed with the rev attribute in the dependency element) is used.
- dynamic
In this mode the dynamic revision constraint (expressed with the revConstraint attribute in the dependency element) is used.
Concurrency
During resolve, Ivy creates a file in the resolution cache. The creation of this file is not aimed to support concurrency, meaning that you can't have two concurrent resolve of the same module, in the same resolution cache, with the same resolveId.
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"
.
Attributes
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, or '*'.
Since 2.0, you can also use '*(private)', '*(public)'. Note that when inline is true, the configuration '*' is equivalent as '*(public)'. No. Defaults to ${ivy.configurations} refresh true to force Ivy to resolve dynamic revision in this resolve process, false to use cached resolved revision since 2.0 No. defaults to false resolveMode the resolve mode to use for this dependency resolution process since 2.0 No. defaults to using the resolve mode set in the settings inline true to use inline mode, false to resolve an ivy file since 1.4 No. defaults to false keep true to keep the results of the resolve in memory, false to discard them. When this is false, the standard ivy properties won't be set and other postresolve-tasks (like retrieve and cachepath) won't be able to resuse the results of this resolve! No. defaults to false for an inline resolve and to true in any other case 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. branch the name of the branch to resolve in inline mode (since 2.1.0) Defaults to no branch in inline mode, nothing in standard mode. changing indicates that the module may change when resolving in inline mode. See cache and change management for details. Ignored when resolving in standard mode. (since 1.4) No. Defaults to false. 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) settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default. resolveId An id which can be used later to refer to the results of this resolve (since 2.0) No, defaults to '[org]-[module]'. log the log setting to use during the resolve process. (since 2.0)
Available options are:
- default
the default log settings, where all usual messages are output to the console
- download-only
disable all usual messages but download ones. A resolve with everything in cache won't output any message.
- quiet
disable all usual messages, making the whole resolve process quiet unless errors occur
No, defaults to 'default'. checkIfChanged When set to true, the resolve will compare the result with the last resolution done on this module, with those configurations in order to define the property ivy.deps.changed. Put it to false may provides slightly better performance. (since 2.0) No, default to 'true'
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
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. overwriteMode option to configure when the destination file should be overwritten if it exist (since 2.2.0). Possible values are:
- newer (default)
overwrite the destination file if a more recent one is available (based on timestamp)
- different
overwrite the destination file if the timestamp is different
- always
always overwrite the destination file
- never
never overwrite the destination file
No. Defaults to 'newer'. symlink true to create symbolic links, false to copy the artifacts. The destination of the symbolic links depends on the value of the useOrigin attribute (since 2.0) No. Defaults to false settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default. log the log setting to use during the resolve and retrieve process. (since 2.0)
Available options are the same as for resolve when used to trigger resolve automatically (see postresolvetask), or the following for the retrieve process only:
- default
the default log settings, where all usual messages are output to the console
- quiet
disable all usual messages, making the whole retrieve process quiet unless errors occur
No, defaults to 'default'.
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 graphviz 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 resolveId has not been specified and 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 resolveId has not been specified and 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 settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default. resolveId The id which was used for a previous resolve (since 2.0) No, defaults to '[org]-[module]'.
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).
settings
(since 2.0)
The settings declaration is used to configure ivy with an xml settings file. The difference with the configure task is that when using the settings declaration, the configuration of Ivy will be done when the settings are first needed (for instance when you do a resolve), while the configure task will perform a configuration of Ivy instantly, which makes it easier to see the problem if something goes wrong.
See Settings Files for details about the settings file itself.
Multiple settings can be defined in a build script. Every task can reference its own settings.
All Ivy variables set during the settings are available in the Ant project as long as they were not set in Ant before (Ant properties are immutable).
Moreover, the variables are exposed under two names: the variable name, and the variable name suffixed by dot + the settings id.
For instance, if you load a settings with the id 'myid', and define a variable my.variable=my.value in the Ivy settings, both my.variable and my.variable.myid will now be available as properties in Ant and equal to 'my.value'. If you later load another settings with the id 'yourid', and in this settings assign the variable 'my.variable' the value 'your.value', in the Ant project you will have:
my.variable=my.value
my.variable.myid=my.value
my.variable.yourid=your.value
Attributes
Attribute Description Required id The settings id useable in the settingsRef attributes of the ivy task that needs a setting. Note that the ivy tasks will search by default for the settings with the id "ivy.instance", which is the default value. No, defaults to "ivy.instance" file path to the settings 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.settings.file}, and if this file does not exist, it uses a default settings file url url of the settings file to use host http authentication host No, unless authentication is required realm http authentication realm username http authentication user name passwd http authentication password
HTTP Authentication
Note: HTTP Authentication can be used only if commons-httpclient.jar is in your classpath
If any of the url you use in ivy (especially in dependency resolvers) need http
authentication, then you have to provide the host, realm, username and passwd
attributes of the configure task. These settings will then be used in any
further call to ivy tasks.
Multiple classloader
A special attention should be applied when you have a multi-project build with subant call, using ivy task loaded by a typedef. Indeed in this situation, it is possible to pass settings reference to a subbuild. When you do that, you should take of the classloader. The ivy task of your subant should not be defined in a different classloader than the parent one. This can be achieved by using the loader parameter of the antlib declaration, or avoid to reload the ivy antlib in the subbuild (place the taskdef in a target only executed when the antlib is not yet loaded).
Examples
Simplest settings
<ivy:settings />
Use either ${ivy.settings.file} if it exists, or the default settings file
This simplest setting is implicit.
Configure with a file
<ivy:settings file="mysettings.xml" />
Configure with an url
<ivy:settings url="http://mysite.com/mysettings.xml" />
Configure multiple realms which require autentication
<ivy:settings file="path/to/my/ivysettings.xml">
<credentials host="myhost.com" realm="My Realm" username="myuser" passwd="mypasswd" />
<credentials host="yourhost.com" realm="Your Realm" username="myuser" passwd="myotherpasswd" />
</ivy:settings>
Configure 2 different settings
You can use multiple ivy settings during a build. Then every ivy task should specify the settings it uses using the settingsRef attribute.
<ivy:settings id="ivy.normal.settings" file="normal_settings.xml" />
<ivy:settings id="ivy.release.settings" file="release_settings.xml" />
<ivy:resolve settingsRef="ivy.normal.settings" />
<ivy:resolve settingsRef="ivy.release.settings" />
var
Sets a variable (by name and value), or set of variables (from file or url) in ivy.
Variables are case sensitive.
Contrary to ant properties, ivy variables are mutable. But a problem with this is that you do not control when
variables are substituted, and usually it is done as soon as possible. So changing the value of a variable will
have no effect if it has already been substituted. Consequently, using this task is NOT recommended.
See reference page for details about ivy variables.
Attribute Description Required name the name of the variable to set
No value the value of the variable to set
Yes when using the name attribute file the filename of the property file to load as ivy variables
One of these, when not using the name attribute url the url from which to read ivy variables prefix Prefix to apply to variables. A "." is appended to the prefix if not specified.
No settingsRef A reference to the ivy settings that must be used by this task (since 2.0) No, 'ivy.instance' is taken by default.
Using standalone
Ivy can be used as a standalone program very easily. All you need is a java 1.4+ runtime environment (JRE)!
Then here is how to call it:
java -jar ivy.jar -?
It will display an online help like this:
==== settings options
-settings <settingsfile> use given file for settings
-cache <cachedir> use given directory for cache
-novalidate do not validate ivy files against xsd
-m2compatible use maven2 compatibility
==== resolve options
-ivy <ivyfile> use given file as ivy file
-dependency <organisation> <module> <revision>
use this instead of ivy file to do the rest of the
work with this as a dependency.
-confs <configurations> resolve given configurations
==== retrieve options
-retrieve <retrievepattern> use given pattern as retrieve pattern
-sync use sync mode for retrieve
==== cache path options
-cachepath <cachepathfile> outputs a classpath consisting of all dependencies
in cache (including transitive ones) of the given
ivy file to the given cachepathfile
==== deliver options
-deliverto <ivypattern> use given pattern as resolved ivy file pattern
==== publish options
-publish <resolvername> use given resolver to publish to
-publishpattern <artpattern> use given pattern to find artifacts to publish
-revision <revision> use given revision to publish the module
-status <status> use given status to publish the module
==== http auth options
-realm <realm> use given realm for HTTP AUTH
-host <host> use given host for HTTP AUTH
-username <username> use given username for HTTP AUTH
-passwd <passwd> use given password for HTTP AUTH
==== launcher options
-main <main> the FQCN of the main class to launch
-args <args> the arguments to give to the launched process
-cp <cp> extra classpath to use when launching process
==== message options
-debug set message level to debug
-verbose set message level to verbose
-warn set message level to warn
-error set message level to error
==== help options
-? display this help
-deprecated show deprecated options
since 1.3 System properties are included as ivy variables, so you can easily define an ivy variable like this:
java -Dmyivyvar=myvalue org.apache.ivy.Main [parameters]
Examples
java -jar ivy.jar
calls ivy with default configuration using ivy.xml in the current dir
java -jar ivy.jar -settings path/to/myivysettings.xml -ivy path/to/myivy.xml
calls ivy with given ivysettings file using given ivy file
since 1.3
java -jar ivy.jar -settings path/to/myivysettings.xml -dependency apache commons-lang 2.0
calls ivy with given ivysettings file and resolve apache commons-lang 2.0.
This is equivalent to:
java -jar ivy.jar -settings path/to/myivysettings.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 -jar ivy.jar -settings path/to/myivysettings.xml -ivy path/to/myivy.xml -cachepath mycachefile.txt
calls ivy with given ivysettings 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 -jar ivy.jar -settings path/to/myivysettings.xml -dependency bar foo 2.0 -main org.bar.foo.FooMain
calls ivy with given ivysettings file and resolve bar foo 2.0, and then run org.foo.FooMain class with the resolved artifacts as classpath
Developer doc
Building from source
To build Ivy from source it's really easy.
Requirements
All you need is
- an svn client
to check out Ivy sources from apache svn, not required if you build from sources packaged in a release
- Apache Ant 1.6.0 or greater
We recommend either ant 1.6.5 or 1.7.0
- junit 3.8.2 jar in your ant lib
this is not required if you use ant 1.7
- a jdk 1.4 or greater
Build instructions have been successfully tested with sun jdk 1.4.2, 1.5.0 and 1.6.0
Procedure
Get the source
You can either get the sources from a release, or get them directly from svn. For instance, to get the trunk version:
svn co https://svn.apache.org/repos/asf/ant/ivy/core/trunk ivy
Build
Go to the directory where you get the Ivy sources (you should see a file named build.xml) and run:
ant
Check the result
The ant build will compile the core classes of Ivy and use them to resolve the dependencies (used for some optional features). Then it will compile and run tests with coverage metrics.
If everything goes well, you should see the message
BUILD SUCCESSFUL
Then you can check the test results in the build/doc/reports/test directory, the jars are in build/artifacts, and the test coverage report in build/doc/reports/coverage
Coding conventions
The Ivy code base is supposed to follow the standard java conventions:
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
This is a work in progress though (see IVY-511), but patches helping migration to these conventions are welcome.
Developing with eclipse
Even though you can develop Ivy with your IDE of choice, we support eclipse development by providing ad hoc metadata.
We currently provide two options:
Eclipse alone
To develop with a simple eclipse install all you need is eclipse 3.1 or greater, with no particular plugin.
First call the following ant target in your Ivy workspace:
ant eclipse-default
This will resolve the dependencies of Ivy and produce a .classpath using the resolved jars for the build path.
Then you can use the "Import->Existing project into workspace" eclipse feature to import the Ivy project in your workspace.
Eclipse + IvyDE
You can also leverage the latest IvyDE version to be able to easily resolve the ivy dependencies from Eclipse.
To do so all you need is call the following ant target in your Ivy workspace:
ant eclipse-ivyde
or if you don't have ant installed you can simply copy the file .classpath.ivyde and rename it to .classpath
Then you can import the project using "Import->Existing project into workspace" as long as you already have latest IvyDE installed.
To install latest IvyDE version compatible with the latest Ivy used to resolve Ivy dependencies, you will need to use a snapshot build, not endorsed by the ASF, available here:
http://people.apache.org/~xavier/ivyde/snapshot/
Download the file and unzip its content in your eclipse installation directory.
recommended plugins
The Ivy project comes with settings for the checkstyle plugin we recommend to use to avoid introducing new disgression to the checkstyle rules we use.
If you use this plugin, you will many errors in Ivy. As we said, following strict checkstyle rules is a work in progress and we used to have pretty different code conventions (like using _ as prefix for private attributes), so we still have things to fix. We usually use the filter in the problems view to filter out checkstyle errors from this view, which helps to know what the real compilation problem are.
Besides this plugin we also recommend to use a subversion plugin, subversive or subclipse being the two options currently available in the open source landscape.
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.
Many things are pluggable in Ivy:
- module descriptor parsers
- dependency resolvers
- lock strategies
- latest strategies
- circular dependency strategies
- conflict managers
- report outputters
- version matchers
- triggers
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 mailing-lists.
If you still don't find what you need, then you'll have to develop your own plugin or find someone who could do that for you.
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.
All pluggable code in Ivy is located in the org.apache.ivy.plugins package. In each package you will find an interface that you must implement to provide a new plugin. We usually also provide an abstract class easing the implementation and making your code more independent of interface changes. We heavily recommend using these abstract classes as a base class.
To understand how your implementation can be done, we suggest looking at existing implementations we provide, it's the best way to get started.
Making a release
Making a release
Requirements
Requirements for making a release are similar to the requirements for building from source, except that sun jdk 1.6 and ant 1.7 are required.
Procedure
1. Check the files which needs to be updated for the release.
On the trunk, check that files which require update for the release are up to date.
This includes particularly:
RELEASE_NOTES
CHANGES
README
2. Create a release branch
This will allow to work separately from other developers, in case you need any last modification.
svn copy https://svn.apache.org/repos/asf/ant/ivy/core/trunk \
https://svn.apache.org/repos/asf/ant/ivy/core/branches/2.0.0-beta1 \
-m "Creating a release branch for 2.0.0-beta1."
3. Check out the branch
svn co https://svn.apache.org/repos/asf/ant/ivy/core/branches/2.0.0-beta1 ivy-2.0.0-beta1
4. Add Ivy xsd file.
You need to store the current ivy xml schema in the documentation, so that it will later be accessible on public web site. To do so, run the following command in the directory in which you checked out the release branch:
ant -f build-release.xml release-xsd
5. Add release note page in the documentation.
Open the file doc/index.html with your favorite browser, and click on the plus button in the upper right. Choose "Release Notes" as title, and "release-notes" as page id.
Then edit the page (hit the first button at the upper right), and copy the content of the RELEASE_NOTES file.
You can also add the announcement for the release if it's already ready. If this is an incubator version, add the usual incubator disclaimer too.
Move the page up in the TOC using the arrow button in the toolbar at the upper right, so that it's the first child page under the "Documentation" page.
If you take the time to make the content of the release notes more "xooki compliant" (by removing unnecessary end of lines and adding h2 h3 and h4 tags), the page could then look like something like that:
http://ant.apache.org/ivy/history/2.0.0-alpha-1.html
6. Commit your changes
svn status
svn add doc/ivy.xsd
svn add doc/release-notes.html
svn ci -m "update templates, add release notes and ivy.xsd in documentation."
7. Check that you have no pending modifications
svn status
If your working copy is clean, you can launch the release script. If it isn't, make sure to clean it properly. Sometimes you may need to call ant clean-all if you have started to work with ant builds. If you are confused about your working copy state, delete it and check it out again.
8. Launch the release script
ant -f build-release.xml release
The status should be release only for final releases, and milestone for any other intermediate release.
If anything is wrong, fix and go back to step 4.
If the release script is successful, release artifacts will be waiting for you in the build/distrib directory.
9. Verify the release
Check that all zips can be opened correctly, and that running 'ant' after unzipping the source distribution works properly.
You can also do a smoke test with the generated ivy.jar , to see if it is able to resolve properly a basic module (for instance you can run some tutorials provided in the src/example directory in all distributions).
10. Sign and upload the artifacts
It's now time to sign the release artifacts and upload them to a location accessible by other Apache commiters.
Here is a simple way to sign the files using gnupg:
gpg --armor --output file.zip.asc --detach-sig file.zip
Here is a ruby script you can use to sign the files:
require 'find'
Find.find('build/distrib') do |f|
`gpg --armor --output #{f}.asc --detach-sig #{f}` if File.file?(f) && ['.zip', '.gz', '.jar', '.pom'].include?(File.extname(f))
end
Be prepared to enter your passphrase several times if you use this script, gpg will ask for your passphrase for each file to sign.
When you're done upload the content of the distrib directory to a publicly accessible web site, your apache personal site being a good location for this. Make sure you include some kind of disclaimer somewhere to inform people the release is not approved yet.
You can for example add a HEADER.html like this:
<h2>WARNING: files available here are NOT an Apache approved release yet.</h2>
11. Prepare the Eclipse update site
To be able to test the release within IvyDE, it can be deployed in the IvyDE update site. See that page to know how to process.
12. Tag the svn repository
As soon as you are happy with the artifacts to be released, it is time to tag the svn repo
svn copy https://svn.apache.org/repos/asf/ant/ivy/core/branches/2.0.0-beta1 \
https://svn.apache.org/repos/asf/ant/ivy/core/tags/2.0.0-beta1 \
-m "Tag release 2.0.0-beta1."
And don't forget to set the svn:external on doc/xooki to a fixed revision. Edit the svn:external property on the folder doc/xooki in the tag and set it to the revision of the commit of the tag. It should look like:
xooki -r790212 https://svn.apache.org/repos/asf/ant/ivy/site/xooki/
And commit that modification.
13. Call for a vote to approve the release
Cast a vote to approve the release on the dev@ant.apache.org mailing list.
Here is an example:
Subject: [VOTE] Ivy ${version} Release
I have built a release candidate for Ivy ${version}
You can download it from this URL: ${url}
Do you vote for the release of these binaries?
[ ] Yes
[ ] No
Regards,
${me}, Ivy ${version} release manager
14. Upload to public repository
If the release is approved, it's now time to make it public by uploading it to the public Apache distrib repository (i.e. /www/www.apache.org/dist/ant/ivy/[version] on people.a.o).
Copy also the staging maven 2 repository to apache maven 2 rsync repo:
/www/people.apache.org/repo/m2-ibiblio-rsync-repository
15. Update the web site
Add a link to the released version documentation in the web site.
To do so, you need to:
- add a svn externals reference to the documentation
edit the svn properties of site/history, and in the svn:externals property, add a line like this one:
2.0.0-beta1 https://svn.apache.org/repos/asf/ant/ivy/core/branches/2.0.0-beta1/doc
You should also change the latest-milestone external link.
You can use "svn propedit svn:externals path/to/history" to do so.
Once you've changed the property, use "svn up" to checkout the proper documentation.
- edit the toc.json file in the site component of Ivy
and add something like that:
{
"title":"2.0.0-beta1",
"url":"http://ant.apache.org/ivy/history/2.0.0-beta1/index.html"
}
You can also edit the title of the main documentation node pointing to latest-milestone / latest-release if necessary.
- Now generate the part of the site for the new version
ant generate-history-ivy -Dhistory.version=2.0.0-beta1
Then you can update the release notes page of the imported documentation if necessary, to include the announcement for example.
It's time to update the download image used on the home page and the download page. Use site/images/ivy-dl.xcf as a basis if you have gimp installed. Then you can update the home page to refer to this image, and add a news item announcing the new version. Update also the download page with the new image and update the links to the download location (using a search/replace on the html source is recommended for this).
All site editing being done, commit your changes.
And now let's generate the site and deploy it:
- generate the part of the site for the new version:
ant generate-history-ivy -Dhistory.version=2.0.0-beta1
WARNING: that target is modifiying the toc.json in the imported branch so that the generated html have a proper version declared in the toc. You should not commit that change. Once the site has been generated, you may want to revert the changes so you won't commit it by mistake. (TODO: process to improve so we shouldn't worry).
- generate the website with the new toc:
ant /all generate-site-ivy
- you should verify that the site generated in target is OK. And once your happy with it, commit the changes in target (some svn add might be needed !)
- deploy the website: go on people.apache.org and svn up /www/ant.apache.org/ivy/
16. Deploy the Eclipse updatesite
If the Eclipse update site has already been prepared to include that new Ivy release, it is now needed to be deployed. Then follow the deployment instruction on that page.
17. Announce
Announce the release on the dev@ant.a.o, ivy-user@ant.a.o, user@ant.apache.org and announce@apache.org mailing lists.
You can also announce the release on popular web sites, like freshmeat.net (xavier is the owner of the Ivy project on freshmeat), javalobby.org, theserverside.com, dzone.com, ...
16. Update this doc
If you feel like anything is missing or misleading in this release doc, update it as soon as you encounter the problem.
17. Merge your modifications back to the trunk if necessary.
Modifications on the template files do not need to be merged, but if you had troubles during your release you may want to merge your fixes back to the trunk.
18. Prepare next release
Update the file version.properties with the version of the next release so that anyone building from the trunk will obtain jar with the correct version number.
Release the version in jira, and create a new unreleased version for the next planned version.
Updating the updatesite
Once a release have been build for Ivy or IvyDE, they should be pushed to the Eclipse updatesite so that Eclipse users will be able to update automatically their installed version of Ivy or IvyDE.
This doc is in two parts, the setup of the updatesite which will be the candidate for the vote of the Ivy or IvyDE release, and the final deployment once the release is accepted.
Important note: in this doc, the released version is denoted as $VERSION (and have to be replaced accordingly in every commands), but this is the OSGi one, not the usually shown one, in particular for release candidate versions. For instance an Ivy version can be 2.0.0-RC1 but the OSGi one, and the one to use here is 2.0.0.cr1.
Build the updatesite
Push the new version
The update site svn location is there: https://svn.apache.org/repos/asf/ant/ivy/updatesite/trunk . You will update it so it will contain the new artifacts.
Before installing the new version, you probably want to remove some deprecated version. For instance is the new release is a RC2, then the RC1 should be removed. But do keep old final release; some users might not want use to the exact same version of Ivy they use in Ant, which might not be the latest one. To do so just svn rm the jars, checksums and signatures of the features and plugins to remove.
- For an Ivy release:
As you have a build jar for Ivy, just do:
ant install-ivy -Divy.jar=...../path/to/ivy.jar
-
For an IvyDE release:
The zip distribution needs to be unpacked into the updatesite directory:
ant install-ivyde -Divyde.zip=...../path/to/org.apache.ivyde.feature-${VERSION}.zip
Prepare the update site
The update site is optimized: the metadata of the features are aggregated into the digest.zip, and the jar of the plugins are compressed with a better algorithm.
Important note: the following optimize tasks need to be run in java 5 jre. The pack200 didn't existed before java 5 and the jar compressed with java 6 can not be uncompressed by some java 5 jre (at least the IBM one).
To accomplish this task, just run at the root of your working copy of the updatesite:
- For an Ivy release:
ant optimize-ivy
-
For an IvyDE release:
ant optimize-ivyde
The binary files then need to be signed and their checksum computed. For the checksums, run:
ant checksum
And sign the binaries:
- For an Ivy release:
./signIvyArtifacts.sh
-
For an IvyDE release:
./signIvyDEArtifacts.sh
Note: these previous targets may optimize, checksum and sign already released artifacts. Just so a svn status to check the modified artifacts; the only modified files should be the digest.zip (with its signature and checksum) and the site.xml; then there should be the added files of the release. Then do some svn revert file to revert the unexpected changes.
And finally commit your changes.
As soon as you ar happy with the committed artifacts, we can tag the updatesite:
svn cp https://svn.apache.org/repos/asf/ant/ivy/updatesite/trunk https://svn.apache.org/repos/asf/ant/ivy/updatesite/tags/$TAGNAME
with $TAGNAME the name of the release, so it would be either ivy-$VERSION or ivyde-$VERSION.
Test the updatesite
The updatesite is ready to be tested. You can deploy it where ever you want with the command:
svn export https://svn.apache.org/repos/asf/ant/ivy/updatesite/trunk/dist updatesite
For both local and remote testing, as the new jars are not yet deployed on Apache mirrors, the updatesite mirroring have to be disable.
Basically it is just about modifying the site.xml and remove the reference to the eclipse-update--xml files: remove the attribute mirrorsURL.
To let the developper community test the updatesite, you can setup a staging updatesite in your public_html directory on people.apache.org. So if you deploy it on people.apache.org, in the directory ~/public_html/staging, then the developpers should setup the updatesite with the URL http://people.apache.org/~LOGIN/staging/updatesite .
Deployment of a release
Then backup and deploy. On people.apache.org:
cd /www/www.apache.org/dist/ant/ivyde/
mv updatesite ~/updatesite.backup
svn export https://svn.apache.org/repos/asf/ant/ivy/updatesite/tags/$TAGNAME/dist updatesite
- IMPROVEMENT: the
- IMPROVEMENT: Handle attributes in description subelements (IVY-1214) (thanks to Jean-Louis Boudart)
- IMPROVEMENT: Use IvyAuthenticator only when it is really necessary (IVY-1211)
- IMPROVEMENT: MakePom task handling of mulitple artifacts for Maven2 (IVY-770) (thanks to Jesper Pedersen)
- IMPROVEMENT: ivy:makepom now has an option to disable the generation of an extra Ivy comment block in the POM
- IMPROVEMENT: ivy:makepom now accepts a list of configurations to include (IVY-1005) (thanks to Jesper Pedersen)
- IMPROVEMENT: ivy:makepom can generate a
- IMPROVEMENT: added support for 'gzip' and 'deflate' HTTP Content-Encoding (IVY-1194)
- IMPROVEMENT: retrieve doesn't retrive files if the current one is more recent (IVY-1044)
- IMPROVEMENT: better diagnostics when reporting bad ivy file in cache (IVY-1190)
- IMPROVEMENT: Support changing="true" for inline retrieve (IVY-1180)
- IMPROVEMENT: Enhance
- IMPROVEMENT: Ivy doesn't support Maven 2.0.9 'import' scope (IVY-807)
- IMPROVEMENT: resolver attribute for listmodules task (IVY-1057)
- IMPROVEMENT: discover 'src' sources in maven repos (IVY-1138)
- IMPROVEMENT: Trace a message when a property file referenced from the settings doesn't exixts (IVY-1074)
- IMPROVEMENT: use defaultconf in combination with defaultconfmapping (IVY-1135) (thanks to Jon Schneider)
- FIX: ApacheURLLister doesn't handle some truncated linknames properly (IVY-1232) (thanks to John Tinetti)
- FIX: Ivy cannot handle Maven pom with parents depending back on theirselfs (IVY-1225)
- FIX: artifactreport ant task doesn't honor log attribute (IVY-1212)
- FIX: XmlModuleDescriptorWriter does not write the transitive attribute (IVY-1207) (thanks to Abel Muino)
- FIX: Ivy info/extends/extendsType attribute is misspelled by XmlModuleDescriptorWriter (IVY-1203) (thanks to Jason Trump)
- FIX: The ivy-module version used by XmlModuleDescriptorWriter is hard coded to '1.0' (IVY-1199)
- FIX: makepom ignores artifact type in ivy.xml and hardcodes 'jar' in the output pom (IVY-736) (thanks to Aaron Hachez)
- FIX: Ant output wasn't always prefixed by the name of the Ivy task
- FIX: Resolved Ivy properties written to cache during ivy:resolve incorrectly represents forced revisions (IVY-1159)
- FIX: Namespace rules not properly applied to parent projects (IVY-1186)
- FIX: LatestVersionMatcher.needModuleDescriptor() does not honor custom statuses (IVY-1170) (thanks to Carl Quinn)
- FIX: Proxy authentication could fail when using commons-httpclient
- FIX: Packager resolver always extracts all files from archives even when the packaging instructions contains include tags (IVY-1179) (thanks to Stefan De Boey)
- FIX: Ivy cannot connect to URLs with '_' in their hostname
- FIX: Transitive dependencies resolutions issue when eviction is triggered (IVY-1178)
- FIX: Can't deal with [VERSION] version pattern from Maven (IVY-1177) (thanks to Richard Vowles)
- FIX: verbose/debug messages were not logged while running ivy:configure task
- FIX: ApacheURLLister does not allow directories not containing a dot on Artifactory (IVY-1175) (thanks to Anders Jacobsson)
- FIX: artifact-lock strategy could hang Ivy when resolving dynamic revisions
- FIX: Authentication won't work in some situations (IVY-1168) (thanks to Sven Walter)
- FIX: Using SFTP resolver with full pattern URL prevents use of dynamic versions (IVY-1167) (thanks to Gregory Fernandez)
- FIX: parent.groupId is not resolved in maven 2 parser (IVY-1169) (thanks to Achim Huegen)
- FIX: Creation of symlinks problematic in Windows with Cygwin 1.7 (IVY-1165)
- FIX: add ability to programmatically change default resolver (IVY-1163) (thanks to Jason Trump)
- FIX: ivy.settings.dir space escaping problem (IVY-1162)
- FIX: Ivy cannot parse alternate format for Maven MD5 files (IVY-1155)
- FIX: Ivy does not close URL connection to ivy-report.xsl properly (IVY-1152)
- FIX: Artifact report throws NPE when artifact is not in cache (IVY-1150) (thanks to Steve Jones)
- FIX: resolve fails for transitive relocated maven modules when the type of the dependency was set to 'jar'
- FIX: optional dependencies, sources and javadocs aren't resolved when a maven module is relocated
- FIX: Encountered 'multiple artifacts retrieved to same file' error when module does not have multiple artifacts (IVY-1148)
- FIX: Use of a shared DocumentBuilder causes SAXException during parallel resolutions (IVY-1147)
- FIX: metadata lock files not always deleted from cache (IVY-1145) (thanks to Jason Trump)
- FIX: FileSystem resolver with m2compatible=true throws error when publishing modules with dotted organisation names (IVY-968)
- FIX: ivy:retrieve sync="true" does nothing if first variable is optional (IVY-1142) (thanks to Andreas Axelsson)
- FIX: Latest Compatible Conflict Manager + Extra Attributes in Dependencies' IVY files == infinite loop (IVY-956)
- FIX: Resolve with Extra Attributes, Forced Dependencies causes invalid delivered ivy file (IVY-1079)
- FIX: ResolveEngine.getDependencies does not work using extra attributes (IVY-1115)
- FIX:
- FIX: IvyNodeEviction.cleanEvicted has bad comparison logic (IVY-1118)
- FIX: ChainResolver doesn't pass the specified 'checkmodified' attribute to the cache (IVY-1133)
- FIX: Ivy couldn't handle maven POMs that depend on theirselves
- FIX: SearchEngine.listModules returns MRID without extra attributes (IVY-1128) (thanks to Michael Scheetz)
- FIX: IvyBuildNumber non-deterministic behaviour (IVY-1120)
- FIX: Change spelling of 'occured' to 'occurred' (IVY-1123)
- FIX: Ivy deliver fails to replace dynamic revision when using extra attributes (IVY-1111) (thanks to Michael Scheetz)
- FIX: IbiblioResolver not always correctly configured when using JRE 1.5 (IVY-1124) (thanks to Flavio Coutinho da Costa)
- FIX: VstfpRepository.readResponse uses bad compare logic (IVY-1119) (thanks to Dave Brosius)
- FIX: URLResource does not properly support authentication (IVY-1106) (thanks to Heschi Kreinick)
- FIX: Excessive hits to missing URLs uses up all ports on Windows (IVY-1105)
- FIX: ivy parse exception when using
- FIX: Change org.apache to commons-cli at jdbc-example (IVY-1109)
- FIX: Fixed name snapshots are not updated even if they are marked as changing and the publication date is changed in repo (IVY-938)
- FIX: Cannot publish wildcard configurations other than * (IVY-1171)
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.
For the first tutorial you won't even have to install Ivy (assuming you have Ant and a JDK properly installed), and it shouldn't take more than 30 seconds.
First Tutorial
- Make sure you have ant 1.6.0 or greater and a jdk properly installed
- Copy this build file in an empty directory on your local filesystem (and make sure you name it build.xml)
- Open a console in this directory and run "ant". That's it!
OK, you've just seen how easy it is to take your first step with Ivy. Go ahead with the other tutorials, but before you do, 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 Guides you through your very first steps with ivy.
- Adjusting default settings Gives you a better understanding of the default settings and shows you how to customize them to your needs.
- Multiple Resolvers Teaches you how to configure Ivy to find its dependencies in multiple places.
- Dual Resolver Helps you configure Ivy to find ivy files in one place and artifacts in another.
- Project dependencies A starting point for using Ivy in a multi-project environment.
- Using Ivy in multiple projects environment A more complex example demonstrating the use of Ant+Ivy in a multi-project environment.
- Using Ivy Module Configurations Shows you how to use configurations in an ivy file to define sets of artifacts.
- Building a repository Shows you how to build your own enterprise repository.
Quick Start
In this tutorial, you will see one of the simplest ways to use Ivy. With no specific settings, Ivy uses the maven 2 repository to resolve the dependencies you declare in an Ivy file. Let's have a look at the content of the files involved.
You'll find this tutorial's 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="2.0">The format of this file should pretty easy to understand, but let's give some details about what is declared here. First, the root element ivy-module, with the version attribute used to tell Ivy which version of Ivy this file uses.
<info organisation="org.apache" module="hello-ivy"/>
<dependencies>
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
<dependency org="commons-cli" name="commons-cli" rev="1.0"/>
</dependencies>
</ivy-module>
Then there is an info tag, which is used to give information about the module for which we are defining dependencies. Here we define only the organization and module name. You are free to choose whatever you want for them, but we recommend avoiding spaces for both.
Finally, the dependencies section lets you define dependencies. Here this module depends on two libraries: commons-lang and commons-cli. As you can see, we use the org and name attributes to define the organization and module name of the dependencies we need. The rev attribute is used to specify the version of the module you depend on.
To know what to put in these attributes, you need to know the exact information for the libraries you depend on. Ivy uses the maven 2 repository by default, so we recommend you use mvnrepository.com to look for the module you want. Once you find it, you will have the details on how to declare the dependency in a maven POM. For instance:
<dependency>To convert this into an Ivy dependency declaration, all you have to do is use the groupId as organization, the artifactId as module name, and the version as revision. That's what we did for the dependencies in this tutorial, that is commons-lang and commons-cli. Note that having commons-lang and commons-cli as organization is not the best example of what the organization should be. It would be better to use org.apache, org.apache.commons or org.apache.commons.lang. However, this is how these modules are identified in the maven 2 repository, so the simplest way to get them is to use the details as is (you will see in Building a repository that you can use namespaces to redefine these names if you want something cleaner).
<groupId>commons-lang</groupId>
<artifactId>commons-lang</artifactId>
<version>2.0</version>
</dependency>
If you want more details on what you can do in Ivy files, you can have a look at the Ivy files reference documentation.
The build.xml file
The corresponding build file contains a set of targets, allowing you to resolve dependencies declared in the Ivy file, to compile and run the sample code, produce a report of dependency resolution, and clean the cache or the project.You can use the standard "ant -p" to get the list of available targets. Feel free to have a look at the whole file, but here is the part relevant to dependency resolution:
<project xmlns:ivy="antlib:org.apache.ivy.ant" name="hello-ivy" default="run">As you can see, it's very easy to call Ivy to resolve and retrieve dependencies: all you need if Ivy is properly installed is to define an XML namespace in your Ant file (xmlns:ivy="antlib:org.apache.ivy.ant"). Then all the Ivy ant tasks will be available in this namespace.
...
<!-- =================================
target: resolve
================================= -->
<target name="resolve" description="--> retrieve dependencies with ivy">
<ivy:retrieve />
</target>
</project>
Here we use only one task: the retrieve task. With no attributes, it will use default settings and look for a file named ivy.xml for the dependency definitions. That's exactly what we want, so we need nothing more than that.
Note that in this case we define a resolve target and call the retrieve task. This may sound confusing, actually the retrieve task performs a resolve (which resolves dependencies and downloads them to a cache) followed by a retrieve (a copy of those file to a local project directory). Check the How does it work ? page for details about that.
Running the project
OK, now that we have seen the files involved, let's run the sample to see what happens. Open a shell (or command line) window, and enter the hello-ivy example directory.Then, at the command prompt, run ant:
[ivy@apache:/ivy/hello-ivy]$ ant
Buildfile: /ivy/hello-ivy/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#hello-ivy;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in public
[ivy:retrieve] found commons-cli#commons-cli;1.0 in public
[ivy:retrieve] found commons-logging#commons-logging;1.0 in public
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0-javadoc.jar ...
[ivy:retrieve] ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:retrieve] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (467kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar(javadoc) (3697ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] ............................................................................................................................................................................................................................................................................................................................................... (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar (1997ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0-sources.jar ...
[ivy:retrieve] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ (245kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar(source) (3495ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-cli/commons-cli/1.0/commons-cli-1.0-javadoc.jar ...
[ivy:retrieve] ........................................................................................................................................................................................... (92kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-cli#commons-cli;1.0!commons-cli.jar(javadoc) (2137ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-cli/commons-cli/1.0/commons-cli-1.0.jar ...
[ivy:retrieve] ......................................................... (29kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-cli#commons-cli;1.0!commons-cli.jar (1404ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-cli/commons-cli/1.0/commons-cli-1.0-sources.jar ...
[ivy:retrieve] ...................................................................................................... (48kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-cli#commons-cli;1.0!commons-cli.jar(source) (1529ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-logging/commons-logging/1.0/commons-logging-1.0.jar ...
[ivy:retrieve] ........................................... (21kB)
[ivy:retrieve] ... (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-logging#commons-logging;1.0!commons-logging.jar (2199ms)
[ivy:retrieve] :: resolution report :: resolve 9095ms :: artifacts dl 16520ms
[ivy:retrieve] :: evicted modules:
[ivy:retrieve] commons-lang#commons-lang;1.0 by [commons-lang#commons-lang;2.0] in [default]
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 4 | 3 | 3 | 1 || 7 | 7 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#hello-ivy
[ivy:retrieve] confs: [default]
[ivy:retrieve] 7 artifacts copied, 0 already retrieved (1069kB/78ms)
run:
[mkdir] Created dir: /ivy/hello-ivy/build
[javac] /ivy/hello-ivy/build.xml:53: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/hello-ivy/build
[java] standard message : hello ivy !
[java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !
BUILD SUCCESSFUL
Total time: 28 seconds
What happened ?
Without any settings, Ivy retrieves files from the maven 2 repository. That's what happened here.The resolve task has found the commons-lang and commons-cli modules in the maven 2 repository, identified that commons-cli depends on commons-logging and so resolved it as a transitive dependency. Then Ivy has downloaded all corresponding artifacts in its cache (by default in your user home, in a .ivy2/cache directory). Finally, the retrieve task copies the resolved jars from the ivy cache to the default library directory of the project: the lib dir (you can change this easily by setting the pattern attribute on the retrieve task).
You might say that the task took a long time just to write out a "Hello Ivy!" message. But remember that a lot of time was spent downloading the required files from the web. Let's try to run it again:
[ivy@apache:/ivy/hello-ivy]$ ant
Buildfile: /ivy/hello-ivy/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#hello-ivy;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in public
[ivy:retrieve] found commons-cli#commons-cli;1.0 in public
[ivy:retrieve] found commons-logging#commons-logging;1.0 in public
[ivy:retrieve] :: resolution report :: resolve 343ms :: artifacts dl 16ms
[ivy:retrieve] :: evicted modules:
[ivy:retrieve] commons-lang#commons-lang;1.0 by [commons-lang#commons-lang;2.0] in [default]
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 4 | 0 | 0 | 1 || 7 | 0 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#hello-ivy
[ivy:retrieve] confs: [default]
[ivy:retrieve] 0 artifacts copied, 7 already retrieved (0kB/15ms)
run:
[javac] /ivy/hello-ivy/build.xml:53: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[java] standard message : hello ivy !
[java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !
BUILD SUCCESSFUL
Total time: 1 second
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.
As you can see, using Ivy to resolve dependencies stored in the maven 2 repository is extremely easy. Now you can go on with the next tutorials to learn more about how to use module configurations which is a very powerful Ivy specific feature. Other tutorials are also available where you will learn how to use Ivy settings to leverage a possibly complex enterprise repository. It may also be a good time to start reading the reference documentation, and especially the introduction material which gives a good overview of Ivy. The best practices page is also a must read to start thinking about how to use Ant+Ivy to build a clean and robust build system.
Adjusting default settings
Ivy comes bundled with some default settings which makes it pretty simple to use in a typical environment. This tutorial, which is close to a reference document, explains what those default settings are and how they can be adjusted to your needs.
To fully understand the concept of settings and what you can do with them, we suggest reading other tutorials related to settings (like Multiple Resolvers and Dual Resolver) or the Settings Files reference documentation.
Concept
The default settings include 3 types of repositories:- local a repository which is private to the user.
- shared a repository which is shared between all the members of a team
- public a public repository on which most modules, and especially third party modules, can be found
Now let's describe each of these repository concepts in more detail. We will describe how they are set up physically later.
Local
The local repository is particularly useful when you want to do something without being disturbed 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 what is available in others.For instance, if you have a module declaring a dependency on the module foo with a revision of 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 publishes 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 repository, 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's private modules, and it's also a place where you can put modules not available in the public repository (sun jars, for instance). You can also put modules here that are simply inaccurate in a public repository (bad or incomplete module descriptors for instance).Note that modules can be split across the shared repository and the public one: For example, you can have the module descriptor in the shared repository and the artifacts in the public one.
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 use the same root in your filesystem. Referenced as ${ivy.default.ivy.user.dir}, this is by default the directory .ivy2 in your user home.
Note that several things can be done by setting Ivy variables. To set them without defining your own ivysettings.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
<target name="resolve">Next we will show you how to override default values for the different kinds of repositories. Note that you can find what the default values are below in the details of the default settings.
<property name="ivy.default.ivy.user.dir" value="/path/to/ivy/user/dir"/>
<ivy:resolve />
</target>
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. 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.patterngives the pattern to find ivy files
ivy.local.default.artifact.patterngives 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 network shared directory. You can use theivy.shared.default.rootvariable to specify a different directory. Moreover, you can also configure the layout with variables similar to the ones used for the local repository:
ivy.shared.default.ivy.patterngives the pattern to find ivy files
ivy.shared.default.artifact.patterngives 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 ibiblio in m2 compatible mode (in other words, the maven 2 public repository).This repository has the advantage of providing a lot of modules, with metadata for most of them. The quality of metadata is not always perfect, but it's a very good start to use a tool like Ivy and benefit from the power of transitive dependency management.
Despite its ease of use, we suggest reading the Best practices to have a good understanding of the pros and cons of using a public unmanaged repository before depending on such a repository for your enterprise build system.
In 1.4 version Ivy was using ivyrep as the default resolver, if you want to restore this, set
ivy.14.compatible=true as an ant property
Going further
OK, so we have seen how to easily change the settings of the three main repositories. But what if my shared repository is on a web server? What if you don't want to use maven 2 repository as the public repository? What if ...No problem, Ivy is very flexible and can be configured with specific settings to match your needs and environment. But before considering writing your own settings from scratch, we suggest reading the following where you will learn how to leverage a part of the default settings and adjust the rest.
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 ivysettings.xml which is packaged in the Ivy jar. Here is this settings file:
<ivysettings>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 ivysettings and easily benefit from the rest. For example, if you want to define your own public resolver, you will just have to configure Ivy with an ivysettings like the following:
<settings defaultResolver="default"/>
<include url="${ivy.default.settings.dir}/ivysettings-public.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-local.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/>
</ivysettings>
<ivysettings>Note that only the ivysettings-public.xml inclusion has changed to include a homemade public resolver. Note also that this can be used like that thanks to the fact that ${ivy.default.settings.dir} is a variable which is always set to the place where Ivy's default settings files are (i.e. packaged in the jar).
<settings defaultResolver="default"/>
<include url="http://myserver/ivy/myivysettings-public.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-local.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/>
<include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/>
</ivysettings>
To finish this example, you have to write your own ivysettings file (that you will make available at http://myserver/ivy/myivysettings-public.xml in this example) for defining your own public resolver. For instance:
<ivysettings>Now the last thing you will need in order to properly take advantage of the default settings is the content of each included ivysettings file:
<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>
</ivysettings>
ivysettings-public.xml
<ivysettings>ivysettings-shared.xml
<resolvers>
<ibiblio name="public" m2compatible="true"/>
</resolvers>
</ivysettings>
<ivysettings>ivysettings-local.xml
<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>
</ivysettings>
<ivysettings>ivysettings-main-chain.xml
<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>
</ivysettings>
<ivysettings>ivysettings-default-chain.xml
<resolvers>
<chain name="main" dual="true">
<resolver ref="shared"/>
<resolver ref="public"/>
</chain>
</resolvers>
</ivysettings>
<ivysettings>There you go, you should have enough clues to configure Ivy the way you want. Check the settings documentation to see if what you want to do is possible, and go ahead!
<resolvers>
<chain name="default" returnFirst="true">
<resolver ref="local"/>
<resolver ref="main"/>
</chain>
</resolvers>
</ivysettings>
Multiple Resolvers
This tutorial is an example of how modules can be retrieved by multiple resolvers. Using multiple resolvers can be useful in many contexts. For example:
- separating integration builds from releases
- using a public repository for third party modules and a private one for internal modules
- use a repository for storing modules which are not accurate in an unmanaged public repository
- use a local repository to expose builds made on one developer's station
In our example, we will simply show you how to use two resolvers, one on a local repository and one using the maven2 repository.
project description
the project: chained-resolvers
The project is very simple and contains only one simple class: example.Hello.It depends on two libraries: Apache's commons-lang and a custom library named test (sources are included in test-1.0jar 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
<ivy-module version="1.0">As we'd expect, the ivy file declares this module to be dependent on the two libraries it uses: 'commons-lang' and 'test'. Note that we didn't specify the org for the dependency 'test'. When we exclude org, Ivy assumes it is in the same org as the declaring module. (i.e. 'org.apache').
<info organisation="org.apache" module="chained-resolvers"/>
<dependencies>
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
<dependency name="test" rev="1.0"/>
</dependencies>
</ivy-module>
the ivy settings
The settings are defined in the ivysettings.xml file located in the settings directory of the project. Below are its contents, followed by an explanation of what it's doing.<ivysettings>
<settings defaultResolver="chain-example"/>
<resolvers>
<chain name="chain-example">
<filesystem name="libraries">
<artifact pattern="${ivy.settings.dir}/repository/[artifact]-[revision].[ext]" />
</filesystem>
<ibiblio name="ibiblio" m2compatible="true" />
</chain>
</resolvers>
</ivysettings>
the settings tag
This tag initializes Ivy with some parameters. Here only one parameter is set, the name of the resolver to use by default.the resolvers tag
The resolvers section defines the list of resolvers that Ivy will use to locate artifacts. In our example, we have only one resolver named "chain-example", which is unique in that it defines a list (hence a chain) of resolvers.The resolvers in this chain are:
- libraries : It is a filesystem resolver, so looks at a directory structure to retrieve the artifacts. This one is configured to look in the repository sub directory of the directory that contains the ivysettings.xml file.
- ibiblio : It looks in the ibiblio maven repository to retrieve the artifacts.
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: antThis will clean up the entire project directory tree and Ivy cache. You can do this each time you want to clean up this example.
In almost all examples, we provide a clean target as default target. Since most examples use the same Ivy cache, you will clean the whole Ivy cache each time you call this target.
Cleaning the Ivy cache is something you can do without fear (except performance): it's only a cache, so everything can be (and should be) obtained again from repositories. This may sound strange to those coming from maven 2 land. But remember that in Ivy, the cache is not a local repository and the two are completely isolated.
Cleaning the Ivy cache is something you can do without fear (except performance): it's only a cache, so everything can be (and should be) obtained again from repositories. This may sound strange to those coming from maven 2 land. But remember that in Ivy, the cache is not a local repository and the two are completely isolated.
step 3: run the project
Go to chained-resolvers project directory. And simply run ant.
[ivy@apache:/ivy/chained-resolvers/chainedresolvers-project]$ ant
Buildfile: /ivy/chained-resolvers/chainedresolvers-project/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/chained-resolvers/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#chained-resolvers;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in ibiblio
[ivy:retrieve] found org.apache#test;1.0 in libraries
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] ........................................................................................................................................................................................................................................................................................................................................... (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar (2745ms)
[ivy:retrieve] downloading /ivy/chained-resolvers/settings/repository/test-1.0.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#test;1.0!test.jar (16ms)
[ivy:retrieve] :: resolution report :: resolve 4836ms :: artifacts dl 2761ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 2 | 2 | 1 | 0 || 2 | 2 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#chained-resolvers
[ivy:retrieve] confs: [default]
[ivy:retrieve] 2 artifacts copied, 0 already retrieved (166kB/62ms)
run:
[mkdir] Created dir: /ivy/chained-resolvers/chainedresolvers-project/build
[javac] /ivy/chained-resolvers/chainedresolvers-project/build.xml:58: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/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: 10 seconds
Also notice that the 'run' Ant target succeeded in using both commons-lang.jar coming from the ibiblio repository and test.jar coming from the local repository.
Going further
This very simple example helps us see how to set up two resolvers in a chain. The chain resolver's reference documentation is available for those who would like to know all the features offered by this resolver.Below are a few more interesting things worth knowing about chain resolvers. After reading them, go ahead and try tweaking this example using your new wealth of knowledge!
- a chain is not limited to two nested resolvers, you can use as many as you want
- by setting returnFirst="true", you can have a chain which stops as soon as it has found a result for a given module
- by setting dual="true", the full chain will be used both for module descriptors and artifacts, while setting dual="false", the resolver in the chain which found the module descriptor (if any) is also used for artifacts
Dual Resolver
In some cases, your module descriptions (i.e. Ivy files, maven poms) are located separately from the module artifacts (i.e. jars). So what can you do about it?
Use a Dual resolver! And this tutorial will show you how.
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:
- settings: contains the ivy settings 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 simple 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
<ivy-module version="1.0">As you can see, nothing special here... Indeed, Ivy's philosophy is to keep ivy files independent of the way dependencies are resolved.
<info organisation="org.apache" module="hello-ivy"/>
<dependencies>
<dependency org="commons-httpclient" name="commons-httpclient" rev="2.0.2"/>
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
</dependencies>
</ivy-module>
the ivy settings
The ivy settings are defined in the ivysettings.xml file located in the settings directory. Here is what it contains, followed by an explanation.<ivysettings>Here we configured 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" or "metadata" resolver of the dual resolver, and the second one is what is called the "artifact" resolver. It is important that the dual resolver has exactly two sub resolvers in this given order.
<settings defaultResolver="dual-example"/>
<resolvers>
<dual name="dual-example">
<filesystem name="ivys">
<ivy pattern="${ivy.settings.dir}/../repository/[module]-ivy-[revision].xml" />
</filesystem>
<ibiblio name="ibiblio" m2compatible="true" usepoms="false" />
</dual>
</resolvers>
</ivysettings>
The metadata resolver, here a filesystem one, is used only to find module descriptors, in this case Ivy files. The setting shown here tells Ivy that all ivy files are in the repository directory, named with the pattern: [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. This file matches the pattern, so it will be found by the resolver.
The artifact resolver is simply an ibiblio one, configured in m2compatible mode to use the maven 2 repository, with usepoms="false" to make sure it won't use maven 2 metadata. Note that this isn't necessary, since the second resolver in a dual resolver (the artifact resolver) is never asked to find module metadata.
walkthrough
step 1 : preparation
Open a DOS or shell window, and go to the dual directory.step 2 : clean up
On the prompt type : antThis will clean up the entire project directory tree (compiled classes and retrieved libs) and the Ivy cache. You can run this each time you want to clean up this example.
step 3 : run the project
Go to the project directory. And simply run ant.
[ivy@apache:/ivy/dual/project]$ ant
Buildfile: /ivy/dual/project/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dual/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#hello-ivy;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-httpclient#commons-httpclient;2.0.2 in ivys
[ivy:retrieve] found commons-logging#commons-logging;1.0.4 in ibiblio
[ivy:retrieve] found commons-lang#commons-lang;2.0 in ibiblio
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-httpclient/commons-httpclient/2.0.2/commons-httpclient-2.0.2.jar ...
[ivy:retrieve] .................................................................................................................................................................................................................................................................................................................................................................................................................................................... (220kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-httpclient#commons-httpclient;2.0.2!commons-httpclient.jar (3853ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] ................................................................................................................................................................................................................................................................................................................................................ (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar (1826ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-logging/commons-logging/1.0.4/commons-logging-1.0.4.jar ...
[ivy:retrieve] .......................................................................... (37kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-logging#commons-logging;1.0.4!commons-logging.jar (1341ms)
[ivy:retrieve] :: resolution report :: resolve 1076ms :: artifacts dl 7036ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 3 | 3 | 1 | 0 || 3 | 3 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#hello-ivy
[ivy:retrieve] confs: [default]
[ivy:retrieve] 3 artifacts copied, 0 already retrieved (423kB/47ms)
run:
[mkdir] Created dir: /ivy/dual/project/build
[javac] /ivy/dual/project/build.xml:58: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/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: 10 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="commons-httpclient"
module="commons-httpclient"
revision="2.0.2"
status="release"
publication="20041010174300"/>
<dependencies>
<dependency org="commons-logging" name="commons-logging" rev="1.0.4" conf="default"/>
</dependencies>
</ivy-module>
So everything seemed to work. The ivy file was found in the repository directory and the artifacts have been downloaded from ibiblio.
This kind of setup can be useful if you don't want to rely on the maven 2 repository for metadata, or if you want to take full advantage of Ivy files for some or all modules. Combining chain and dual resolvers should give you enough flexibility to meet almost any requirement.
For full details about the dual resolver, have a look at the corresponding reference documentation.
Project dependencies
This tutorial will show you how to use Ivy when one of your projects depends on another.
For our example, we will have two projects, depender and dependee, where the depender project uses/requires the dependee project. This example will help illustrate two things about Ivy:
- that dependencies defined by parent projects (dependee) will automatically be retrieved for use by child projects (depender)
- that child projects can retrieve the "latest" version of the dependee project
projects used
dependee
The dependee 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
- build.xml: the ant build file for the project
- ivy.xml: the project ivy file
- src\standalone\Main.java: the only class of the project
<ivy-module version="1.0">The ivy file declares only one dependency, that being the apache commons-lang library.
<info organisation="org.apache" module="dependee"/>
<dependencies>
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
</dependencies>
</ivy-module>
depender
The depender project is very simple as well. It declares only one dependency on the latest version of the dependee project, and it contains only one class, depending.Main, which does 2 things:- gets the version of the standalone project by calling standalone.Main.getVersion()
- transforms a string by calling standalone.Main.capitalizeWords(str)
<ivy-module version="1.0">
<info organisation="org.apache" module="depender"/>
<dependencies>
<dependency name="dependee" rev="latest.integration" />
</dependencies>
</ivy-module>
settings
The Ivy settings are defined in two files located in the settings directory:- ivysettings.properties: a property file
- ivysettings.xml: the file containing the settings
<ivysettings>The file contains four main tags: properties, settings, resolvers and modules.
<properties file="${ivy.settings.dir}/ivysettings.properties"/>
<settings defaultCache="${ivy.settings.dir}/ivy-cache" defaultResolver="libraries"/>
<resolvers>
<filesystem name="projects">
<artifact pattern="${repository.dir}/[artifact]-[revision].[ext]" />
<ivy pattern="${repository.dir}/[module]-[revision].xml" />
</filesystem>
<ibiblio name="libraries" m2compatible="true" usepoms="false" />
</resolvers>
<modules>
<module organisation="org.apache" name="dependee" resolver="projects"/>
</modules>
</ivysettings>
properties
This tag loads some properties for the Ivy process, just like Ant does.settings
This tag initializes some parameters for the Ivy process. In this case, the directory that Ivy will use to cache artifacts will be in a sub directory called ivy-cache of the directory containing the ivysettings.xml file itself.The second parameter, tells Ivy to use a resolver named "libraries" as its default resolver. More information can be found in the settings reference documentation.
resolvers
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 by locating them on the local filesystem.
The ibiblio resolver called "libraries" is able to find dependencies on the maven 2 repository, but doesn't use maven poms.
modules
The modules tag allows you to configure which resolver should be used for which module. Here the setting tells Ivy to use the "projects" resolver for all modules having an organisation of org.apache and module name of dependee. This actually corresponds to only one module, but a regular expression could be used, or many other types of expressions (like glob expressions).All other modules (i.e. all modules but org.apache#dependee), will use the default resolver ("libraries").
walkthrough
step 1: preparation
Open a DOS or shell window, and go to the src/example/dependence directory.step 2: clean directory tree
On the prompt type: ant This will clean up the entire project directory tree. You can do this each time you want to clean up this example.step 3: publication of dependee project
Go to dependee directory and publish the project
[ivy@apache:/ivy/dependence/dependee]$ ant publish
Buildfile: /ivy/dependence/dependee/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dependence/settings/ivysettings.xml
[ivy:retrieve] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/dependence/settings/ivysettings.xml)
[ivy:retrieve] :: resolving dependencies :: org.apache#dependee;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in libraries
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] ...................................................................................................................................................................................................................................................................................................................................
[ivy:retrieve] (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-lang#commons-lang;2.0!commons-lang.jar (3260ms)
[ivy:retrieve] :: resolution report :: resolve 530ms :: artifacts dl 3260ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 1 | 1 | 0 | 0 || 1 | 1 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#dependee
[ivy:retrieve] confs: [default]
[ivy:retrieve] 1 artifacts copied, 0 already retrieved (165kB/31ms)
compile:
[mkdir] Created dir: /ivy/dependence/dependee/build/classes
[javac] /ivy/dependence/dependee/build.xml:60: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/dependence/dependee/build/classes
jar:
[propertyfile] Creating new property file: /ivy/dependence/dependee/build/classes/version.properties
[jar] Building jar: /ivy/dependence/dependee/build/dependee.jar
publish:
[ivy:publish] :: delivering :: org.apache#dependee;working@apache :: 1 :: release :: Thu Sep 23 23:15:49 CEST 2010
[ivy:publish] delivering ivy file to /ivy/dependence/dependee/build/ivy.xml
[ivy:publish] :: publishing :: org.apache#dependee
[ivy:publish] published dependee to /ivy/dependence/settings/repository/dependee-1.jar
[ivy:publish] published ivy to /ivy/dependence/settings/repository/dependee-1.xml
[echo] project dependee released with version 1
BUILD SUCCESSFUL
Total time: 6 seconds
- the project depends on 1 library (1 artifact)
- the library was not in the Ivy cache and so was downloaded (1 downloaded)
- the project has been released under version number 1
- 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 its 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 makes a call to the deliver task which delivers a resolved ivy file to this destination.
- the publication of artifact 'dependee' and its resolved ivy file to the repository. Both are just copies of the files found in the current project, or more precisely, those in the build directory. This is because the artifactspattern has been set to ${build.dir}/[artifact].[ext], so the dependee artifact is found at build/dependee.jar and the 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\dependee-1.jar and to repository\dependee-1.xml, respecting the artifact and ivy patterns of our settings (see above).
step 4: running the depender project
Go to directory depender and run ant
[ivy@apache:/ivy/dependence/depender]$ ant
Buildfile: /ivy/dependence/depender/build.xml
clean:
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dependence/settings/ivysettings.xml
[ivy:retrieve] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/dependence/settings/ivysettings.xml)
[ivy:retrieve] :: resolving dependencies :: org.apache#depender;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found org.apache#dependee;1 in projects
[ivy:retrieve] [1] org.apache#dependee;latest.integration
[ivy:retrieve] found commons-lang#commons-lang;2.0 in libraries
[ivy:retrieve] downloading /ivy/dependence/settings/repository/dependee-1.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#dependee;1!dependee.jar (16ms)
[ivy:retrieve] :: resolution report :: resolve 343ms :: artifacts dl 47ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 2 | 1 | 1 | 0 || 2 | 1 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#depender
[ivy:retrieve] confs: [default]
[ivy:retrieve] 2 artifacts copied, 0 already retrieved (167kB/47ms)
compile:
[mkdir] Created dir: /ivy/dependence/depender/build/classes
[javac] /ivy/dependence/depender/build.xml:71: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/dependence/depender/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
- 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 retrieved version 1 of the project "dependee". The call to standalone.Main.getVersion() has returned 1. If you look in the depender/lib directory, you should see dependee-1.jar which is the version 1 artifact of the project "dependee"
- the call to standalone.Main.capitalizeWords(str) succeed, which means that the required library was in the classpath. If you look at the lib directory, you will see that the library commons-lang-2.0.jar was also retrieved. This library was declared as a dependency of the "dependee" project, so Ivy retrieves it (transitively) along with the dependee artifact.
step 5: new version of dependee project
Like we did before in step 3, publish the dependee project again. This will result in a new version of the project being published.
[ivy@apache:/ivy/dependence/dependee]$ ant publish
Buildfile: /ivy/dependence/dependee/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dependence/settings/ivysettings.xml
[ivy:retrieve] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/dependence/settings/ivysettings.xml)
[ivy:retrieve] :: resolving dependencies :: org.apache#dependee;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found commons-lang#commons-lang;2.0 in libraries
[ivy:retrieve] :: resolution report :: resolve 109ms :: artifacts dl 0ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 1 | 0 | 0 | 0 || 1 | 0 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#dependee
[ivy:retrieve] confs: [default]
[ivy:retrieve] 0 artifacts copied, 1 already retrieved (0kB/0ms)
compile:
[javac] /ivy/dependence/dependee/build.xml:60: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
jar:
[propertyfile] Updating property file: /ivy/dependence/dependee/build/classes/version.properties
[jar] Building jar: /ivy/dependence/dependee/build/dependee.jar
publish:
[delete] Deleting: /ivy/dependence/dependee/build/ivy.xml
[ivy:publish] :: delivering :: org.apache#dependee;working@apache :: 2 :: release :: Thu Sep 23 23:15:56 CEST 2010
[ivy:publish] delivering ivy file to /ivy/dependence/dependee/build/ivy.xml
[ivy:publish] :: publishing :: org.apache#dependee
[ivy:publish] published dependee to /ivy/dependence/settings/repository/dependee-2.jar
[ivy:publish] published ivy to /ivy/dependence/settings/repository/dependee-2.xml
[echo] project dependee released with version 2
BUILD SUCCESSFUL
Total time: 1 second
Let's look at it:
I:\dependee>dir ..\settings\repository /w
[.] [..] dependee-1.jar dependee-1.xml dependee-2.jar dependee-2.xml
I:\dependee>
step 6: get the new version in depender project
What should we expect if we run the depender project again? It should:- retrieve version 2 as the latest.integration version of the dependee project
- display version 2 of dependee project
[ivy@apache:/ivy/dependence/depender]$ ant
Buildfile: /ivy/dependence/depender/build.xml
clean:
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: file = /ivy/dependence/settings/ivysettings.xml
[ivy:retrieve] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/dependence/settings/ivysettings.xml)
[ivy:retrieve] :: resolving dependencies :: org.apache#depender;working@apache
[ivy:retrieve] confs: [default]
[ivy:retrieve] found org.apache#dependee;1 in projects
[ivy:retrieve] [1] org.apache#dependee;latest.integration
[ivy:retrieve] found commons-lang#commons-lang;2.0 in libraries
[ivy:retrieve] :: resolution report :: resolve 94ms :: artifacts dl 15ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 2 | 0 | 0 | 0 || 2 | 0 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#depender
[ivy:retrieve] confs: [default]
[ivy:retrieve] 2 artifacts copied, 0 already retrieved (167kB/31ms)
compile:
[mkdir] Created dir: /ivy/dependence/depender/build/classes
[javac] /ivy/dependence/depender/build.xml:71: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/dependence/depender/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: 2 seconds
Using Ivy in multiple projects environment
In the previous tutorial, you saw 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 of the code for this tutorial is available in the src/example/multi-project directory of the Ivy distribution.
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
But this gives a simple understanding of how Ant+Ivy can be used to develop an application divided in multiple modules.
Now, here is how these modules relate to each other:
click to enlarge
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 is 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 each containing:
- 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="org.apache.ivy.example"
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="commons-collections" name="commons-collections" rev="3.1" conf="core->default" />
<dependency org="commons-cli" name="commons-cli" rev="1.0" conf="standalone->default" />
</dependencies>
</ivy-module>
<project name="find" default="compile">
<property file="build.properties"/>
<import file="${common.dir}/common.xml"/>
</project>
projects.dir = ${basedir}/..
wkspace.dir = ${projects.dir}/..
common.dir = ${wkspace.dir}/common
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 the module's build files only import the common build file, and define their dependencies in their ivy files (which you should begin to be familiar with).
So, here are some aspects of this common build file:
ivy settings
<!-- setup ivy default configuration with some custom info -->This declaration configures Ivy by only setting two properties: the location for the local repository and the location for the shared repository. It's the only settings done here, since Ivy is configured by default to work in a team environment (see default settings 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 settings tutorial to see how to use something really different).
<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 ivysettings file
<ivy:settings file="${common.dir}/ivysettings.xml" id="ivy.instance" />
-->
Commented out you can see how the settings would have been done if the default setting wasn't OK for our purpose.
resolve dependencies
<target name="resolve" depends="clean-lib, load-ivy" description="--> resolve and retrieve dependencies with ivy">You should begin to be familiar with using Ivy this way. We call resolve explicitly to use the ivy file configured (the default would have been fine), and then call retrieve to copy resolved dependencies artifacts from the cache to a local lib directory. The pattern is also used to name the artifacts in the lib dir with their name and extension only (without revision), this is easier to use with an IDE, as the IDE configuration won't change when the artifacts version change.
<mkdir dir="${lib.dir}"/> <!-- not usually necessary, ivy creates the directory IF there are dependencies -->
<!-- the call to resolve is not mandatory, retrieve makes an implicit call if we don't -->
<ivy:resolve file="${ivy.file}"/>
<ivy:retrieve pattern="${lib.dir}/[artifact].[ext]" />
</target>
ivy-new-version
<target name="ivy-new-version" depends="load-ivy" unless="ivy.new.revision">This target is used to ask Ivy to find a new version for a module. To get details about the module we are dealing with, we pull information out of the ivy file by using the ivy:info task. Then the buildnumber task is used to get a new revision, based on a prefix we set with a property, by default it will be 1.0-dev-b (have a look at the default value for module.version.target in the common/build.properties file). Each module built by this common build file could easily override this by either setting a different module.version.target in its module specific build.properties, or even overriding module.version.prefix. To get the new revision, Ivy scans the repository to find the latest available version with the given prefix, and then increments this version by 1.
<!-- default module version prefix value -->
<property name="module.version.prefix" value="${module.version.target}-dev-b" />
<!-- asks Ivy for an available version number -->
<ivy:info file="${ivy.file}" />
<ivy:buildnumber
organisation="${ivy.organisation}" module="${ivy.module}"
revision="${module.version.prefix}" defaultBuildNumber="1" revSep=""/>
</target>
publish
<target name="publish" depends="clean-build, jar" description="--> publish this project in the ivy repository">This target publishes the module to the shared repository, with the revision found in the version property, which is set by other targets (based on ivy-new-version we have seen above). It can be used when a module reaches a specific milestone, or whenever you want the team to benefit from a new version of the module.
<ivy:publish artifactspattern="${build.dir}/[artifact].[ext]"
resolver="shared"
pubrevision="${version}"
status="release"
/>
<echo message="project ${ant.project.name} released with version ${version}" />
</target>
publish-local
<target name="publish-local" depends="local-version, jar" description="--> publish this project in the local ivy repository">This is very similar to the publish task, except that this publishes the revision to 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.
<ivy:publish artifactspattern="${build.dir}/[artifact].[ext]"
resolver="local"
pubrevision="${version}"
pubdate="${now}"
status="integration"
forcedeliver="true"
/>
<echo message="project ${ant.project.name} published locally with version ${version}" />
</target>
clean-local
<target name="clean-local" description="--> cleans the local repository for the current module">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, or discard your local changes and want to take advantage of a new version from the team.
<delete dir="${ivy.local.default.root}/${ant.project.name}"/>
</target>
report
<target name="report" depends="resolve" description="--> generates a report of dependencies">Generates both an html report and a graphml report.
<ivy:report todir="${build.dir}"/>
</target>
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!
Playing with the projects
You can play with this tutorial by using regular Ant commands. Begin in the base directory of the tutorial (src/example/multi-project), and run ant -p:[ivy@apache:/ivy/multi-project]$ ant -p Buildfile: /ivy/multi-project/build.xml Main targets: clean clean tutorial: delete repository, ivy cache, and all projects clean-all clean all projects publish-all compile, jar and publish all projects in the right order
You will see that Ivy calls the publish target on all the modules, following the order of the dependencies, so that a dependee is always built and published before its depender. Feel free to make changes in the source code of a module (changing a method name for instance) and in the module using the method, then call publish-all to see how the change in the dependee is compiled first, published, and then available to the depender which can compile successfully.
Then you can go in one of the example project directories (like projects/find for instance), and run ant -p:
[ivy@apache:/ivy/multi-project/projects/find]$ ant -p Buildfile: /ivy/multi-project/projects/find/build.xml Main targets: clean --> clean the project clean-build --> clean the project built files clean-lib --> clean the project libraries directory (dependencies) clean-local --> cleans the local repository for the current module compile --> compile the project jar --> make a jar file for this project publish --> publish this project in the ivy repository publish-local --> publish this project in the local ivy repository report --> generates a report of dependencies resolve --> resolve and retrieve dependencies with ivy run --> compile and run the project Default target: compile
By now, you should be pretty familiar with multi-project development with Ivy. We hope you will appreciate its power and flexibility! And these tutorials are only the beginning of your journey with Ivy, browse the reference documentation to learn more about the features, subscribe to the mailing lists to share your experience and ask questions with the community, browse the source code, open jira issues, submit patches, join in and help make Ivy the best of dependency management tools!
Using Ivy Module Configurations
This tutorial introduces the use of module configurations in ivy files. Ivy module configurations are 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 poured :-)
More seriously, configurations in Ivy can be better understood as views on your module, and you will see how they can be used effectively here.
Reference documentation on configurations can be found here and here.
Introduction
Source code is available in src/example/configurations/multi-projects.We have two projects :
- filter-framework is a library that defines an api to filter String arrays and two implementations of this api.
- myapp is a very small app that uses filter-framework.
The filter-framework library project produces 3 artifacts:
- the api jar,
- an implementation jar with no external dependencies,
- a second implementation jar that needs commons-collections to perform.
The application only needs the api jar to compile and can use either of the two implementations at runtime.
The library project
The first project we'll look at in this tutorial is filter-framework. In order to have a fine-grained artifacts publication definition, we defined several configurations, each which maps to a set of artifacts that other projects can make use of.The ivy.xml file
<ivy-module version="1.0">
<info organisation="org.apache" 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="commons-collections" 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 4 configurations, with 3 being public and 1 private. (the junit dependency for testing).The 2 implementation configurations, homemade-impl and cc-impl extend the api configuration so that all artifacts defined in api will also be part of the extending configuration.
In the publications tag, we defined the artifacts we produce (jars in this case) and we assign them to a configuration. When others use our library they will have a flexible way to ask for what they need.
See it in action
The filter-framework project is built using Ant. Open a shell in the root directory of the project and type ant.
[ivy@apache:/ivy/configurations/multi-projects/filter-framework]$ ant
Buildfile: /ivy/configurations/multi-projects/filter-framework/build.xml
clean:
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#filter-framework;working@apache
[ivy:retrieve] confs: [api, homemade-impl, cc-impl, test]
[ivy:retrieve] found commons-collections#commons-collections;3.1 in public
[ivy:retrieve] found junit#junit;3.8 in public
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-collections/commons-collections/3.1/commons-collections-3.1.jar ...
[ivy:retrieve] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
[ivy:retrieve] ...................................................................................................................................................................................................................................................................................................................................................................................... (546kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] commons-collections#commons-collections;3.1!commons-collections.jar (3432ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/junit/junit/3.8/junit-3.8.jar ...
[ivy:retrieve] .......................................................................................................................................................................................................................................... (118kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] junit#junit;3.8!junit.jar (2013ms)
[ivy:retrieve] :: resolution report :: resolve 7286ms :: artifacts dl 5460ms
---------------------------------------------------------------------
| | 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 | 2 | 0 || 2 | 2 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#filter-framework
[ivy:retrieve] confs: [api, homemade-impl, cc-impl, test]
[ivy:retrieve] 3 artifacts copied, 0 already retrieved (1211kB/63ms)
build:
[mkdir] Created dir: /ivy/configurations/multi-projects/filter-framework/build
[mkdir] Created dir: /ivy/configurations/multi-projects/filter-framework/distrib
[javac] /ivy/configurations/multi-projects/filter-framework/build.xml:57: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 4 source files to /ivy/configurations/multi-projects/filter-framework/build
[javac] Note: Some input files use unchecked or unsafe operations.
[javac] Note: Recompile with -Xlint:unchecked for details.
[jar] Building jar: /ivy/configurations/multi-projects/filter-framework/distrib/filter-api.jar
[jar] Building jar: /ivy/configurations/multi-projects/filter-framework/distrib/filter-hmimpl.jar
[jar] Building jar: /ivy/configurations/multi-projects/filter-framework/distrib/filter-ccimpl.jar
test:
[mkdir] Created dir: /ivy/configurations/multi-projects/filter-framework/build/test-report
[mkdir] Created dir: /ivy/configurations/multi-projects/filter-framework/build/test-classes
[javac] /ivy/configurations/multi-projects/filter-framework/build.xml:82: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 3 source files to /ivy/configurations/multi-projects/filter-framework/build/test-classes
[junit] Running filter.ccimpl.CCFilterTest
[junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0,109 sec
[junit] Running filter.hmimpl.HMFilterTest
[junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0,093 sec
publish:
[ivy:publish] :: delivering :: org.apache#filter-framework;working@apache :: 1.3 :: release :: Thu Sep 23 23:16:19 CEST 2010
[ivy:publish] delivering ivy file to /ivy/configurations/multi-projects/filter-framework/distrib/ivy.xml
[ivy:publish] :: publishing :: org.apache#filter-framework
[ivy:publish] published filter-api to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part/jars/filter-api.jar
[ivy:publish] published filter-hmimpl to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part/jars/filter-hmimpl.jar
[ivy:publish] published filter-ccimpl to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part/jars/filter-ccimpl.jar
[ivy:publish] published ivy to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part/ivys/ivy.xml
[ivy:publish] publish commited: moved /home/ivy/.ivy2/local/org.apache/filter-framework/1.3.part
[ivy:publish] to /home/ivy/.ivy2/local/org.apache/filter-framework/1.3
[echo] project filter-framework released with version 1.3
BUILD SUCCESSFUL
Total time: 18 seconds
The application project
Now that we have shipped (published) our fantastic filter library, we want to use it! The tutorial comes with a sample application called myapp.The ivy.xml file
<ivy-module version="1.0">
<info organisation="org.apache" 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="org.apache" 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 different ways we want to use the application. The build configuration defines the compile-time dependencies, and thus only needs the api conf from the filter-framework project. The other two configurations define runtime dependencies. One will only use our "home-made" jar, and the other will use an external jar.We also defined a dependency on our previously built library. In this dependency, we use configuration mappings to match ours with the dependency's configurations. You can find more information about configuration mapping here
- build->api : here we tell Ivy that our build configuration depends on the api configuration of the dependency
- noexternaljar->homemade-impl : here we tell Ivy that our noexternaljar configuration depends on the homemade-impl configuration of the dependency.
- withexternaljar->cc-impl : here we tell Ivy that our withexternaljar configuration depends on the cc-impl configuration of the dependency
In the Ant build.xml file, we defined a 'resolve' target as follow:
<target name="resolve" description="--> retreive dependencies with ivy">When we call this target, Ivy will do a resolve using our ivy.xml file in the root folder and then retrieve all the artifacts. The artifacts retrieved are kept in separate folders according to the configurations they belong to. Here is how your lib directory should look after a call to this target:
<ivy:retrieve pattern="${ivy.lib.dir}/[conf]/[artifact].[ext]"/>
</target>
Repertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib
01/24/2006 11:19 AMbuild
01/24/2006 11:19 AMnoexternaljar
01/24/2006 11:19 AMwithexternaljar
0 fichier(s) 0 octets
Repertoire 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
Repertoire 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
Repertoire 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
Let's try to launch our app.
See it in action
Use Ant to run the application. The default Ant target is run-cc and will launch the application using the Apache commons-collections implementation.
[ivy@apache:/ivy/configurations/multi-projects/myapp]$ ant
Buildfile: /ivy/configurations/multi-projects/myapp/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#myapp;working@apache
[ivy:retrieve] confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] found org.apache#filter-framework;1.3 in local
[ivy:retrieve] [1.3] org.apache#filter-framework;latest.integration
[ivy:retrieve] found commons-collections#commons-collections;3.1 in public
[ivy:retrieve] downloading /home/ivy/.ivy2/local/org.apache/filter-framework/1.3/jars/filter-ccimpl.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#filter-framework;1.3!filter-ccimpl.jar (16ms)
[ivy:retrieve] downloading /home/ivy/.ivy2/local/org.apache/filter-framework/1.3/jars/filter-hmimpl.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#filter-framework;1.3!filter-hmimpl.jar (15ms)
[ivy:retrieve] downloading /home/ivy/.ivy2/local/org.apache/filter-framework/1.3/jars/filter-api.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] [SUCCESSFUL ] org.apache#filter-framework;1.3!filter-api.jar (31ms)
[ivy:retrieve] :: resolution report :: resolve 156ms :: artifacts dl 62ms
---------------------------------------------------------------------
| | 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 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#myapp
[ivy:retrieve] confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] 6 artifacts copied, 0 already retrieved (552kB/94ms)
build:
[mkdir] Created dir: /ivy/configurations/multi-projects/myapp/build
[javac] /ivy/configurations/multi-projects/myapp/build.xml:56: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /ivy/configurations/multi-projects/myapp/build
run-cc:
[java] Filtering with:class filter.ccimpl.CCFilter
[java] Result :[two, tree]
BUILD SUCCESSFUL
Total time: 3 seconds
type ant run-hm
[ivy@apache:/ivy/configurations/multi-projects/myapp]$ ant run-hm
Buildfile: /ivy/configurations/multi-projects/myapp/build.xml
resolve:
[ivy:retrieve] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] :: loading settings :: url = jar:file:///home/ivy/ivy.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: org.apache#myapp;working@apache
[ivy:retrieve] confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] found org.apache#filter-framework;1.3 in local
[ivy:retrieve] [1.3] org.apache#filter-framework;latest.integration
[ivy:retrieve] found commons-collections#commons-collections;3.1 in public
[ivy:retrieve] :: resolution report :: resolve 156ms :: artifacts dl 0ms
---------------------------------------------------------------------
| | modules || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| build | 1 | 0 | 0 | 0 || 1 | 0 |
| noexternaljar | 1 | 0 | 0 | 0 || 2 | 0 |
| withexternaljar | 2 | 0 | 0 | 0 || 3 | 0 |
---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: org.apache#myapp
[ivy:retrieve] confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] 0 artifacts copied, 6 already retrieved (0kB/31ms)
build:
[javac] /ivy/configurations/multi-projects/myapp/build.xml:56: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
run-hm:
[java] Filtering with:class filter.hmimpl.HMFilter
[java] Result :[two, tree]
BUILD SUCCESSFUL
Total time: 2 seconds
Conclusion
You should use configurations as often as possible. Configurations are a very important concept in Ivy. They allow you to group artifacts and give the group a meaning. When you write ivy files for projects that are intended for use by others, use configurations to allow people to get only what they need, without having to specify them one by one in their own dependency list.Building a repository
The install Ant task lets you copy a module or a set of modules from one repository to another. This is very useful to build and maintain an enterprise or team repository. If you don't want to give access to the public maven 2 repository to the developers on your team (to keep control over which modules are in use in your company or your team for instance), it can sometimes become tiresome to answer the developers request to add new modules or new versions by hand.
Fortunately the install task is here to help: you can use specific settings for your repository maintenance build which will be used to maintain your target enterprise repository. These settings will point to another repository (for instance the maven 2 public repository) so that you will just have to ask Ivy to install the modules you want with a simple command line.
To demonstrate this, we will first use a basic ivy settings file to show how it works, and then we will use the advanced namespaces features to demonstrate how to deal with naming mismatches between the source and target repository.
The project used
The project that we will use is pretty simple. It is composed of an Ant build file, and two ivy settings files.Here are the public targets that we will use:
Z:\ivy-repository>ant -p
Buildfile: build.xml
Main targets:
clean-cache --> clean the cache
clean-repo --> clean the destination repository
maven2 --> install module from maven 2 repository
maven2-deps --> install module from maven 2 repository with dependencies
maven2-namespace --> install module from maven 2 using namespaces
maven2-namespace-deps --> install module with dependencies from maven2 repo using namespaces
Default target: basic
This project is accessible in the src/example/build-a-ivy-repository
Next steps:
Basic repository copy
Using namespaces
Basic repository copy
In this first step, we use the install Ant task to install modules from the maven 2 repository to a file system based repository. We first install a module by itself, excluding dependencies, then again with its dependencies.
Basic: ivysettings.xml file used
The ivy settings file that we will use is very simple here. It defines two resolvers, libraries and my-repository. The first one is used as the source, the second one as the destination. In a typical setup, the second one would be configured using an include that included an existing settings file used by the development team.<ivysettings>
<settings defaultCache="${ivy.cache.dir}/no-namespace"
defaultResolver="libraries"
defaultConflictManager="all" /> <!-- in order to get all revisions without any eviction -->
<resolvers>
<ibiblio name="libraries" m2compatible="true" />
<filesystem name="my-repository">
<ivy pattern="${dest.repo.dir}/no-namespace/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${dest.repo.dir}/no-namespace/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
</filesystem>
</resolvers>
</ivysettings>
install a simple module with no dependencies
Let's have a look at the maven2 target.
<target name="maven2" depends="init-ivy"
description="--> install module from maven 2 repository">
<ivy:install settingsRef="basic.settings"
organisation="commons-lang" module="commons-lang" revision="1.0"
from="${from.resolver}" to="${to.resolver}" />
</target>
Pretty simple, we call the [[ant:install] task with the settings we have loaded using ivy:settings as usual. We then set the source and destination repositories using the from and to attributes. We used Ant properties for these values here, which helps ease the maintenance of the script, but it's basically the name of our resolvers: 'libraries' for the source and 'my-repository' for the destination.Here is the Ant call output :
[ivy@apache:/ivy/build-a-ivy-repository]$ ant maven2 Buildfile: /ivy/build-a-ivy-repository/build.xml load-ivy: init-ivy: maven2: [ivy:install] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ :: [ivy:install] :: loading settings :: file = /ivy/build-a-ivy-repository/settings/ivysettings-basic.xml [ivy:install] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/build-a-ivy-repository/settings/ivysettings-basic.xml) [ivy:install] :: installing commons-lang#commons-lang;1.0 :: [ivy:install] :: resolving dependencies :: [ivy:install] found commons-lang#commons-lang;1.0 in libraries [ivy:install] :: downloading artifacts to cache :: [ivy:install] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0-javadoc.jar ... [ivy:install] .............................................................................................................................................................................................................................................................................................................................................................. (170kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] commons-lang#commons-lang;1.0!commons-lang.jar(javadoc) (4134ms) [ivy:install] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0.jar ... [ivy:install] .......................................................................................................................... (62kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] commons-lang#commons-lang;1.0!commons-lang.jar (1576ms) [ivy:install] :: installing in my-repository :: [ivy:install] published commons-lang to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/javadocs/commons-lang-1.0.jar [ivy:install] published commons-lang to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/jars/commons-lang-1.0.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/ivys/ivy-1.0.xml [ivy:install] :: install resolution report :: [ivy:install] :: resolution report :: resolve 0ms :: artifacts dl 5725ms --------------------------------------------------------------------- | | modules || artifacts | | conf | number| search|dwnlded|evicted|| number|dwnlded| --------------------------------------------------------------------- | default | 1 | 1 | 1 | 0 || 2 | 2 | --------------------------------------------------------------------- BUILD SUCCESSFUL Total time: 10 seconds
Let's have a look at our repository :
[ivy@apache:/]$ find /ivy/build-a-ivy-repository/myrepository/no-namespace -type f -print /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/ivys/ivy-1.0.xml /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/ivys/ivy-1.0.xml.md5 /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/ivys/ivy-1.0.xml.sha1 /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/jars/commons-lang-1.0.jar /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/jars/commons-lang-1.0.jar.md5 /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/jars/commons-lang-1.0.jar.sha1 /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/javadocs/commons-lang-1.0.jar /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/javadocs/commons-lang-1.0.jar.md5 /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-lang/commons-lang/javadocs/commons-lang-1.0.jar.sha1
install a module with dependencies
Now let's say that we want to be sure all the dependencies of the module we install are available in our repository after the installation. We could either install without dependencies on a staging repository and check the missing dependencies (more control), or use transitive dependency management and ask Ivy to install everything for us (much simpler).The maven2-deps target is very similar to the one described above, except that we explicitly ask for transitive installation.
<target name="maven2-deps" depends="init-ivy"
description="--> install module from maven 2 repository with dependencies">
<ivy:install settingsRef="basic.settings"
organisation="org.hibernate" module="hibernate" revision="3.2.5.ga"
from="${from.resolver}" to="${to.resolver}" transitive="true" />
</target>
If you call this target, you will see that Ivy installs not only the hibernate module but also its dependencies:
[ivy@apache:/ivy/build-a-ivy-repository]$ ant maven2-deps Buildfile: /ivy/build-a-ivy-repository/build.xml load-ivy: init-ivy: maven2-deps: [ivy:install] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ :: [ivy:install] :: loading settings :: file = /ivy/build-a-ivy-repository/settings/ivysettings-basic.xml [ivy:install] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/build-a-ivy-repository/settings/ivysettings-basic.xml) [ivy:install] :: installing org.hibernate#hibernate;3.2.5.ga :: [ivy:install] :: resolving dependencies :: [ivy:install] found org.hibernate#hibernate;3.2.5.ga in libraries [ivy:install] found net.sf.ehcache#ehcache;1.2.3 in libraries [ivy:install] found commons-logging#commons-logging;1.0.4 in libraries [ivy:install] found commons-collections#commons-collections;2.1 in libraries [ivy:install] found javax.transaction#jta;1.0.1B in libraries [ivy:install] found asm#asm-attrs;1.5.3 in libraries [ivy:install] found dom4j#dom4j;1.6.1 in libraries [ivy:install] found antlr#antlr;2.7.6 in libraries [ivy:install] found cglib#cglib;2.1_3 in libraries [ivy:install] found asm#asm;1.5.3 in libraries [ivy:install] found commons-collections#commons-collections;2.1.1 in libraries [ivy:install] found ant#ant;1.6.5 in libraries [ivy:install] found swarmcache#swarmcache;1.0RC2 in libraries [ivy:install] found commons-logging#commons-logging;1.0.2 in libraries [ivy:install] found jgroups#jgroups-all;2.2.8 in libraries [ivy:install] found jboss#jboss-cache;1.2.2 in libraries [ivy:install] found jboss#jboss-system;4.0.2 in libraries [ivy:install] found jboss#jboss-common;4.0.2 in libraries [ivy:install] found slide#webdavlib;2.0 in libraries [ivy:install] found xerces#xercesImpl;2.6.2 in libraries [ivy:install] found jboss#jboss-minimal;4.0.2 in libraries [ivy:install] found jboss#jboss-j2se;200504122039 in libraries [ivy:install] found concurrent#concurrent;1.3.4 in libraries [ivy:install] found jgroups#jgroups-all;2.2.7 in libraries [ivy:install] found c3p0#c3p0;0.9.1 in libraries [ivy:install] found javax.security#jacc;1.0 in libraries [ivy:install] found opensymphony#oscache;2.1 in libraries [ivy:install] found proxool#proxool;0.8.3 in libraries [ivy:install] :: downloading artifacts to cache :: [ivy:install] downloading http://repo1.maven.org/maven2/org/hibernate/hibernate/3.2.5.ga/hibernate-3.2.5.ga-sources.jar ... [ivy:install] ......................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] .................................................................................................................................................................................................................................................................................................................................. (1470kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] org.hibernate#hibernate;3.2.5.ga!hibernate.jar(source) (6427ms) [ivy:install] downloading http://repo1.maven.org/maven2/org/hibernate/hibernate/3.2.5.ga/hibernate-3.2.5.ga-javadoc.jar ... [ivy:install] ............................................................................................................................................................................................................................................................. [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. [ivy:install] ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. [ivy:install] .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ [ivy:install] ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ [ivy:install] ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ [ivy:install] ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ [ivy:install] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (7352kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] org.hibernate#hibernate;3.2.5.ga!hibernate.jar(javadoc) (22511ms) [ivy:install] downloading http://repo1.maven.org/maven2/org/hibernate/hibernate/3.2.5.ga/hibernate-3.2.5.ga.jar ... [ivy:install] ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (2202kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] org.hibernate#hibernate;3.2.5.ga!hibernate.jar (7300ms) [ivy:install] downloading http://repo1.maven.org/maven2/net/sf/ehcache/ehcache/1.2.3/ehcache-1.2.3.jar ... [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................ (203kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] net.sf.ehcache#ehcache;1.2.3!ehcache.jar (2746ms) [ivy:install] downloading http://repo1.maven.org/maven2/commons-logging/commons-logging/1.0.4/commons-logging-1.0.4.jar ... [ivy:install] .......................................................................... (37kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] commons-logging#commons-logging;1.0.4!commons-logging.jar (1825ms) [ivy:install] downloading http://repo1.maven.org/maven2/asm/asm-attrs/1.5.3/asm-attrs-1.5.3.jar ... [ivy:install] .............................. (16kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] asm#asm-attrs;1.5.3!asm-attrs.jar (1857ms) [ivy:install] downloading http://repo1.maven.org/maven2/dom4j/dom4j/1.6.1/dom4j-1.6.1.jar ... [ivy:install] ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] .................................................................................................................................................. (306kB) [ivy:install] ... (0kB) [ivy:install] [SUCCESSFUL ] dom4j#dom4j;1.6.1!dom4j.jar (3463ms) [ivy:install] downloading http://repo1.maven.org/maven2/antlr/antlr/2.7.6/antlr-2.7.6.jar ... [ivy:install] ....................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (433kB) [ivy:install] ... (0kB) [ivy:install] [SUCCESSFUL ] antlr#antlr;2.7.6!antlr.jar (4711ms) [ivy:install] downloading http://repo1.maven.org/maven2/cglib/cglib/2.1_3/cglib-2.1_3.jar ... [ivy:install] .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (275kB) [ivy:install] ... (0kB) [ivy:install] [SUCCESSFUL ] cglib#cglib;2.1_3!cglib.jar (2449ms) [ivy:install] downloading http://repo1.maven.org/maven2/asm/asm/1.5.3/asm-1.5.3.jar ... [ivy:install] ..................................................... (25kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] asm#asm;1.5.3!asm.jar (9157ms) [ivy:install] downloading http://repo1.maven.org/maven2/commons-collections/commons-collections/2.1.1/commons-collections-2.1.1.jar ... [ivy:install] .......................................................................................................................................................................................................................................................................................................................... (171kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] commons-collections#commons-collections;2.1.1!commons-collections.jar (2356ms) [ivy:install] downloading http://repo1.maven.org/maven2/commons-collections/commons-collections/2.1/commons-collections-2.1.jar ... [ivy:install] .................................................................................................................................................................................................................................................................................................. (161kB) [ivy:install] ... (0kB) [ivy:install] [SUCCESSFUL ] commons-collections#commons-collections;2.1!commons-collections.jar (1638ms) [ivy:install] downloading http://repo1.maven.org/maven2/ant/ant/1.6.5/ant-1.6.5.jar ... [ivy:install] .............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. [ivy:install] ....................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................ (1009kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] ant#ant;1.6.5!ant.jar (5304ms) [ivy:install] downloading http://repo1.maven.org/maven2/swarmcache/swarmcache/1.0RC2/swarmcache-1.0RC2.jar ... [ivy:install] ......................................................... (29kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] swarmcache#swarmcache;1.0RC2!swarmcache.jar (1670ms) [ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-cache/1.2.2/jboss-cache-1.2.2.jar ... [ivy:install] ...................................................................................................... [ivy:install] ................................................................................................. [ivy:install] ................................................................................................................................................................................................................................ [ivy:install] ................................................................................................................................................................................................................................................................................................................................... [ivy:install] ..... (365kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] jboss#jboss-cache;1.2.2!jboss-cache.jar (8470ms) [ivy:install] downloading http://repo1.maven.org/maven2/jgroups/jgroups-all/2.2.8/jgroups-all-2.2.8.jar ... [ivy:install] ........................................................................................................................................................................................................................................................................................................................................ [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. [ivy:install] ........................................................................................................................................................................................................................................................................................................................... [ivy:install] ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (1573kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] jgroups#jgroups-all;2.2.8!jgroups-all.jar (8954ms) [ivy:install] downloading http://repo1.maven.org/maven2/c3p0/c3p0/0.9.1/c3p0-0.9.1.jar ... [ivy:install] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (594kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] c3p0#c3p0;0.9.1!c3p0.jar (4836ms) [ivy:install] downloading http://repo1.maven.org/maven2/opensymphony/oscache/2.1/oscache-2.1.jar ... [ivy:install] ............................................................................................................................................................................................................................. (111kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] opensymphony#oscache;2.1!oscache.jar (1856ms) [ivy:install] downloading http://repo1.maven.org/maven2/proxool/proxool/0.8.3/proxool-0.8.3.jar ... [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (464kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] proxool#proxool;0.8.3!proxool.jar (7238ms) [ivy:install] downloading http://repo1.maven.org/maven2/commons-logging/commons-logging/1.0.2/commons-logging-1.0.2.jar ... [ivy:install] .................................................. (25kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] commons-logging#commons-logging;1.0.2!commons-logging.jar (4790ms) [ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-system/4.0.2/jboss-system-4.0.2.jar ... [ivy:install] ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (227kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] jboss#jboss-system;4.0.2!jboss-system.jar (2917ms) [ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-common/4.0.2/jboss-common-4.0.2.jar ... [ivy:install] ..................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... (457kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] jboss#jboss-common;4.0.2!jboss-common.jar (3666ms) [ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-minimal/4.0.2/jboss-minimal-4.0.2.jar ... [ivy:install] .......................................................................................................................................................................................................................................................................................................................... (163kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] jboss#jboss-minimal;4.0.2!jboss-minimal.jar (2215ms) [ivy:install] downloading http://repo1.maven.org/maven2/jboss/jboss-j2se/200504122039/jboss-j2se-200504122039.jar ... [ivy:install] .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. (350kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] jboss#jboss-j2se;200504122039!jboss-j2se.jar (2714ms) [ivy:install] downloading http://repo1.maven.org/maven2/concurrent/concurrent/1.3.4/concurrent-1.3.4.jar ... [ivy:install] ........................................................................................................................................................................................................................................................................................................................................... (184kB) [ivy:install] ... (0kB) [ivy:install] [SUCCESSFUL ] concurrent#concurrent;1.3.4!concurrent.jar (2574ms) [ivy:install] downloading http://repo1.maven.org/maven2/jgroups/jgroups-all/2.2.7/jgroups-all-2.2.7.jar ... [ivy:install] ....................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. [ivy:install] ..................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... [ivy:install] ................................................................................................................................................................................... (1613kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] jgroups#jgroups-all;2.2.7!jgroups-all.jar (7052ms) [ivy:install] downloading http://repo1.maven.org/maven2/slide/webdavlib/2.0/webdavlib-2.0.jar ... [ivy:install] ......................................................................................................................................................................................................................................................................... (128kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] slide#webdavlib;2.0!webdavlib.jar (2792ms) [ivy:install] downloading http://repo1.maven.org/maven2/xerces/xercesImpl/2.6.2/xercesImpl-2.6.2.jar ... [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. [ivy:install] ............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ (986kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] xerces#xercesImpl;2.6.2!xercesImpl.jar (4087ms) [ivy:install] :: installing in my-repository :: [ivy:install] published hibernate to /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/sources/hibernate-3.2.5.ga.jar [ivy:install] published hibernate to /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/javadocs/hibernate-3.2.5.ga.jar [ivy:install] published hibernate to /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/jars/hibernate-3.2.5.ga.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/ivys/ivy-3.2.5.ga.xml [ivy:install] published ehcache to /ivy/build-a-ivy-repository/myrepository/no-namespace/net.sf.ehcache/ehcache/jars/ehcache-1.2.3.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/net.sf.ehcache/ehcache/ivys/ivy-1.2.3.xml [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/javax.transaction/jta/ivys/ivy-1.0.1B.xml [ivy:install] published commons-logging to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-logging/commons-logging/jars/commons-logging-1.0.4.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-logging/commons-logging/ivys/ivy-1.0.4.xml [ivy:install] published asm-attrs to /ivy/build-a-ivy-repository/myrepository/no-namespace/asm/asm-attrs/jars/asm-attrs-1.5.3.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/asm/asm-attrs/ivys/ivy-1.5.3.xml [ivy:install] published dom4j to /ivy/build-a-ivy-repository/myrepository/no-namespace/dom4j/dom4j/jars/dom4j-1.6.1.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/dom4j/dom4j/ivys/ivy-1.6.1.xml [ivy:install] published antlr to /ivy/build-a-ivy-repository/myrepository/no-namespace/antlr/antlr/jars/antlr-2.7.6.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/antlr/antlr/ivys/ivy-2.7.6.xml [ivy:install] published cglib to /ivy/build-a-ivy-repository/myrepository/no-namespace/cglib/cglib/jars/cglib-2.1_3.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/cglib/cglib/ivys/ivy-2.1_3.xml [ivy:install] published asm to /ivy/build-a-ivy-repository/myrepository/no-namespace/asm/asm/jars/asm-1.5.3.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/asm/asm/ivys/ivy-1.5.3.xml [ivy:install] published commons-collections to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-collections/commons-collections/jars/commons-collections-2.1.1.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-collections/commons-collections/ivys/ivy-2.1.1.xml [ivy:install] published commons-collections to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-collections/commons-collections/jars/commons-collections-2.1.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-collections/commons-collections/ivys/ivy-2.1.xml [ivy:install] published ant to /ivy/build-a-ivy-repository/myrepository/no-namespace/ant/ant/jars/ant-1.6.5.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/ant/ant/ivys/ivy-1.6.5.xml [ivy:install] published swarmcache to /ivy/build-a-ivy-repository/myrepository/no-namespace/swarmcache/swarmcache/jars/swarmcache-1.0RC2.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/swarmcache/swarmcache/ivys/ivy-1.0RC2.xml [ivy:install] published jboss-cache to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-cache/jars/jboss-cache-1.2.2.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-cache/ivys/ivy-1.2.2.xml [ivy:install] published jgroups-all to /ivy/build-a-ivy-repository/myrepository/no-namespace/jgroups/jgroups-all/jars/jgroups-all-2.2.8.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jgroups/jgroups-all/ivys/ivy-2.2.8.xml [ivy:install] published c3p0 to /ivy/build-a-ivy-repository/myrepository/no-namespace/c3p0/c3p0/jars/c3p0-0.9.1.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/c3p0/c3p0/ivys/ivy-0.9.1.xml [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/javax.security/jacc/ivys/ivy-1.0.xml [ivy:install] published oscache to /ivy/build-a-ivy-repository/myrepository/no-namespace/opensymphony/oscache/jars/oscache-2.1.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/opensymphony/oscache/ivys/ivy-2.1.xml [ivy:install] published proxool to /ivy/build-a-ivy-repository/myrepository/no-namespace/proxool/proxool/jars/proxool-0.8.3.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/proxool/proxool/ivys/ivy-0.8.3.xml [ivy:install] published commons-logging to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-logging/commons-logging/jars/commons-logging-1.0.2.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/commons-logging/commons-logging/ivys/ivy-1.0.2.xml [ivy:install] published jboss-system to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-system/jars/jboss-system-4.0.2.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-system/ivys/ivy-4.0.2.xml [ivy:install] published jboss-common to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-common/jars/jboss-common-4.0.2.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-common/ivys/ivy-4.0.2.xml [ivy:install] published jboss-minimal to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-minimal/jars/jboss-minimal-4.0.2.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-minimal/ivys/ivy-4.0.2.xml [ivy:install] published jboss-j2se to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-j2se/jars/jboss-j2se-200504122039.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jboss/jboss-j2se/ivys/ivy-200504122039.xml [ivy:install] published concurrent to /ivy/build-a-ivy-repository/myrepository/no-namespace/concurrent/concurrent/jars/concurrent-1.3.4.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/concurrent/concurrent/ivys/ivy-1.3.4.xml [ivy:install] published jgroups-all to /ivy/build-a-ivy-repository/myrepository/no-namespace/jgroups/jgroups-all/jars/jgroups-all-2.2.7.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/jgroups/jgroups-all/ivys/ivy-2.2.7.xml [ivy:install] published webdavlib to /ivy/build-a-ivy-repository/myrepository/no-namespace/slide/webdavlib/jars/webdavlib-2.0.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/slide/webdavlib/ivys/ivy-2.0.xml [ivy:install] published xercesImpl to /ivy/build-a-ivy-repository/myrepository/no-namespace/xerces/xercesImpl/jars/xercesImpl-2.6.2.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/no-namespace/xerces/xercesImpl/ivys/ivy-2.6.2.xml [ivy:install] :: install resolution report :: [ivy:install] :: resolution report :: resolve 0ms :: artifacts dl 137701ms --------------------------------------------------------------------- | | modules || artifacts | | conf | number| search|dwnlded|evicted|| number|dwnlded| --------------------------------------------------------------------- | default | 28 | 28 | 28 | 0 || 30 | 28 | --------------------------------------------------------------------- [ivy:install] [ivy:install] :: problems summary :: [ivy:install] :::: WARNINGS [ivy:install] [NOT FOUND ] javax.transaction#jta;1.0.1B!jta.jar (0ms) [ivy:install] ==== libraries: tried [ivy:install] http://repo1.maven.org/maven2/javax/transaction/jta/1.0.1B/jta-1.0.1B.jar [ivy:install] [NOT FOUND ] javax.security#jacc;1.0!jacc.jar (0ms) [ivy:install] ==== libraries: tried [ivy:install] http://repo1.maven.org/maven2/javax/security/jacc/1.0/jacc-1.0.jar [ivy:install] :::::::::::::::::::::::::::::::::::::::::::::: [ivy:install] :: FAILED DOWNLOADS :: [ivy:install] :: ^ see resolution messages for details ^ :: [ivy:install] :::::::::::::::::::::::::::::::::::::::::::::: [ivy:install] :: javax.transaction#jta;1.0.1B!jta.jar [ivy:install] :: javax.security#jacc;1.0!jacc.jar [ivy:install] :::::::::::::::::::::::::::::::::::::::::::::: [ivy:install] [ivy:install] [ivy:install] :: USE VERBOSE OR DEBUG MESSAGE LEVEL FOR MORE DETAILS
You may also have noticed that Ivy installed 2 different revisions of commons-logging (1.0.2, 1.0.4). This is due to the fact that we used the "no conflict" conflict manager in the ivysettings file.
We do not want to evict any modules because we are building our own repository. Indeed if we get both commons-logging 1.0.2 and 1.0.4 it's because some modules among the transitive dependencies of hibernate depend on 1.0.2 and others on 1.0.4. If we got only 1.0.4, the module depending on 1.0.2 would be inconsistent in your own repository (depending on a version you don't have installed). Thus developers using this module directly would run into a problem.
If you now have a closer look at your repository, you will probably notice that it isn't an exact replication of the original one. Let's have a look at the directory of one module:
[ivy@apache:/]$ find /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate -type f -print /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/ivys/ivy-3.2.5.ga.xml /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/ivys/ivy-3.2.5.ga.xml.md5 /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/ivys/ivy-3.2.5.ga.xml.sha1 /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/jars/hibernate-3.2.5.ga.jar /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/jars/hibernate-3.2.5.ga.jar.md5 /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/jars/hibernate-3.2.5.ga.jar.sha1 /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/javadocs/hibernate-3.2.5.ga.jar /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/javadocs/hibernate-3.2.5.ga.jar.md5 /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/javadocs/hibernate-3.2.5.ga.jar.sha1 /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/sources/hibernate-3.2.5.ga.jar /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/sources/hibernate-3.2.5.ga.jar.md5 /ivy/build-a-ivy-repository/myrepository/no-namespace/org.hibernate/hibernate/sources/hibernate-3.2.5.ga.jar.sha1
OK, enough for this simple repository installation, the next tutorial will show how you can deal with more complex cases where your source and destination repositories do not follow the same naming conventions.
Using namespaces
Now that you have seen how simple it is to create your own repository from an existing one, you may wonder how you can handle more complex cases, like when the source and destination repositories don't follow the same naming conventions.
On the road to a professional repository
In this section, you will learn how to build a professional repository. What is a professional repository? Our vision is to say that a good quality repository must follow clear rules about projects naming and must offer correct, useable, configurations 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 always the expected one, especially concerning the naming rules used.
This problem is pretty normal when you have an existing repository, and want to benefit from large public repositories which do not follow the same naming conventions. It also shows up because many public repositories do not use a consistent naming scheme. For example, why don't all the apache commons modules use the org.apache.commons organization? Well.. for historical reasons. But if you setup your own repository, you may not want to suffer from the mistakes of history.
Fortunately, Ivy has a very powerful answer to this problem: namespaces.
Using namespaces
If you look at the repository built with the previous tutorial, you will see exactly what we were talking about: all apache commons modules use their own name as their organization.So let's see what Ivy can do using namespaces (we will dig into details later):
[ivy@apache:/ivy/build-a-ivy-repository]$ ant maven2-namespace Buildfile: /ivy/build-a-ivy-repository/build.xml load-ivy: init-ivy: maven2-namespace: [ivy:install] :: Ivy 2.2.0 - 20100923230623 :: http://ant.apache.org/ivy/ :: [ivy:install] :: loading settings :: file = /ivy/build-a-ivy-repository/settings/ivysettings-advanced.xml [ivy:install] DEPRECATED: 'defaultCache' is deprecated, use 'caches[@defaultCacheDir]' instead (file://ivy/build-a-ivy-repository/settings/ivysettings-advanced.xml) [ivy:install] :: installing apache#commons-lang;1.0 :: [ivy:install] :: resolving dependencies :: [ivy:install] found apache#commons-lang;1.0 in libraries [ivy:install] :: downloading artifacts to cache :: [ivy:install] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0.jar ... [ivy:install] ....................................................................................................................... (62kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] apache#commons-lang;1.0!commons-lang.jar (3151ms) [ivy:install] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0-javadoc.jar ... [ivy:install] ..................................................................................................................................................................................................................................................................................................................................................................... (170kB) [ivy:install] .. (0kB) [ivy:install] [SUCCESSFUL ] apache#commons-lang;1.0!commons-lang.jar(javadoc) (3104ms) [ivy:install] :: installing in my-repository :: [ivy:install] published commons-lang to /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/jars/commons-lang-1.0.jar [ivy:install] published commons-lang to /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/javadocs/commons-lang-1.0.jar [ivy:install] published ivy to /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/ivys/ivy-1.0.xml [ivy:install] :: install resolution report :: [ivy:install] :: resolution report :: resolve 0ms :: artifacts dl 6255ms --------------------------------------------------------------------- | | modules || artifacts | | conf | number| search|dwnlded|evicted|| number|dwnlded| --------------------------------------------------------------------- | default | 1 | 1 | 1 | 0 || 2 | 2 | --------------------------------------------------------------------- BUILD SUCCESSFUL Total time: 10 seconds
$ find /ivy/build-a-ivy-repository/myrepository/advanced -type f -print /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/ivys/ivy-1.0.xml /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/ivys/ivy-1.0.xml.md5 /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/ivys/ivy-1.0.xml.sha1 /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/jars/commons-lang-1.0.jar /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/jars/commons-lang-1.0.jar.md5 /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/jars/commons-lang-1.0.jar.sha1 /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/javadocs/commons-lang-1.0.jar /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/javadocs/commons-lang-1.0.jar.md5 /ivy/build-a-ivy-repository/myrepository/advanced/apache/commons-lang/javadocs/commons-lang-1.0.jar.sha1
<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="1.0">
<info organisation="apache"
module="commons-lang"
revision="1.0"
status="integration"
publication="20051124062021"
namespace="ibiblio-maven2"
/>
...
How does this work ?
Actually, Ivy uses the same repository as before for the source repository, with only one difference: the namespace parameter:<ibiblio name="libraries"A namespace is defined by a set of rules. These rules are based on regular expressions and tell Ivy how to convert data from the repository namespace to what is called the system namespace, i.e. the namespace in which Ivy runs most of the time (Note: the Ivy cache always uses the system namespace).
root="${ibiblio-maven2-root}"
m2compatible="true"
namespace="maven2"
/>
For the namespace we call maven2, we have declared several rules. Below is one of the rules:
rule handling the 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 organization, module, and revision, the notation Ivy uses prefixes the matching regular expression with the letters 'o', 'm' and 'r'.
$o0 : the whole matching value in the organization attribute
$o1 : the first matching expression group that was marked in the organization attribute
...
The same applies for modules : $m0, $m1, ...
and for revisions : $r0, $r1, ...
To understand namespaces,
$o0 : the whole matching value in the organization attribute
$o1 : the first matching expression group that was marked in the organization attribute
...
The same applies for modules : $m0, $m1, ...
and for revisions : $r0, $r1, ...
- fromsystem : we define here that the projects defined in the system namespace under the organization called "apache" are transformed into the destination namespace into projects whose organization is named with the module name, whatever the revision is. For example, the project apache#commons-lang;1.0 in the system namespace will be translated into commons-lang#commons-lang;1.0 in the maven2 resolver namespace.
- tosystem : we define here the reverse mapping, i.e. how to translate apache projects from maven 2 repo into apache projects in the system namespace. The rule used here tells Ivy that all projects matching commons-.+ (see it as java regular expression) for their organization 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 defined for others apache projects like ant, etc.
Run
ant maven2-namespace-depsand you will see the resulting repository is cleaner than the first one we built.
From our experience, investing in creating a namespace is worth the time it costs if you often need to add new modules or revisions of third party libraries in your own repository, where naming rules already exist or are rather strict.
More examples
If you have successfully followed and understood all the tutorials, you still might need to get a better picture of how to use Ivy in the real world.
Here are some links which might 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.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 makes 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.Reference
Welcome to the Ivy reference documentation!
If you don't know Ivy at all, take a look at its features, the faq and the tutorials before digging into this reference documentation.
Reference Overview
This documentation is broken into several parts:- Introduction
- Terminology This part gives you the meaning of some words used all over the Ivy documentation, such as organization, module, configurations, settings, ...
- Main Concepts This part introduces the main concepts used in Ivy: dependency resolvers, variables, patterns, and also a good introduction to a central ivy concept: module configurations.
- How does it work ? As the title suggests, here you will find an explanation of how Ivy does work internally, which can help to better understand and customize its use.
- Installation This part describes how to install Ivy.
- Settings Files This part is dedicated to the specification of the settings file of Ivy (usually called ivysettings.xml). It also gives the list of built-in dependency resolvers available in Ivy.
- Ivy Files This part is the reference for the module descriptors, the Ivy files in which you describe your dependencies. If you have any questions about what can be done or not in an ivy file, you will find the answer here.
- Ant Tasks This part describes how to use Ivy from ant. It's in this section that all ant tasks provided by Ivy are specified.
- Using standalone Even though Ivy is most often used from ant, it can also be used from the command line. This page describes how you can do this.
Introduction
Terminology
Here are some terms used in Ivy, with their definitions in Ivy:
- Organisation
- Module
- Module Descriptor
- Artifact
- Type of an artifact
- Artifact file name extension
- Module Revision
- Branch
- Status of a revision
- Configurations of a module
- Ivy Settings
- Repository
Overview
The following illustration shows all the key terminology in one diagram:
Organisation
An organisation is either a company, an individual, or simply any group of people that produces software. In principle, Ivy handles only a single level of organisation, meaning that they have a flat namespace in Ivy module descriptors. So, with Ivy descriptors, you can only describe a tree-like organisation structure, if you use a hierarchical naming convention. The organisation name is used for keeping together software produced by the same team, just to help locate their published works.Often organisations will use their inverted domain name as their organisation name in Ivy, since domain names by definition are unique. A company whose domain name is www.example.com might want to use com.example, or if they had multiple teams, all their organisation names could begin with com.example (e.g. com.example.rd, com.example.infra, com.example.services). The organisation name does neither really have to be an inverted domain name, nor even globally unique, but unique naming is highly recommended. Widely recognized trademark or trade name owners may choose to use their brand name instead.
Examples: org.apache, ibm, jayasoft
Note that the Ivy "organisation" is very similar to Maven POM "groupId".
Module
A module is a self-contained, reusable unit of software that, as a whole unit, follows a revision control scheme.Ivy is only concerned about the module deliverables known as artifacts, and the module descriptor that declares them. These deliverables, for each revision of the module, are managed in repositories. In other words, to Ivy, a module is a chain of revisions each comprising a descriptor and one or more artifacts.
Examples: hibernate-entitymanager, ant
Module Descriptor
A module descriptor is a generic way of identifying what describes a module: the identifier (organisation, module name, branch and revision), the published artifacts, possible configurations and their dependencies.The most common module descriptors in Ivy are Ivy Files, xml files with an Ivy specific syntax, and usually called ivy.xml.
But since Ivy is also compatible with maven 2 metadata format (called pom, for Project Object Model), pom files fall into the category of module descriptors.
And because Ivy accepts pluggable module descriptor parsers, you can use almost whatever you want as module descriptors.
Artifact
An artifact is a single file ready for delivery with the publication of a module revision, as a product of development.Compressed package formats are often preferred because they are easier to manage, transfer and store. For the same reasons, only one or a few artifacts per module are commonly used. However, artifacts can be of any file type and any number of them can be declared in a single module.
In the Java world, common artifacts are Java archives or JAR files. In many cases, each revision of a module publishes only one artifact (like jakarta-log4j-1.2.6.tar.gz, for instance), but some of them publish many artifacts dependending on the use of the module (like apache-ant binary and source distributions in zip, gz and bz2 package formats, for instance).
Examples: ant-1.7.0-bin.zip, apache-ant-1.7.0-src.tar.gz
Type of an artifact
The artifact type is a category of a particular kind of artifact specimen. It is a classification based on the intended purpose of an artifact or why it is provided, not a category of packaging format or how the artifact is delivered.Although the type of an artifact may (rather accidentally) imply its file format, they are two different concepts. The artifact file name extension is more closely associated with its format. For example, in the case of Java archives the artifact type "jar" indicates that it is indeed a Java archive as per the JAR File specification. The file name extension happens to be "jar" as well. On the other hand, with source code distributions, the artifact type may be "source" while the file name extensions vary from "tar.gz", "zip", "java", "c", or "xml" to pretty much anything. So, the type of an artifact is basically an abstract functional category to explain its purpose, while the artifact file name extension is a more concrete technical indication of its format and, of course, naming.
Defining appropriate artifact types for a module is up to its development organisation. Common choices may include: "jar", "binary", "bin", "rc", "exe", "dll", "source", "src", "config", "conf", "cfg", "doc", "api", "spec", "manual", "man", "data", "var", "resource", "res", "sql", "schema", "deploy", "install", "setup", "distrib", "distro", "distr", "dist", "bundle", etc.
Module descriptors are not really artifacts, but they are comparable to an artifact type, i.e. "descriptor" (an ivy file or a Maven POM).
Electronic signatures or digests are not really artifacts themselves, but can be found with them in repositories. They also are comparable to an artifact type, i.e. "digest" (md5 or sha1).
Artifact file name extension
In some cases the artifact type already implies its file name extension, but not always. More generic types may include several different file formats, e.g. documentation can contain tarballs, zip packages or any common document formats.Examples: zip, tar, tar.gz, rar, jar, war, ear, txt, doc, xml, html
Module Revision and Status
Module revision
A unique revision number or version name is assigned to each delivered unique state of a module. Ivy can help in generating revision numbers for module delivery and publishing revisions to repositories, but other aspects of revision control, especially source revisioning, must be managed with a separate version control system.Therefore, to Ivy, a revision always corresponds to a delivered version of a module. It can be a public, shared or local delivery, a release, a milestone, or an integration build, an alpha or a beta version, a nightly build, or even a continuous build. All of them are considered revisions by Ivy.
Source revision
Source files kept under a version control system (like Subversion, CVS, SourceSafe, Perforce, etc.) have a separate revisioning scheme that is independent of the module revisions visible to Ivy. Ivy is unaware of any revisions of a module's source files.In some cases, the SCM's source revision number could be used also as the module revision number, but that usage is very rare. They are still two different concepts, even if the module revision number was wholly or partially copied from the respective source revision number.
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.
Status of a revision
A module's 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: a revision fully tested and labelled fall in this category
Configurations of a module
A module configuration is a way to use or construct a module. If the same module has different dependencies based on how it's used, those distinct dependency-sets are called its configurations in Ivy.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 different ways to use or build a module are called module configurations in ivy.
For more details on configurations and how they are used in ivy, please refer to the main concepts page.
Ivy Settings
Ivy settings files are xml files used to configure ivy to indicate where the modules can be found and how.History of settings
Prior to Ivy 2.0, the settings files were called configuration files and usually named ivyconf.xml. This resulted in confusion between module configurations and Ivy configuration files, so they were renamed to settings files. If you happen to fall on an ivyconf file or something called a configuration file, most of the time it's only unupdated information (documentation, tutorial or article). Feel free to report any problem like this if you find such an inconsistency.Repository
What is called a repository in Ivy is a distribution site location where Ivy is able to find your required modules' artifacts and descriptors (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
Moreover, the fact that it is the responsibility of the resolver to find ivy files and download artifacts helps to implement various resolving strategies.
As you see, a dependency resolver can be thought of as a class responsible for 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 because ivy can't work without configurations. 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 get better dependencies resolution, configurations will meet most of your needs.
For details on how to declare your module configurations, how to 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 you 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 overridden, whereas ant
properties can't, and that they are defined in separate environments.
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 the 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 encounters 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 (actually they are first loaded as ant properties and then imported as ivy variables, see Ant Tasks), 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 ivysettings.properties file. Some variables will really only be able to be overridden via ant properties because of this.
Moreover, it's also important to understand the difference between ivy variables and ivy pattern tokens.
See the Patterns chapter below for 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 a hyphen, then the revision, a dot, and the artifact extension.
Not too difficult to understand is 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)
since 1.2 [organization] can be used instead of [organisation].
since 1.3 Optional parts can be used in patterns.
This provides 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]lets 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 of artifact names.
since 1.4 Extra attributes can be used as any other token in a pattern.
Latest Strategy
Ivy often needs to know which revision between two is considered the "latest". To know that, it uses the concept of latest strategy. Indeed, there are several ways to consider a revision to be the latest. You can choose an existing one or plug in your own.But before knowing which revision is the latest, ivy needs to be able to consider several revisions 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 does 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 the revisions is the latest one.
Ivy has three built-in latest strategies:
- latest-time This 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 of being costly to compute for 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 This compares the revisions as strings, using an algorithm close to the one used in the php version_compare function.
- latest-lexico This compares the revisions as strings, using lexicographic order (the one used by the Java string comparison).
This algorithm takes into account special meanings 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.
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 select a list of revisions, even if most conflict managers 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.
For more details on how to setup your conflict managers by module, see the conflicts section in the ivy file reference.
Pattern matcher
since 1.3 In several places Ivy uses a 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 a pluggable pattern matcher to match those object names. 3 are defined by default:
- exact This matcher matches only using strings
- regexp This matcher lets you use a regular expression as supported by the Pattern class of java 1.4 or greater
- glob This matcher lets you use a 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.
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.
since 2.0 It's possible and recommended to use xml namespaces for your extra attributes. Using an Ivy extra namespace is the easiest way to add your own extra attributes.
Example:
Here is an ivy file with the attribute 'color' set to blue:
<ivy-module version="2.0" xmlns:e="http://ant.apache.org/ivy/extra">Then you must use the extra attribute when you declare a dependency on foo. Those extra attributes
<info organisation="apache"
module="foo"
e:color="blue"
status="integration"
revision="1.59"
/>
</ivy-module>
will indeed be used as identifiers for the module like the org the name and the revision:
<dependency org="apache" name="foo" e:color="blue" rev="1.5+" />And you can define your repository pattern as:
${repository.dir}/[organisation]/[module]/[color]/[revision]/[artifact].[ext]
Note that in patterns you must use the unqualified attribute name (no namespace prefix).If you don't want to use xml namespaces, it's possible but you will need to disable ivy file validation, since your files won't fulffill anymore the official ivy xsd. See the settings documentation to see how to disable validation.
Checksums
since 1.4 Ivy allows the use of checksums, also known as digests, to verify the correctness of a downloaded file.For the moment Ivy supports the md5 and sha1 algorithms.
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 algorithms 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 an 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 allows, for example, you 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 events 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 a warning (default)
- error halt the dependency resolution when a circular dependency is found
Cache and Change Management
Ivy heavily relies on local caching to avoid accessing remote repositories too often, thus saving a lot of network bandwidth and time.Cache types
An Ivy cache is composed of two different parts:- the repository cache The repository cache is where Ivy stores data downloaded from module repositories, along with some meta information concerning these artifacts, like their original location.
- the resolution cache This part of the cache is used to store resolution data, which is used by Ivy to reuse the results of a resolve process.
This part of the cache can be shared if you use a well suited lock strategy.
This part of the cache is overwritten each time a new resolve is performed, and should never be used by multiple processes at the same time.
Change management
To optimize the dependency resolution and the way the cache is used, Ivy assumes by default that a revision never changes. So once Ivy has a module in its cache (metadata and artifacts), it trusts the cache and does not even query the repository. This optimization is very useful in most cases, and causes no problem as long as you respect this paradigm: a revision never changes. Besides performance, there are several good reasons to follow this principle.However, depending on your current build system and your dependency management strategy, you may prefer to update your modules sometimes. There are two kinds of changes to consider:
Changes in module metadata
Since pretty often module metadata are not considered by module providers with as much attention as their API or behavior (if they even provide module metadata), it happens more than we would like that we have to update module metadata: a dependency has been forgotten, or another one is missing, ...In this case, setting checkModified="true" on your dependency resolver will be the solution. This flag tells Ivy to check if module metadata has been modified compared to the cache. Ivy first checks the metadata last modified timestamp on the repository to download it only if necessary, and then updates it when needed.
Changes in artifacts
Some people, especially those coming from maven 2 land, like to use one special revision to handle often updated modules. In maven 2 this is called a SNAPSHOT version, and some argue that it helps save disk space to keep only one version for the high number of intermediary builds you can make whilst developing.Ivy supports this kind of approach with the notion of "changing revision". A changing revision is just that: a revision for which Ivy should consider that the artifacts may change over time. To handle this, you can either specify a dependency as changing on the dependency tag, or use the changingPattern and changingMatcher attributes on your resolvers to indicate which revision or group of revisions should be considered as changing.
Once Ivy knows that a revision is changing, it will follow this principle to avoid checking your repository too often: if the module metadata has not changed, it will considered the whole module (including artifacts) as not changed. Even if the module descriptor file has changed, it will check the publication data of the module to see if this is a new publication of the same revision or not. Then if the publication date has changed, it will check the artifacts' last modified timestamps, and download them accordingly.
So if you want to use changing revisions, use the publish task to publish your modules, it will take care of updating the publication date, and everything will work fine. And remember to set checkModified=true" on your resolver too!
Paths handling
As a dependency manager, Ivy has a lot of file related operations, which most of the time use paths or path patterns to locate the file on the filesystem.These paths can obviously be relative or absolute. We recommend to always use absolute paths, so that you don't have to worry about what is the base of your relative paths. Ivy provides some variables which can be used as the base of your absolute paths. For instance, Ivy has a concept of base directory, which is basically the same as for Ant. You have access to this base directory with the ivy.basedir variable. So if you have a path like
${ivy.basedir}/ivy.xml, you have an absolute path. In settings files, you also have a variable called ivy.settings.dir which points to the directory in which your settings file is located, which makes defining paths relative to this directory very easy.If you really want to use relative paths, the base directory used to actually locate the file depends on where the relative path is defined:
- In an Ivy file, paths are relative to the Ivy file itself (the only possible path in an Ivy file is for configurations declaration inclusion)
- In settings files, paths for file inclusion (namely properties file loading and settings inclusion) are relative to the directory in which the settings file is located. All other paths must be absolute unless explicitly noted.
- In Ivy Ant tasks and Ivy parameters or options, paths are relative to Ivy base directory, which when called from Ant is the same as your Ant basedir.
Text Conventions
Very often some concepts discussed in Ivy here, and especially those involving modules and dependencies, require to be discussed by text (e-mail, textual doc, console, ...), and so benefit from convention in this area.
The conventions have been adopted with Ivy 2.0 are the following:
|
what |
pattern |
example |
|
a module without revision |
[organisation]#[module] |
org.apache.ant#ant |
|
a module with revision |
[organisation]#[module];[revision] |
org.apache.ant#ant;1.7.0 |
|
a module with (some) configurations |
[organisation]#[module][ [confs] ] |
org.apache.ant#ant[master,compile,build] |
|
a module with revision and (some) configurations |
[organisation]#[module];[revision][ [confs] ] |
org.apache.ant#ant;1.7.0[master,compile,build] |
|
a module's artifact |
[organisation]#[module]![artifact].[ext]([type]) |
org.apache.ant#ant!ant.jar(source) |
|
a module's artifact with revision |
[organisation]#[module];[revision]![artifact].[ext]([type]) |
org.apache.ant#ant;1.7.0!ant.jar(source) |
Another usual text representation used is to represent dependencies using a dash followed by greater than sign: ->
To group a set of set of modules, we recommend using curly braces { }
With these conventions, it's easy to give a concise and detailed overview of a set of modules and their dependencies.
For instance:
#A;2-> { #B;[1.0,1.5] #C;[2.0,2.5] }
#B;1.4->#D;1.5
#B;1.5->#D;2.0
#C;2.5->#D;[1.0,1.6]
In full words here is how it could be written:
module A revision 2 depends on module B with the version constraint [1.0,1.5], and on module C with the version constraint [2.0,2.5].As you can see, using text conventions is much more concise.
module B revision 1.4 depends on module D revision 1.5.
module B revision 1.5 depends on module D revision 2.0.
module C revision 2.5 depends on module D with the version constraint [1.0,1.6].
Another benefit is that these conventions are usually used in Ivy console output, and can also be used in some cases to be parsed into Ivy objects (we use it for test cases for instance). To make sure text parsing works fine, we recommend using only a limited range of characters for each attributes of your module identifiers.
Here is the recommended characters set for each attribute:
- organisation a-z A-Z 0-9 - / . _ + =
- module a-z A-Z 0-9 - / . _ + =
- branch a-z A-Z 0-9 - / . _ + =
- revision a-z A-Z 0-9 - / . _ + = , [ ] { } ( ) : @
- artifact a-z A-Z 0-9 - / . _ + =
- extension a-z A-Z 0-9 - / . _ + =
- type a-z A-Z 0-9 - / . _ + =
How does it work ?
Now that you have been introduced to the main ivy terminology and concepts, it is time to give some explanation of how ivy works.
Usual cycle of modules between different locations
Configure
Ivy needs to be configured to be able to resolve your dependencies. This configuration is usually done with a settings file, which defines a set of dependency resolvers. Each resolver is able to find ivy files and/or artifacts, given simple information such as organisation, 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 resolves 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 settings) 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 the ivy cache. Then ivy checks if the dependency module has dependencies, in which case it recursilvely traverses the graph of dependencies.
All over this traversal, conflict management is done to prevent access to a module as soon as possible.
When ivy has traversed the whole graph, it asks the resolvers to download the artifacts corresponding to each of the dependencies which are not already in the cache and which have not been evicted by conflict managers. All downloads are made to the ivy cache.
Finally, an xml report is generated in the cache, which allows ivy to easily know what are all the dependencies of a module, without traversing the graph again.
After this resolve step, two main steps are possible: either build a path with artifacts in the cache, or copy them to another directory structure.
Retrieve
What is called retrieve in ivy is the act of copying 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 the 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 the 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 when building plug-ins for IDEs.
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 future resolving. This task is usually called either manually or from a continuous integration server.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 produces as artifacts 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 such module descriptors themselves.
First, it will seem like extra work and require time. But when you have several modules using the same third party library, then 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 adding ivy files for all the modules in your repository. You can even enforce this rule by setting the descriptor attribute to required 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:- control The main problem with these kinds of public repositories is that you don't have control over the repository. This means that if a module descriptor is broken you cannot easily fix it. Sure you can use a chain between a shared repository and the public one and put your fixed module descriptor in the shared repository so that it hides the one on the public repository, but this makes repository browsing and maintenance cumbersome.
- reliability The Maven repository is not particularly well known for its reliability (we often experience major slow downs or even complete failures of the site), and ivyrep is only supported by a small company (yes we are only a small company!). So slow down and site hangs occur also. And if the repository you rely on is down, this can cause major slow downs in your development or release process.
- accuracy A public repository usually contains much more than what you actually need. Is this a problem? We think so. We think that in an enterprise environment the libraries you use should step through some kind of validation process before being used in every projects of your company. And what better way to do so? Setup an enterprise repository with only the libraries you actually want to use. This will not only ensure better quality for your application dependencies, but help to have the same versions everywhere, and even help when declaring your module dependencies, if you use a tool like IvyDE, the code completion will only show relevant information about your repository, with only the libraries you actually want to see.
- security The artifacts you download from a module repository are often executable, and are thus a security concern. Imagine a hacker replacing commons-lang by another version containing a virus? If you rely on a public repository to build your software, you expose it to a security risk. You can read more about that in this Forrester article.
Even more problematic is the possible updates of the repository. We know that versions published in such repositories should be stable and not be updated, but we also frequently see that a module descriptor is buggy, or an artifact corrupted. We even see sometimes a new version published with the same name as the preceding one because the previous one was simply badly packaged. This can occur even to the best; it occurred to us with Ivy 1.2 :-) But then we decided to publish the new version with a different name, 1.2a. But if the repository manager allows such updates, this means that what worked before can break. It can thus break your build reproducibility.
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 always using the organisation and the module name in your pattern, even for a private repository where you put only your own modules (which all have the same organisation). Why? Because the Ivy listing feature relies 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 repreport.Public ivysettings.xml with public repositories
If you create a public repository, provide a URL to the ivysettings.xml file. It's pretty easy to do, and if someone wants to leverage your repository, he will just have to load it with settings with the URL of your ivysettings.xml file, 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:
- use a naming convention like a special suffix the idea is pretty simple, each time you publish a new integration of your module you give the same name to the version (in maven world this is for example 1.0-SNAPSHOT). The dependency manager should then be aware that this version is special because it changes over time, so that it does not trust its local cache if it already has the version, but checks the date of the version on the repository and sees if it has changed. In Ivy this is supported using the changing attribute on a dependency or by configuring the changing pattern to use for all your modules.
- automatically create a new version for each in this case you use either a build number or a timestamp to publish each new integration version with a new version name. Then you can use one of the numerous ways in Ivy to express a version constraint. Usually selecting the very latest one (using 'latest.integration' as version constraint) is enough.
But usually we recommend using 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 ones. And this is interesting because it enables, with some work in your build system, the ability 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 who comes on a Monday morning and asks for the latest version of your software, for testing or demonstration purposes. Obviously he needs it for the afternoon :-) Now if you have a continuous integration process and good tracking of your changes and your artifacts, it may occur to you that you are actually able to fulfill his request without needing the use of a DeLorean to give you some more time :-) But it may also occur to you that your latest version is stable enough to be used for the purpose of the customer, but was actually built a few days ago, because the very latest just broke a feature or introduced a new one you don't want to deliver. You can deliver this 'stable' integration build if you want, but rest assured 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 asks 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 for 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 you 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:
- separate revision cycle if your dependencies may change more often than your build, it's a good idea to separate the two, to isolate the two concepts: describing how to build / describing your project dependencies
- possibility to publish if you describe dependencies of a module which can itself be reused, you may want to use ant to publish it to a repository. In this case the publication is only possible if you have a separate ivy file
- more flexible inline dependencies can only be used to express one dependency and only one. An ivy file can be used to express much more complex dependencies
- you want to use a custom task in your ant build Without ivy you usually either copy the custom task jar in ant lib, which requires maintenance of your workstation installation, or use a manual copy or download and a taskdef with the appropriate classpath, which is better. But if you have several custom tasks, or if they have themselves dependencies, it can become cumbersome. Using Ivy with an inline dependency is an elegant way to solve this problem.
- you want to easily deploy an application If you already build your application and its modules using Ivy, it is really easy to leverage your ivy repository to download your application and all its dependencies on the local filesystem, ready to be executed. If you also put your configuration files as artifacts in your repository (maybee packaged as a zip), the whole installation process can rely on ivy, easing the automatic installation of any version of your application available in your repository!
Hire an expert
Build and dependency management is often given too low a 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 savings 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.
Feedback
These best practices reflect 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.
Installation
There are basically two ways 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 into 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:org.apache.ivy.ant"
- add taskdefs for ivy tasks:
<taskdef name="ivy-configure" classname="org.apache.ivy.ant.IvyConfigure"/>- replace ivy:xxx tasks by ivy-xxx
<taskdef name="ivy-resolve" classname="org.apache.ivy.ant.IvyResolve"/>
<taskdef name="ivy-retrieve" classname="org.apache.ivy.ant.IvyRetrieve"/>
<taskdef name="ivy-publish" classname="org.apache.ivy.ant.IvyPublish"/>
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 might be the problem with the ivyrep resolver.
Ivy dependendencies
One of the two binary versions of Ivy doesn't include the optional dependencies. To download them using Ivy, all you need is to run the Ant build file provided in the distribution. This will use Ivy itself to download the dependencies. Then you should see the Ivy optional dependencies in the lib directory, organized per configuration (see the ivy.xml for details about the configurations and their use).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="2.1.0-rc2" />
<condition property="ivy.home" value="${env.IVY_HOME}">
<isset property="env.IVY_HOME" />
</condition>
<property name="ivy.home" value="${user.home}/.ant" />
<property name="ivy.jar.dir" value="${ivy.home}/lib" />
<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://repo2.maven.org/maven2/org/apache/ivy/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="org/apache/ivy/ant/antlib.xml"
uri="antlib:org.apache.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 the ivy namespace to your build script. See the self contained go-ivy example for details about this.Settings Files
In order to work as you want, ivy sometimes needs some settings. Actually, ivy can work with no specific settings at all, see the default settings documentation for details about that. But ivy is able to work in very different contexts. You just have to configure it properly.
Settings are specified through an xml file, usually called ivysettings.xml. To configure ivy from ant, you just have to use the settings datatype with the path of your settings file.
Here is an example of the settings file:
<ivysettings>
<properties file="${ivy.settings.dir}/ivysettings-file.properties" />
<settings 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>
</ivysettings>
Mainly, the settings enable you to configure the default cache directory used by ivy and the dependency resolvers that it will use to resolve dependencies.
Note: To work, this settings file needs a property file named ivysettings-file.properties in the same directory as the settings file, with ivy variables you want in it.
Some useful variables are available in settings files:
- ivy.settings.dir this variable references the directory in which the ivysettings itself is. This is available if the settings has been loaded as a file. In case of a URL, it takes the part before the last slash of the URL, if any. If the URL has no slash, then this variable is not set.
- ivy.settings.file the path of the settings file itself if it has been loaded as a file only. If it has been loaded as a URL, this variable is not set
- ivy.settings.url the URL pointing to the settings file. This is set both when it has been loaded as a file or a URL
Settings file structure
The settings file is structured in some parts and left open in others. Indeed, each resolver has its own structure, thus it's not the settings file itself which defines the structure for the resolvers.ivysettings
property
properties
settings
include
classpath
typedef
credentials
lock-strategies
caches
cache
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
ivysettings
Tag: ivysettingsRoot tag of any ivysettings file.
Child elements
| Element | Description | Cardinality |
|---|---|---|
| property | set an ivy variable | 0..n |
| properties | loads a properties file as ivy variables | 0..n |
| settings | configures ivy with some defaults | 0..1 |
| include | includes another settings file | 0..n |
| classpath | add a location in the classpath used to load plugins | 0..n |
| typedef | defines new types in ivy | 0..n |
| lock-strategies | defines lock strategies | 0..1 |
| caches | defines repository cache managers | 0..1 |
| 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 you to avoid overriding the previous value of the variable, which makes the definition behave like an ant property, 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 the variables chapter above for details about ivy variables.
Since 2.0: it is possible to access environment variables. This can be done by specifying the environment attribute. This attribute specifies the prefix which can be used to access these environment variables. For instance, if you specify environment="env", you can access the PATH environment variable with the env.PATH property name.
Attributes
| Attribute | Description | Required |
|---|---|---|
| file | a path to a properties file to load | One of these |
| environment | the prefix to use when retrieving environment variables (since 2.0) | |
| override | indicates if the variable found in the properties file should override its previous value, if any (since 1.3) | No, defaults to true |
settings
Tag: settings
Configures some important ivy info: default resolver, latest strategy, conflict manager... The default resolver is used whenever nothing else is configured in the modules section of the settings file. It should give the name of a dependency resolver defined in the resolvers section of the settings file.
The default latest strategy and conflict manager can also be configured here.
validate indicates if ivy files should generally be validated against the xsd or not. This setting is only a default value, and can be overridden:
1) in ant tasks
2) in resolvers
So if there is a setting in the resolver, it always wins against all other settings.
Attributes
| Attribute | Description | Required |
|---|---|---|
| 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 |
| defaultResolveMode | the default resolve mode to use for all modules, except if they have a module specific resolve mode setting. since 2.0 | No, defaults to 'default' |
| 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 |
| 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 |
| httpRequestMethod | specifies the HTTP method to use to retrieve information about an URL. Possible values are 'GET' and 'HEAD'. This setting can be used to solve problems with firewalls and proxies. (since 2.0) | No, defaults to 'HEAD' |
| a path to a directory to use as default basedir for both resolution and repository cache(s). Deprecated, we recommend using defaultCacheDir on the caches tag instead |
No, defaults to .ivy2/cache in user home | |
| Indicates if date should be checked before retrieving artifacts from cache. Deprecated, we recommend using overwriteMode on the retrieve task instead |
No, defaults to true | |
| a pattern to indicate where ivy files should be put in cache. Deprecated, we recommend using ivyPattern on the caches tag instead |
No, defaults to [organisation]/[module]/ivy-[revision].xml | |
| a pattern to indicate where artifact files should be put in cache. Deprecated, we recommend using artifactPattern on the caches tag instead |
No, defaults to [organisation]/[module]/[type]s/[artifact]-[revision].[ext] |
include
Tag: include
Includes another ivysettings file as if it were part of this one. since 1.3 The included ivysettings file has to be a complete well formed ivysettings file, i.e. it does have to include the
<ivysettings>tag.
Attributes
| Attribute | Description | Required |
|---|---|---|
| url | a URL to the ivysettings file to include | Yes, unless file is specified |
| file | a path to the ivysettings file to include | Yes, unless url is specified |
Examples
<ivysettings>with ivysettings-default.xml:
<property name="myrepository" value="path/to/my/real/rep"/>
<settings defaultResolver="default"/>
<include file="path/to/ivysettings-default.xml"/>
</ivysettings>
<ivysettings>The included ivysettings 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 override the value given in the main ivysettings including this one, so the value used for myrepository will be path/to/my/real/rep.
<property name="myrepository" value="path/to/rep" overwrite="false"/>
<resolvers>
<ivyrep name="default" ivyroot="${myrepository}"/>
</resolvers>
</ivysettings>
<ivysettings>with ivysettings-macro.xml being the ivysettings example given on the macrodef documentation page.
<include file="ivysettings-macro.xml"/>
<resolvers>
<mymacro name="includeworks" mymainrep="included/myrep" mysecondrep="included/secondrep"/>
</resolvers>
</ivysettings>
This lets us easily reuse the custom macro resolver.
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 an external classpath (the ant classpath for instance), therefore easing the use of ivy in multiple execution environments (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
<ivysettings>Adds the custom-resolver.jar (found in the same directory as the ivysettings.xml file) to the classpath, then defines a custom resolver and uses it.
<classpath file="${ivy.settings.dir}/custom-resolver.jar"/>
<typedef name="custom" classname="org.apache.ivy.resolver.CustomResolver"/>
<resolvers>
<custom name="custom"/>
</resolvers>
</ivysettings>
<ivysettings>Same as above, but finds the jar on a web server.
<classpath url="http://www.myserver.com/ivy/custom-resolver.jar"/>
<typedef name="custom" classname="org.apache.ivy.resolver.CustomResolver"/>
<resolvers>
<custom name="custom"/>
</resolvers>
</ivysettings>
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
| Attribute | Description | Required |
|---|---|---|
| name | the name of the type to define. This name is then used as an xml tag. | Yes |
| classname | the fully qualified class name of the type to define. | Yes |
credentials
Tag: credentials
Configures HTTP authentication credentials. since 2.0.
Attributes
| Attribute | Description | Required |
|---|---|---|
| host | the name of the host | Yes |
| realm | the name of the realm | No |
| username | the username | Yes |
| passwd | the password | Yes |
signers
Tag: signers
since 2.2 Defines a list of detached signature generators usable in ivy. Each generator is identified by its name, given as an attribute.
The child tags used to configure the signature generator must be equal to the name of a signature generator type (either built-in or added with the typedef tag). Ivy supports the following signature generator out of the box:
- pgp generates an OpenPGP compatible ASCII armored detached signature.
Child elements
| Element | Description | Cardinality |
|---|---|---|
| any signature generator | adds a signature generator to the list of registered generators | 1..n |
Built-in Generators
PGP
This generator is capable of generating an OpenPGP compatible ASCII armored detached signature.Remark: This generator uses the BouncyCastle OpenPGP library. Before this generator can be used, these libraries must be available on Ivy's classpath.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the signature generator. | Yes |
| secring | The location of the secret keyring. | No, defaults to ${user.home}/.gnupg/secring.gpg |
| keyId | The identifier of the key to use. The keyword 'auto' can be used to indicate a key will be selected automatically. | No, defaults to 'auto'. |
| password | The password of the private key. | Yes |
Examples
<signers>Defines a detached signature generator with name 'mypgp' which uses the secret key ring on the default location and automatically selects a private key.
<pgp name="mypgp" password="my-password" />
</signers>
<signers>Same as before, but this time the key '123ABC45' is used to generate the detached signature.
<pgp name="mypgp" password="my-password" keyId="123ABC45"/>
</signers>
lock-strategies
Tag: lock-strategies since 2.0 Defines a list of lock strategies usable in Ivy. A lock strategy is used by a cache manager to decide when and how locking should be performed (see settings/cache to see how to configure the lock strategy to use).
Two lock strategies are registered by default:
- no-lock This lock strategy actually performs no locking at all, and thus should not be used in an environment where the cache is shared by multiple processes.
- artifact-lock This strategy acquires a lock whenever a module descriptor or an artifact is downloaded to the cache, which makes a good solution when you want to share your repository cache.
This strategy is implemented by (NoLockStrategy)
Note that this strategy is based on file locking, performed by default using the java.io.File.createNewFile() atomicity (which is documented as atomic in the javadoc, but not recommended to perform locks). A java.nio.FileLock based implementation is also provided, but according to our tests the createNewFile based one performs better and more reliably. We heavily recommend making your own testing in your target environment before relying on this lock strategy for heavily concurrent operations.
This strategy is implemented by (ArtifactLockStrategy)
Child elements
| Element | Description | Cardinality |
|---|---|---|
| any lock strategy | adds a lock strategy to the list of available ones | 0..n |
caches
Tag: caches
Configures the Ivy cache system. since 2.0.
See cache concept for details on the Ivy cache concept.
By default, Ivy defines one repository cache instance, called 'default-cache', which uses the default cache settings defined using attributes on this tag. This default instance is defined as long as you don't define your own default cache using the 'default' attribute, and have at least one dependency resolver which doesn't specify which cache instance to use.
defaultCacheDir is the default directory used for both the resolution and repository cache(s). It usually points to a directory in your filesystem. If you want to isolate resolution cache from repository cache, we recommend setting both the resolutionCacheDir and repositoryCacheDir attributes on this tag instead of using defaultCacheDir.
Since repository cache implementations are pluggable, you can either define new cache instances based on the default implementation provided in Ivy using the cache child element, or use custom cache implementations using child elements as you have defined using typedef.
ivyPattern and artifactPattern are used to configure the default way Ivy stores ivy files and artifacts in repository cache(s). Usually you do not have to change this, unless you want to use the cache directly from another tool, which is not recommended. These patterns are relative to the repository cache base directory.
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.
Attributes
| Attribute | Description | Required |
|---|---|---|
| default | the name of the default cache to use on all resolvers not defining the cache instance to use | No, defaults to a default cache manager instance named 'default-cache' |
| defaultCacheDir | a path to a directory to use as default basedir for both resolution and repository cache(s) | No, defaults to .ivy2/cache in the user's home directory |
| resolutionCacheDir | the path of the directory to use for all resolution cache data | No, defaults to defaultCacheDir |
| repositoryCacheDir | the path of the default directory to use for repository cache data. This should not point to a directory used as a repository! | No, defaults to defaultCacheDir |
| ivyPattern | default pattern used to indicate where ivy files should be put in the repository cache(s) | No, defaults to [organisation]/[module]/ivy-[revision].xml |
| artifactPattern | default pattern used to indicate where artifact files should be put in the repository cache(s) | No, defaults to [organisation]/[module]/[type]s/[artifact]-[revision].[ext] |
| Indicates if date should be checked before retrieving artifacts from cache. Deprecated, we recommend using overwriteMode on the retrieve task instead |
No, defaults to true | |
| useOrigin | the default value to use for useOrigin for caches in which it isn't specifically defined. Use true to avoid the copy of local artifacts to the cache and use directly their original location. |
No, defaults to false |
| lockStrategy | the name of the default lock strategy to use when accessing repository cache(s) | No, defaults to no-lock |
Child elements
| Element | Description | Cardinality |
|---|---|---|
| cache | defines a new repository cache instance, based on the default repository cache implementation | 0..n |
Examples
<caches>Define 2 cache instances, named mycache and mycache2, using two different directories as base directory, and using the default patterns and lock strategies. The default cache instance will still be defined as long as at least one dependency resolver does not declare which cache manager to use.
<cache name="mycache" basedir="path/to/my/cache/1" />
<cache name="mycache2" basedir="path/to/my/cache/2" />
</caches>
cache
Tag: cache
Since 2.0.
Defines a repository cache instance based on the default repository cache implementation. The default repository cache implementation caches files on the local filesystem in subdirectories of a configured base directory.
By default also, the parsed module descriptor read from the cache are kept in a memory cache in case they are reused. This may enhance the performance of multi-module build, provided that all modules are build using the same ivy instance. The size of this memory cache is configurable in term of number of module descriptors. A size of 0 means no memory caching.
Attributes
| Attribute | Description | Required |
|---|---|---|
| name | name of the cache instance | Yes |
| basedir | the path of the base directory to use to put repository cache data. This should not point to a directory used as a repository! | No, defaults to repositoryCacheDir defined in caches |
| ivyPattern | the pattern to use to store cached ivy files | No, defaults to default cache ivy pattern as configured in caches |
| artifactPattern | the pattern to use to store cached artifacts | No, defaults to default cache artifact pattern as configured in caches |
| useOrigin | true to avoid the copy of local artifacts to the cache and use directly their original location, false otherwise. 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 use the cache for some non local resolvers. In this case the cache will behave as usual, copying files to the cache. Note also that this only applies to artifacts, not to ivy files, which are still copied in the cache. |
No. defaults to the default value configured in caches |
| lockStrategy | the name of the lock strategy to use for this cache | No, defaults to default lock strategy as configured in caches |
| defaultTTL | the default TTL to use when no specific one is defined | No, defaults to ${ivy.cache.ttl.default} |
| memorySize | the number of parsed module descriptors to keep in a memory cache. | No, default to 150 |
Child elements
| Element | Description | Cardinality |
|---|---|---|
| ttl | defines a TTL rule | 0..n |
Examples
<cache name="mycache"Defines a cache called 'mycache', storing files in the '/path/to/mycache' directory using '[module]/ivy-[revision].xml' as pattern to store Ivy files and '[module]/[artifact]-[revision].[ext]' as pattern to store other artifacts.
basedir="/path/to/mycache"
ivyPattern="[module]/ivy-[revision].xml"
artifactPattern="[module]/[artifact]-[revision].[ext]"
lockStrategy="no-lock"
defaultTTL="1s">
<ttl revision="latest.integration" duration="200ms" />
<ttl organisation="org1" duration="10m 20s" />
<ttl organisation="org2" duration="5h" />
<ttl organisation="org3" duration="2d 12h" />
</cache>
The lock strategy used by this cache is the 'no-lock' strategy, which does not perform any locking.
The defaultTTL used is of 1s, meaning that by default dynamic revision result will be stored and used for one second. TTL rules then define that all 'latest.integration' revisions will be stored and used for 200ms, while other dynamic revisions from org1 org2 and org3 modules will be stored respectively for 10 minutes 20 seconds; 5 hours; and 2 days and 12 hours.
ttl
Tag: ttl
Since 2.0 Defines a TTL (Time To Live) rule for resolved revision caching. When Ivy resolves a dynamic version constraint (like latest.integration or a version range), it can store the result of the resolution (like latest.integration=1.5.1) for a given time, called TTL. It means that Ivy will reuse this dynamic revision resolution result without accessing the repositories for the duration of the TTL, unless running resolve in refresh mode.
This tag let you define a rule to define a TTL specific to a set of dynamic revision, based on the whole module revision information (organization, module name, revision, ...). The revision considered in the rule is the revision before the resolution (for instance 'latest.integration') and not the resolved revision (for instance '1.5.1').
The rules are evaluated in order, the first matching rule being used to define the TTL. If no rule matches, the cache defaultTTL will be used.
The format used to specify the TTL is of the form:
XXd XXh XXm XXs XXXmsWhere 'd' stands for days, 'h' for hours, 'm' for minutes, 's' for seconds and 'ms' for milliseconds. Any part of the specification can be omitted, so '12d', '2h 5m' and '1d 5ms' are all valid.
The TTL duration can also be set to 'eternal', in which case once resolved the revision is always use, except when resolving in refresh mode.
Using a 0ms TTL disable resolved revision caching for the given rule.
Attributes
| Attribute | Description | Required |
|---|---|---|
| organisation | the organisation to match to apply the rule. | No, defaults to * |
| module | the module's name to match to apply the rule. | No, defaults to * |
| revision | the module's revision to match to apply the rule. Note that the version is not resolved when evaluating the rule ('latest.integration' for instance). | No, defaults to * |
| any extra attribute | an extra attribute to match to apply the rule. | No, defaults to * |
| matcher | the matcher to use to match the modules to which the resolver should be applied | No, defaults to exact |
| duration | the TTL to apply (see above for format) | 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 included in Ivy by default 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's drawback is that it can be slow when dealing with remote repositories. If you use ivyrep,
- latest-revision compares the revisions as strings, using an algorithm close to the one used in php's version_compare function.
- latest-lexico compares the revisions as strings, using lexicographic order (the one used by java string comparison).
for example, Ivy has to ask the http server for the date of each ivy file before knowing which is the latest.
This algorithm takes into account the 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.
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>Knowing that the default "special meaning" words are the following:
<latest-revision name="mylatest-revision">
<specialMeaning name="PRE" value="-2"/>
<specialMeaning name="QA" value="4"/>
<specialMeaning name="PROD" value="5"/>
</latest-revision>
</latest-strategies>
<specialMeaning name="dev" value="-1"/>
<specialMeaning name="rc" value="1"/>
<specialMeaning name="final" value="2"/>
You can even remove 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 both a maven2 repository and an ivyrep, 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, their organisation is same as 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?Ivy's answer to this issue is called namespaces. In short, you can attach 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.
I have an error while trying to resolve module xxx. It says that it depends on [commons-httpclient commons-httpclient] and that it isn't available.
...
This very powerful feature is thoroughly used in the build your own repository tutorial, so is the best place to see an example 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 can be referenced by one of the resolvers. An overview of Namespaces is given in the namespaces documentation.
A namespace mainly consists of a list of rules, each rule defining a translation between a system namespace and the defined namespace, and vice versa.
There are two main possibilities for using these rules. By default, a namespace iterates through the rules, and when it finds one that translates the given name, it returns the translated name. But the namespace can be configured to 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 the namespace doc for details.
Child elements
| Element | Description | Cardinality |
|---|---|---|
| fromsystem | defines the translation to apply from the system namespace to the defined namespace | 1 |
| tosystem | defines the translation to apply from the defined namespace to the 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 another. This definition is very similar to the macrodef feature of ant for defining macro tasks. since 1.3 This task eases the process of creating a new dependency resolver, because it avoids writing java code.
It is generally used in combination with the include feature to help reuse a macro in multiple settings files.
A macro is defined by declaring an existing resolver within it. Then you can use attributes to pass parameters to the newly defined resolver type. Attributes are defined with a name, and optionally a default value, and are used using the following syntax:
@{attributename}
Resolvers names
Since you can use the same macro several times it can define several resolvers (in a chain for instance), the resolver names need to be chosen carefully to avoid name conflicts (each resolver must have a unique name).Here is how Ivy deals with the names of the resolvers defined in a macro:
- if there is no name attribute on a resolver in the macrodef, then Ivy will use the name given when using the macro. This is what usually should be done for the main resolver defined in the macro
- if there is a name attribute on a resolver in the macrodef, but this name doesn't contain a @{name} inside, then Ivy will use the provided name prefixed with the name of the macro separated by a dash
- if there is a name attribute on a resolver in the macrodef, and this name contains @{name} somewhere, then Ivy will use this name, and replace @{name} with the name provided when using the macro.
<ivysettings>This is equivalent to:
<macrodef name="mymacro">
<chain>
<ibiblio name="ex1" />
<ibiblio name="ex2.@{name}" m2compatible="true" />
</chain>
</macrodef>
<resolvers>
<mymacro name="default" />
<mymacro name="other" />
</resolvers>
</ivysettings>
<ivysettings>
<resolvers>
<chain name="default">
<ibiblio name="default-ex1" />
<ibiblio name="ex2.default" m2compatible="true" />
</chain>
<chain name="other">
<ibiblio name="other-ex1" />
<ibiblio name="ex2.other" m2compatible="true" />
</chain>
</resolvers>
</ivysettings>
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">Using it:
<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>
<resolvers>
<mymacro name="default" mymainrep="path/to/myrep"/>
</resolvers>
A complete example:
<ivysettings>
<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>
</ivysettings>
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 already been defined and NOT if it is defined later in the ivysettings 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 that handle most common needs.If you don't find the one you want here, you can also check if someone has contributed it on the links page, or even write your own.
There are basically two types of resolvers in Ivy: composite and standard. 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. |
| Packager | Standard | Finds ivy files and packaging instructions via URLs, then creates artifacts by following the instructions. |
| 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 features and attributes
All resolvers of the same type share some common features and attributes detailed here.Features
validation
All standard resolvers support several options for validation.The validate attribute is used to configure if ivy files should be checked against the ivy file xml schema.
The checkconsistency attribute allows you to enable or disable consistency checking between what is expected by Ivy when it finds a module descriptor, and what the module descriptor actually contains.
The descriptor attribute lets you define if module descriptors are mandatory or optional.
The checksums attribute is used to define the list of checksums files to use to check if the content of downloaded files has not been corrupted (eg during transfer).
force
Any standard resolver can be used in force mode, which is used mainly to handle local development builds. In force mode, the resolver attempts to find a dependency whatever the requested revision is (internally it replace the requested revision by 'latest.integration'), and if it finds one, it forces this revision to be returned, even when used in a chain with returnFirst=false.By using such a resolver at the beginning of a chain, you can be sure that Ivy will pick up whatever module is available in this resolver (usually a private local build) instead of the real requested revision. This allows to handle use case like a developer working on modules A and C, where A -> B -> C, and pick up the local build for C without having to publish a local version of B.
since 2.0
Attributes
| Attribute | Description | Required | Composite | Standard |
|---|---|---|---|---|
| name | the name which identifies the resolver | Yes | Yes | Yes |
| validate | indicates if resolved ivy files should be validated against ivy xsd | No, defaults to call setting | Yes | Yes |
| force | Indicates if this resolver should be used in force mode (see above). since 2.0 | No, defaults to false | No | 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. See cache and change management for details. | 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. See cache and change management for details. | 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 belons 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 |
| descriptor | 'optional' if a module descriptor (usually an ivy file) is optional for this resolver, 'required' to refuse modules without module descriptor since 2.0 | No, defaults to 'optional' | No (except dual) | Yes |
| allownomd | DEPRECATED. Use descriptor="required | optional" instead. 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 |
| cache | The name of the cache manager to use. | No, defaults to the value of the default attribute of caches | No | Yes |
| signer | The name of the detached signature generator to use when publishing artifacts. (since 2.2) | No, by default published artifacts will not get signed by Ivy. | No | Yes |
Examples
<resolvers>Defines a filesystem resolver, named '1', which is then used in two chains, the first which combines the filesystem resolver with an ivyrep resolver, and second which combines 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). Resolver 1 will use a cache named 'cache-1' which should have been defined under the caches element.
<filesystem name="1" cache="cache-1">
<ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${ivy.settings.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>
IvyRep Resolver
| Tag | ivyrep |
| Handle latest | yes, at least if the repository server is apache based |
| Handle publish | no |
Since ivyrep is not maintained anymore, the ivyroot attribute is mandatory, and the use of this resolver is not recommended (we recommend using url resolver as replacement in most cases).
Attributes
This resolver shares the common attributes of standard resolvers.| Attribute | Description | Required |
|---|---|---|
| ivyroot | the root of the ivy repository. | Yes, but may be provided through ${ivy.ivyrep.default.ivy.root} since 2.0 |
| 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" 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 |
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 a url resolver configured like this:
<url name="test" m2compatible="true">since 2.0 When used in m2compatible mode with the default pattern, this resolver uses maven-metadata.xml files (if present) to list the revisions available on the repository. This is especially useful when using a maven specific proxy, which does not serve directory listing. This can be disabled by using the useMavenMetadata flag.
<artifact pattern="http://repo1.maven.org/maven2/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
</url>
Limitation: in m2compatible mode, this resolver is not able list available organizations. It means some features like repreport are not available.
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 |
| useMavenMetadata | True if this resolver should use maven-metadata.xml files to list available revisions, false to use directory listing since 2.0 | No, defaults to true |
Examples
<ibiblio name="maven2" m2compatible="true"/>Defines a resolver called "maven2" using the maven 2 public repository to find module metadata (using maven 2 poms) and artifacts.
<ibiblio name="maven" m2compatible="true" usepoms="false"/>Same as above, but doesn't use poms, only artifacts.
Packager resolver
| Tag | packager |
| Handle latest | yes with http urls (and apache server) and with file urls, no with other urls |
| Handle publish | no |
Since 2.0.
This resolver accesses ivy files and "packaging instructions" from an online "packager" repository. "Packager" repositories contain no actual artifacts. To get the artifacts, the packaging instructions are downloaded from the repository and executed locally. These instructions specify additional resource(s) to download and how to create the artifacts from them, for example, by downloading a project's original distribution archive directly from their web site and extracting the desired artifacts.
Packager repositories allow the creation of Ivy repositories that require neither the participation of any of the modules' creators nor setting up a huge mirror site. One such repository on the web is Ivy RoundUp. Of course, private packager repositories are feasible as well.
The Packager resolver supports a "resource cache", where downloaded archives can be stored to avoid duplicate downloads. This cache is entirely separate from the normal Ivy cache: it is "private" to the Packager resolver, and it stores unmodified original software archives, not Ivy artifacts. See the resourceCache attribute below for details.
The packaging instructions are contained in "packager.xml" in a simple XML format. At resolve time this file gets converted into a "build.xml" file via XSLT and then executed using ant. Therefore, ant must be available as an executable on the platform. The ant task executes in a separate ant project and so is not affected by properties, etc. that may be set in any existing ant environment in which Ivy is running. However, Ivy will define a few properties for convenience; see the "Properties" listed below.
For security reasons, the XSLT transform ensures that (a) all downloaded archives have verified SHA1 checksums (including cached resources); and (b) only a very limited set of ant tasks can be performed during the artifact "build" phase; currently these include move, copy, mkdir, zip, unzip, tar, and untar (this restriction may be overridden however; see below).
The Packager resolver is based on the URL resolver and is configured similarly, except the artifact child tags specify where to find the packager.xml files, rather than the artifacts themselves.
Because the packaging process is relatively slow, it is important to use Ivy's caching support to avoid repeated execution of the packaging instructions.
Attributes
This resolver shares the common attributes of standard resolvers, plus the following:| Attribute | Description | Required |
|---|---|---|
| buildRoot | Defines the root of the temporary build directory hierarchy | Yes |
| resourceCache | Directory where downloaded resources should be cached | No; defaults to none |
| resourceURL | Ivy pattern that specifies a base URL to use for downloading all resources; overrides the URLs in the packaging instructions | No; defaults to none |
| restricted | True if this resolver should only allow "safe" ant tasks in the packaging instructions. Warning: setting restricted to false creates a security problem due to ant tasks like delete, exec, etc. Do not use this setting when your configuration points to an untrusted repository. | No; defaults to true |
| verbose | True to run ant with the -verbose flag | No; defaults to false |
| quiet | True to run ant with the -quiet flag | No; defaults to false |
| validate | True if this resolver should validate (via XSD) the downloaded XML packaging instructions | No; defaults to true |
| preserveBuildDirectories | True if this resolver should not delete the temporary build directories in which the ant tasks are executed (for debugging purposes) | No; defaults to false |
Setting a resourceURL will cause the resolver to override the URLs for resources specified by the packaging instructions. Instead, all resources will be downloaded from an URL constructed by first resolving the resourceURL pattern into a base URL, and then resolving the resource filename relative to that base URL. In other words, the resourceURL pattern specifies the URL "directory", so it should always end in a forward slash.
If a resourceURL download fails, the resolver will fall back to the original URL from the packaging instructions.
Configure a resourceURL in situations where you don't want to rely on (or wait for) the web sites configured in the packaging instructions, and have access to a better (perhaps private) mirror site.
Child elements
| Element | Description | Cardinality |
|---|---|---|
| ivy | Defines a pattern for ivy.xml files, using the pattern attribute | 1..n |
| artifact | Defines a pattern for packager.xml files, using the pattern attribute | 1..n |
Examples
<packager name="ivyroundup"Defines a packager resolver which points to the Ivy RoundUp online repository. Builds will occur in a subdirectory of
buildRoot="${user.home}/.ivy2/packager/build"
resourceCache="${user.home}/.ivy2/packager/cache"
resourceURL="ftp://mirror.example.com/pub/resources/[organisation]/[module]/">
<ivy pattern="http://ivyroundup.googlecode.com/svn/trunk/repo/modules/[organisation]/[module]/[revision]/ivy.xml"/>
<artifact pattern="http://ivyroundup.googlecode.com/svn/trunk/repo/modules/[organisation]/[module]/[revision]/packager.xml"/>
</packager>
${user.home}/.ivy2/packager/build downloaded resources will be cached in ${user.home}/.ivy2/packager/cache and the mirror site ftp://mirror.example.com/pub/resources/[organisation]/[module]/will be tried first for all resources.
Packaging Instructions
The goal of the packaging instructions is to download the required archives, extract the artifacts, and put the artifacts into a subdirectory. Each artifact should be written to artifacts/[type]s/[artifact].[ext] when the ant build completes.
Below is an example of packaging instructions for TestNG 2.5:
<packager-module version="1.0">Of course, packaging instructions must produce artifacts consistent with those listed in the associated ivy.xml file.
<property name="name" value="${ivy.packager.module}"/>
<property name="version" value="${ivy.packager.revision}"/>
<property name="zipname" value="${name}-${version}"/>
<resource dest="archive" url="http://testng.org/${zipname}.zip" sha1="2ea19275dc17453306f8bb780fe6ef6e9af7756b">
<url href="http://mirror.example.com/archives/${zipname}.zip"/>
<include name="${zipname}/src/main/**/*"/>
<include name="${zipname}/src/jdk15/**/*"/>
<include name="${zipname}/javadocs/**/*"/>
<include name="${zipname}/*.jar"/>
</resource>
<build>
<!-- jar -->
<move file="archive/${zipname}/${zipname}-jdk14.jar" tofile="artifacts/jars/${name}-jdk14.jar"/>
<move file="archive/${zipname}/${zipname}-jdk15.jar" tofile="artifacts/jars/${name}-jdk15.jar"/>
<!-- source -->
<zip destfile="artifacts/sources/${name}.zip">
<fileset dir="archive/${zipname}/src/main">
<include name="**/*.java"/>
</fileset>
<fileset dir="archive/${zipname}/src/jdk15">
<include name="**/*.java"/>
</fileset>
</zip>
<!-- javadoc -->
<zip destfile="artifacts/javadocs/javadoc.zip">
<fileset dir="archive/${zipname}/javadocs"/>
</zip>
</build>
</packager-module>
Build-time properties
This resolver ensures following ant properties are defined when it executes the ant build task.| Property | Description |
|---|---|
| ivy.packager.organisation | Organization of the ivy module whose artifacts are being built |
| ivy.packager.module | Module of the ivy module whose artifacts are being built |
| ivy.packager.revision | Revision of the ivy module whose artifacts are being built |
| ivy.packager.branch | Branch of the ivy module whose artifacts are being built |
| ivy.packager.resourceCache | The configured resourceCache if any; otherwise not defined |
| ivy.packager.resourceURL | The resolved resourceURL pattern if any; otherwise not defined |
Packager XML Elements
The packager.xml document element can contain the following child tags.| Element | Description | Cardinality |
|---|---|---|
| property | Set an ant property | 0..n |
| resource | Define a resource to download and (optionally) unpack | 0..n |
| m2resource | Define a Maven2 resource to download and (optionally) unpack | 0..n |
| build | Specify ant tasks that ultimately result in each artifact being placed into artifacts/[type]s/[artifact].[ext] | 0..1 |
Which ant tasks are allowed within the build tag is controlled by the restricted configuration attribute. When true (the default), only the following ant tasks are allowed: copy, jar, mkdir, move, tar, unjar, untar, unwar, unzip, war, and zip. When false, all ant tasks are allowed.
Warning: setting restricted to false creates a security problem due to ant tasks like delete, exec, etc. Do not use this setting when your configuration points to an untrusted repository.
Resource XML Elements
The resource XML tag supports the following attributes:| Attribute | Description | Required |
|---|---|---|
| url | Primary URL for the resource | Yes |
| sha1 | SHA1 checksum of the resource | Yes |
| dest | Defines the name of the subdirectory into which the artifact should be unpacked | No; defaults to "archive" |
| tofile | Where to put the file directly; if present no extraction will be performed | No; if present, "dest" is ignored |
| filename | Name of the file to download | No; if not present, same as the last component of the URL |
| type | Type of archive: "zip", "jar", "war", "tar", "tgz", "tar.gz", "tar.bz2" | No; if not present, will be automatically determined from the filename suffix |
The resource XML tag may contain child elements. An url tag with an href attribute specifies an alternate URL for the resource (see TestNG example above). Any other tags will be included as children of an automatically generated fileset tag.
Maven2 Resources
Special support is included for maven2 resources. For these resources, use the m2resource tag instead of the resource tag. Each m2resource tag specifies one or more artifacts that are downloaded from the Maven2 repository.M2Resource XML Elements
The m2resource XML tag supports the following attributes:| Attribute | Description | Required |
|---|---|---|
| groupId | Maven group ID | No; defaults to ${ivy.packager.organisation} |
| artifactId | Maven artifact ID | No; defaults to ${ivy.packager.module} |
| version | Maven version | No; defaults to ${ivy.packager.revision} |
| repo | Maven repository URL | No; defaults to http://repo1.maven.org/maven2/ |
Each m2resource XML tag must have one or more artifact tags that define the artifacts to directly download. The URL for each artifact is constructed automatically based on the attributes in the m2resource and artifact tags.
M2Resource Artifact Attributes
The artifact children of m2resource tags support the following attributes:| Attribute | Description | Required |
|---|---|---|
| ext | Maven filename extension | No; defaults to "jar" |
| classifier | Maven classifier (e.g., "sources", "javadoc") | No; defaults to none |
| sha1 | SHA1 checksum of the resource | Yes |
| dest | Defines the name of the subdirectory into which the artifact should be unpacked | Exactly one of "dest" or "tofile" must be supplied |
| tofile | Where to put the file; no extraction will be performed | |
| type | Type of archive: "zip", "jar", "war", "tar", "tgz", "tar.gz", "tar.bz2" | No; if not present, will be automatically determined from the filename suffix |
Below is an example of packaging instructions for the Apache Commons Email module. Note that no build tag is required because all of the maven2 artifacts are usable directly (i.e., without unpacking anything).
<packager-module version="1.0">
<m2resource>
<artifact tofile="artifacts/jars/${ivy.packager.module}.jar" sha1="a05c4de7bf2e0579ac0f21e16f3737ec6fa0ff98"/>
<artifact classifier="javadoc" tofile="artifacts/javadocs/javadoc.zip" sha1="8f09630f1600bcd0472a36fb2fa2d2a6f2836535"/>
<artifact classifier="sources" tofile="artifacts/sources/source.zip" sha1="15d67ca689a792ed8f29d0d21e2d0116fa117b7e"/>
</m2resource>
</packager-module>
File System resolver
| Tag | filesystem |
| Handle latest | yes |
| Handle publish | yes |
This resolver uses the file system to resolve ivy files and artifacts. An advantage of this resolver is that it usually provides very good performance. Moreover, it is easy to setup using basic OS file sharing mechanisms.
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. These patterns must be absolute paths (since 2.0). You can indicate a list of patterns which will be checked one after the other.
since 1.3 Using the m2compatible attribute, this resolver will convert dots found in organisation into 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.
Limitation: in m2compatible mode, this resolver is not able list available organizations. It means some features like repreport are not available.
Atomic publish support
since 2.0 This resolver supports atomic publish, which is useful for environments with a lot of concurrent publish and resolve actions. The atomic publish relies on the atomicity of the rename operation in the underlying filesystem (which includes NTFS and POSIX based filesystems).In this case the resolver starts by publishing the module according to the pattern, but where a '.part' suffix is appended to the revision. Then the publish is committed with a rename to the final location.
Limitations
Atomic publish is currently limited in several ways:
- you need to use a pattern for both the artifact and the ivy files which uses the revision as a directory. For instance "${repository.dir}/[module]/[revision]/[artifact].[ext]" works, "${repository.dir}/[module]/[artifact]-[revision].[ext]" doesn't
- both the artifact and ivy pattern should have the same prefix until the [revision] token.
- overwrite during publish is not supported
- you should not use revision names ending with '.part'
- auto use transaction if possible (according to limitation), otherwise don't
- true always use transaction, fail the build if a limitation is not fulfilled
- false don't use transaction at all
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 caches element for details. | No, defaults to true |
| transactional | true to force the use of transaction, false to prevent the use of transaction, auto to get transaction when possible since 2.0. See above for details. | No, defaults to auto |
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 | yes with http urls whose destination supports publishing (as of Ivy 2.0) |
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.
Limitation: in m2compatible mode, this resolver is not able list available organizations. It means some features like repreport are not available.
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">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).
<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>
Chain Resolver
| Tag | chain |
| Handle latest | depends on sub resolvers |
| Handle publish | delegates to first sub resolver in chain |
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">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.
<filesystem name="1">
<ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${ivy.settings.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
</filesystem>
<ivyrep name="2"/>
</chain>
<chain name="test" returnFirst="true">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.
<filesystem name="1">
<ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${ivy.settings.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
</filesystem>
<ivyrep name="2"/>
</chain>
<chain name="test" dual="true">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.
<filesystem name="1">
<ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
<artifact pattern="${ivy.settings.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
</filesystem>
<ivyrep name="2"/>
</chain>
Dual resolver
| Tag | dual |
| Handle latest | depends on sub resolvers |
| Handle publish | delegates to ivy sub resolver if artifact to publish is of "ivy" type, to artifact sub resolver otherwise |
Attributes
This resolver shares the common attributes of composite resolvers.Child elements
| Element | Description | Cardinality |
|---|---|---|
| any resolver | two 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 widespread 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">Will connect to myhost.com using myuser and prompt for the password.
<ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
<artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
</sftp>
<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>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.
<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>
<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 widespread 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 |
| publishPermissions | A four digit string (e.g., 0644, see "man chmod", "man open") specifying the permissions of the published files. (since 2.0) | No, defaults to scp standard behaviour |
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">Will connect to myhost.com using myuser and prompt for the password.
<ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
<artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
</ssh>
<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">Access ivy and artifacts files using sftp.
<ivy pattern="sftp://username:password@host/[organisation]/[module]/[revision]/ivy.xml" />
<artifact pattern="sftp://username:password@host/[organisation]/[module]/[revision]/[artifact].[ext]" />
</vfs>
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 built-in conflicts managers (which do not require anything in the configuration file):
- all this conflicts manager resolve conflicts by selecting all revisions. Also called the NoConflictManager, it doesn't evict any modules.
- 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.
- latest-compatible this conflict manager selects the latest version in the conflicts which can result in a compatible set of dependencies. This means that in the end, this conflict manager does not allow any conflicts (similar to the strict conflict manager), except that it follows a best effort strategy to try to find a set of compatible modules (according to the version constraints)
- strict this conflict manager throws an exception (i.e. causes a build failure) whenever a conflict is found.
Indeed direct dependencies can declare a force attribute (see dependency), which indicates that the revision given in the direct dependency should be preferred 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"/>
<compatible-cm name="my-latest-compatible-conflict-manager" latest="my-latest-strategy"/>
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 a pattern for module organisation and name, and giving some settings for the set, like the name of the corresponding resolver to use.
If no rules match a given module, the default setting will be used.
Note: You can greatly improve the performance of dependency resolution by configuring multiple smaller resolvers instead of one large resolver (i.e. chain). For instance, if you have a local repository for your modules and a remote repository for third party libraries, it is a good idea to have two separate resolvers, one for all of 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, name, revision and any extra attribute identifying your modules. The rule matching is performed in order, and is using a pattern matcher. Hence you can use * to specify all, or simply avoid specifying the attribute.
The revision and extra attributes are only used for rules defining the resolver to use. For other settings, use only organisation and module name.
It also gives the specific setting to use for this module set.
For each module set, you can configure:
- the resolver to use
- the conflict manager to use
- the default branch to use
- the resolve mode to use
Attributes
| Attribute | Description | Required |
|---|---|---|
| organisation | the organisation to match to apply the rule. | No, defaults to * |
| name | the module's name to match to apply the rule. | No, defaults to * |
| revision | the module's revision to match to apply the rule. Note that the version may not be resolved yet (be latest.integration for instance), so be very careful when using this attribute. since 2.0 | No, defaults to * |
| any extra attribute | an extra attribute to match to apply the rule. since 2.0 | No, defaults to * |
| matcher | the matcher to use to match the modules to which the resolver should be applied since 1.3 | No, defaults to exactOrRegexp |
| 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 |
| resolveMode | the resolve mode to use. since 2.0 | No |
Examples
<modules>Uses myprojectresolver for all modules from apache.
<module organisation="apache" name="*" resolver="myprojectsresolver"/>
</modules>
<modules>Uses myapachecommonsresolver for all modules beginning with 'commons-' from 'apache'.
<module organisation="apache" name="commons-*" matcher="glob" resolver="myapachecommonsresolver"/>
</modules>
<modules>Uses myapachecommonsresolver for all modules from apache beginning with 'commons-' followed by any number of alphabetic lowercase characters, and with the extra attribute 'myextra' having a value beginning with 'val.'.
<module organisation="apache" name="commons-[a-z]+" myextra="val.*" matcher="regexp" resolver="myapachecommonsresolver"/>
</modules>
<modules>Uses latest-time conflict manager for all modules from apache whose name begins with 'ivy'.
<module organisation="apache" name="ivy*" matcher="glob" conflict-manager="latest-time"/>
</modules>
<modules>Uses 'fix-103' as default branch for all modules from apache whose name begins with 'ivy'.
<module organisation="apache" name="ivy*" matcher="glob" branch="fix-103"/>
</modules>
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 |
---------------------------------------------------------------------
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 |
signers
Tag: signers
since 2.2 Defines a list of detached signature generators usable in ivy. Each generator is identified by its name, given as an attribute.
The child tags used to configure the signature generator must be equal to the name of a signature generator type (either built-in or added with the typedef tag). Ivy supports the following signature generator out of the box:
- pgp generates an OpenPGP compatible ASCII armored detached signature.
Child elements
| Element | Description | Cardinality |
|---|---|---|
| any signature generator | adds a signature generator to the list of registered generators | 1..n |
Built-in Generators
PGP
This generator is capable of generating an OpenPGP compatible ASCII armored detached signature.Remark: This generator uses the BouncyCastle OpenPGP library. Before this generator can be used, these libraries must be available on Ivy's classpath.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the signature generator. | Yes |
| secring | The location of the secret keyring. | No, defaults to ${user.home}/.gnupg/secring.gpg |
| keyId | The identifier of the key to use. The keyword 'auto' can be used to indicate a key will be selected automatically. | No, defaults to 'auto'. |
| password | The password of the private key. | Yes |
Examples
<signers>Defines a detached signature generator with name 'mypgp' which uses the secret key ring on the default location and automatically selects a private key.
<pgp name="mypgp" password="my-password" />
</signers>
<signers>Same as before, but this time the key '123ABC45' is used to generate the detached signature.
<pgp name="mypgp" password="my-password" keyId="123ABC45"/>
</signers>
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 ivysettings 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.<status> 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">Defines 3 statuses, gold, silver and bronze. The default status used when none is declared in an ivy file will be bronze.
<status name="gold" integration="false"/>
<status name="silver" integration="false"/>
<status name="bronze" integration="true"/>
</statuses>
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 3 type of triggers out of the box:
- ant-call calls a target in the same build as the original one whenever a particular event occurs.
- ant-build calls an ant build which may be in another ant build script.
- log echo a message, usually in a file
The following events are available in Ivy:
| Name | Attributes | Description |
|---|---|---|
| pre-resolve |
|
Fired at the beginning of the resolve process, before module dependencies and transitive dependencies are resolved. |
| pre-resolve-dependency |
|
Fired before each dependency is resolved. In this case resolved means resolving the actual revision if the requested revision is a version constraint and not a static version, and downloading all necessary metadata information. |
| post-resolve-dependency |
|
Fired after each dependency is resolved |
| post-resolve |
|
Fired at the end of the resolve process, when all module dependencies have been resolved |
| pre-download-artifact |
|
Fired before an artifact is downloaded from a repository to the cache |
| post-download-artifact |
|
Fired after an artifact has been downloaded from a repository to the cache |
| pre-retrieve since 2.0 |
|
Fired at the beginning of the retrieve process. |
| post-retrieve since 2.0 |
|
Fired at the end of the retrieve process. |
| pre-retrieve-artifact since 2.1 |
|
Fired before an artifact is retrieved from the cache to a local location |
| post-retrieve-artifact since 2.1 |
|
Fired after an artifact is retrieved from the cache to a local location |
| pre-publish-artifact since 2.0 |
|
Fired before an artifact is published into a repository |
| post-publish-artifact since 2.0 |
|
Fired after an artifact is published into a repository. Note that this event is fired whether or not the publication succeeded. The "status" property can be checked to verify success. |
Child elements
| Element | Description | Cardinality |
|---|---|---|
| any trigger | adds a trigger to the list of registered triggers | 1..n |
Built-in Triggers
Ivy comes with 3 built-in triggers:| Name | Description |
|---|---|
| ant-build | Triggers an ant build. Note that by default the ant build is triggered only once per build file, the property onlyonce can be set to false to change this. |
| ant-call | Calls a target in the current ant build. |
| log | Logs a message on the console or in a log file. |
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>Triggers an ant build of the ant file ${ivy.settings.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.
<ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish"
event="pre-resolve-dependency" filter="revision=latest.integration"/>
</triggers>
Note that by default the ant build is triggered only once per build file. See below to see how to trigger the build more than once.
<triggers>Same as before, but this time the builds will be triggered as many time as the dependency is resolved, instead of only once.
<ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish"
event="pre-resolve-dependency" filter="revision=latest.integration"
onlyonce="false" />
</triggers>
<triggers>Triggers an ant call of the target unzip just after downloading a zip artifact, prefixing all parameters to the target with 'dep'.
<ant-call target="unzip" prefix="dep"
event="post-download-artifact" filter="type=zip AND status=successful"/>
</triggers>
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>
<triggers>Logs any successful artifact download, with information on the source and destination, and details on download size and duration.
<log file="ivy.log"
message='downloaded "${origin}" to "${file}" (${duration}ms - ${size}B)'
event="post-download-artifact" filter="status=successful"/>
</triggers>
The file attribute is optional, the log trigger will output messages to console if it isn't provided.
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 dependency version constraint matches a dependency version.
Child elements
| Element | Description | Cardinality |
|---|---|---|
| any version matcher | adds a version matcher to the list of available ones | 0..n |
Built-in Version Matchers
Exact Revesion Matcher
A matcher that matches a dependency revision id to the module revision id using simple string equality.Sub Revision Matcher
A matcher that matches all revisions starting with a specific prefix. The syntax is: [prefix]+| Revision | Matches |
|---|---|
| 1.0.+ | all revisions starting with '1.0.', like 1.0.1, 1.0.5, 1.0.a |
| 1.1+ | all revisions starting with '1.1', like 1.1, 1.1.5, but also 1.10, 1.11 |
Latest (Status) Matcher
A matcher that matches versions based on their status. The predefined statuses in Ivy are 'release', 'milestone' and 'integration'. It's possible to define your own statuses, see statuses for more details.| Revision | Matches |
|---|---|
| latest.integration | all versions |
| latest.milestone | all modules having at least 'milestone' as status |
| latest.release | all modules having at least 'release' as status |
| latest.[any status] | all modules having at least the specified status |
Version Range Matcher
Range types are exhaustively listed by example in the table below.| Revision | Matches |
|---|---|
| [1.0,2.0] | all versions greater or equal to 1.0 and lower or equal to 2.0 |
| [1.0,2.0[ | all versions greater or equal to 1.0 and lower than 2.0 |
| ]1.0,2.0] | all versions greater than 1.0 and lower or equal to 2.0 |
| ]1.0,2.0[ | all versions greater than 1.0 and lower than 2.0 |
| [1.0,) | all versions greater or equal to 1.0 |
| ]1.0,) | all versions greater than 1.0 |
| (,2.0] | all versions lower or equal to 2.0 |
| (,2.0[ | all versions lower than 2.0 |
Version Pattern Matcher
The version pattern matcher allows for more flexibility in pattern matching at the cost of adding a matcher declaration in Ivy settings. A simple example is given below.Settings.xml
<pattern-vm>
<match revision="foo" pattern="${major}\.${minor}\.\d+" args="major, minor" matcher="regexp" />
</pattern-vm>
Ivy.xml
<dependency org="acme" name="tool" rev="foo(1, 3)" />The version pattern matcher may contain more than one match element. The matcher will attempt to match a dependency revision against each match in sequence, checking the revision tag (e.g. foo(..)) and then the pattern.
Matcher types may be one of "regexp", "exact", "glob", or "exactOrRegexp". Glob pattern matching requires Apache ORO 2.0.8 or higher to be on the classpath.
Ivy Files
Ivy use is entirely based on module descriptors known as "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="2.0">If you want to see a sample module descriptor using almost all possibilities of ivy files, check this one, with or without xslt.
<info organisation="myorg"
module="mymodule"
/>
</ivy-module>
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="2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation=
"http://ant.apache.org/ivy/schemas/ivy.xsd">
<info organisation="myorg"
module="mymodule"
/>
</ivy-module>
Dynamic and resolved ivy files
A module descriptor (ivy file) is needed both before and after the publication of each revision of the module. Depending on the case, a module descriptor can be either dynamic or resolved:Dynamic descriptor for module development
During the module development time, between publications, the descriptor helps in managing all the possibly changing dependencies of the module. For that purpose, development time ivy files can declare dynamic dependencies to allow for a greater flexibility of use. Dynamic revision references like "latest.integration" or "1.0.+" are possible and may resolve to different artifacts at different times. Variables can be used for even more flexibility. Development time ivy files are hence called "dynamic", because they can produce different results over time. The dynamic ivy files are normally considered source files and kept with them (under SCM control).Resolved descriptors for publishing
At each publication, another kind of a module descriptor is needed to document the dependencies of the particular published revision of the module. For that purpose, the descriptor usually needs to be fixed as its dependencies should no longer change. In doing so, the published module revision gets fixed, explicitly resolved dependencies. No variables are allowed either. Such publication-friendly, static ivy files are called "resolved", because they should always produce the same results. The resolved ivy files are comparable to published artifacts and are kept with them in a repository.Resolved ivy files are generated from their original dynamic ivy files via the deliver task.
Note that although it is technically possible to publish module revisions with dynamic ivy files, it is not a generally recommended practice.
Hierarchical Index
ivy-module
info
license
ivyauthor
repository
description
configurations
conf
publications
artifact
conf
dependencies
dependency
conf
mapped
artifact
conf
include
conf
exclude
conf
exclude
override
conflict
conflicts
manager
ivy-module
Tag: ivy-moduleThe root tag of any ivy file (module descriptor).
Attributes
| Attribute | Description | Required |
|---|---|---|
| version | the version of the ivy file specification - should be '2.0' 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 identification and basic information about the module this ivy file describes.
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 setting, 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 |
|---|---|---|
| extends | identifies a parent Ivy file from which this descriptor inherits content | 0..n |
| 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 |
extends
Tag: extends Parent: info
since 2.2 Identifies an optional parent descriptor for this module. For complicated projects composed of many modules that have common configurations or dependencies, inheritance allows modules to share this information. Which parts of the parent descriptor are inherited can be controlled with the extendType attribute. Supported extendType values are:
| Value | Description |
|---|---|
| info | Attributes of the info element are inherited from the parent. When an attribute appears in both child and parent, the child value is used. |
| description | The content of the info/description element is inherited from the parent. |
| configurations | Configurations defined in the parent descriptor are added to any configurations defined in the child descriptor. |
| dependencies | Dependencies defined in the parent descriptor are added to any dependencies defined in the child descriptor. |
| all | info, description, configurations, and dependencies from the parent descriptor are merged into the child descriptor. |
Attributes
| Attribute | Description | Required |
|---|---|---|
| organisation | the organisation of the parent module | Yes |
| module | the name of the parent module | Yes |
| revision | the revision of the parent module. Can be fixed, a dynamic value, or range of revisions; see dependency for information on specifying revisions. | Yes |
| extendType | which part(s) of the parent descriptor are inherited. Valid values are info, description, configurations, dependencies, and all. |
No, default is all |
| location | A local filesystem path that should be searched for the parent descriptor. If the parent descriptor cannot be found at this location, it will be located using dependency resolvers like any normal dependency. This attribute is intended for development use. For example, child module descriptors appear in a source control directory with the parent module descriptor at a higher level. location will then contain the relative path to the parent descriptor for use during development builds. |
No, as long as the parent descriptor exists in an Ivy resolver |
license
Tag: license Parent: info
Gives information about a license of the described module.
Attributes
| Attribute | Description | Required |
|---|---|---|
| name | the name of the license. Try to respect spelling when using a classical license. | Yes |
| url | an 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
| Attribute | Description | Required |
|---|---|---|
| name | the name of the author, as a person or a company. | Yes |
| url | an 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
| Attribute | Description | Required |
|---|---|---|
| name | the name of the repository. Try to respect spelling for common repositories (ibiblio, ivyrep, ...) | Yes |
| url | an url pointing to the repository. | Yes |
| pattern | an ivy pattern to find modules on this repository | No, but it's recommended to indicate it. |
| ivys | true if ivy file can be found on this repository | No, defaults to false. |
| artifacts | true 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
| Attribute | Description | Required |
|---|---|---|
| homepage | the url of the homepage of the module | No, but it's recommended to indicate it. |
configurations
Tag: configurations Parent: ivy-module
A container for configuration elements. If this container is not present, it is assumed that the module has one public configuration called 'default'.
since 2.2 You can define the default conf on this container by specifying the defaultconf attribute. This attribute defines the conf mapping to use when no conf mapping is specified for a dependency in this ivy file.
since 1.3 You can define a default conf mapping on this container by specifying the defaultconfmapping attribute.
This attribute modifies 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.
In order to maintain backwards compatibility with Ivy 2.1.0 and earlier, the defaultconfmapping also provides one additional function. If no defaultconf is specified (on either the configurations tag or the dependencies tag), the defaultconfmapping becomes the default configuration for dependencies in this ivy file when no configuration is specified. In other words, in addition to altering the interpretation of individual configurations with no mapping, defaultconfmapping also performs exactly like defaultconf in the absence of a definition for defaultconf.
If several defaultconfmapping or defaultconf attributes are defined (in the configurations tag, one or several in an included configurations file, and/or in the dependency tag, then it's only the last definition of each property which is taken into account. The others will have no effect at all.
See examples below to clarify the behavior of these two attributes together.
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.
Attributes
| Attribute | Description | Required |
|---|---|---|
| defaultconf | the default conf to use in this ivy file since 2.2 | No, defaults to no default conf |
| 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 |
Configuration mappings details
When Ivy parses your Ivy file, it will create (internally) modify the configuration mapping of your dependencies.For instance, say you have:
<configurations defaultconfmapping="conf1->other1;conf2->other2">When Ivy parses this file, it will construct the following dependency (in-memory only):
<conf name="conf1" />
<conf name="conf2" extends="conf1" />
</configurations>
<dependencies>
<dependency name="other-module" conf="conf1" />
</dependencies>
<dependency name="other-module" conf="conf1->other1" />So, if you now resolve the conf2 configuration, you will only get the other1 dependencies of your other-module.
But when you set confmappingoverride to true, Ivy will construct the following dependency in memory:
<dependency name="other-module" conf="conf1->other1;conf2->other2" />As you can see, the defaultmappings of the extending configurations are also added (although you didn't explicitly defined them)
When you now resolve the conf2 configuration, you'll get the other2 dependencies of your other-module.
Examples involving defaultconf and defaultconfmapping
The table below indicates how Ivy interprets the conf attribute according to how defaultconfmapping and defaultconf are set:| defaultconf | defaultconfmapping | conf | ivy interpretation |
|---|---|---|---|
*->* | |||
| runtime | runtime->runtime | ||
| test | test->test | ||
runtime | runtime->runtime | ||
runtime | runtime->*;test->default | runtime->* | |
runtime | runtime->*;test->default | test | test->default |
runtime->*;test->default | runtime->*;test->default | ||
runtime->*;test->default | runtime | runtime->* | |
runtime->*;test->default | test | test->default |
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 module 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" />Declares three configurations, core compile and runtime, with only the runtime one accessible from other modules, and with the compile one being non transitive.
<conf name="compile" extends="core" transitive="false" visibility="private" />
<conf name="runtime" extends="compile" description="everything needed to run this module" />
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">with included-configurations.xml like this:
<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>
<configurations defaultconfmapping="*->@">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.
<conf name="conf1" visibility="public"/>
<conf name="conf2" visibility="private"/>
</configurations>
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.
Attributes
| Attribute | Description | Required |
|---|---|---|
| defaultconf | comma separated list of public configurations in which artifacts are published by default (when no specific configurations are set on the artifact element). '*' wildcard can be used to designate all public configurations of this module. since 2.0 |
No, defaults to '*' |
Child elements
| Element | Description | Cardinality |
|---|---|---|
| artifact | declares 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
since 1.4 The artifact element has 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.
since 1.4 This tag supports extra attributes.
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 defaultconf attribute value on parent publications element. |
| 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
| Attribute | Description | Required |
|---|---|---|
| name | the 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 provides for two similar behaviors. An overview is given here. (See configurations doc page for more details about these behaviors).
since 1.1
defaultconfDefines the 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.
since 1.3
defaultconfmappingInfluences the way that a conf mapping with no mapped conf is interpreted.
In Ivy 2.1.0 and earlier, if both defaultconf and defaultconfmapping are defined, it's the defaultconfmapping that is used. Since Ivy 2.2.0, these attributes can be used together.
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 file. since 1.3 | No, defaults to no default conf mapping |
Child elements
| Element | Description | Cardinality |
|---|---|---|
| dependency | declares a dependency for this module | 0..n |
| exclude | excludes artifacts, modules or whole organizations from the set of dependencies of this module since 2.0 | 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] since 1.4 selects the latest revision of the dependency module with at least the specified status.
- end the revision with a + selects the latest sub-revision of the dependency module. For instance,
- version ranges since 1.4 mathematical notation for ranges can be used to match a range of version.
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.
if the dependency module exists in revision 1.0.3, 1.0.7 and 1.1.2, "1.0.+" will select 1.0.7.
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
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.
Revision constraint
since 2.0 The dependency tag supports two revision attributes: rev, corresponding to the default required dependency revision, and revConstraint, corresponding to a dynamic revision constraint applied on this dependency.Depending on the resolve mode used, the actual revision used during dependency resolution may vary. These revisions usually differ only for modules published in a repository. When deliver is used, dynamic version constraints are replaced by a stic version constraint, to help build reproducibility. However, the information of the original version constraint is not lost, but rather put in the revConstraint attribute. This both ensure better metadata in the repository while still allowing easier build reproducibility.
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).
- 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'.
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.
The examples on the dependency on the configurations page explain how ivy interprets the conf attribute according to how defaultconfmapping and defaultconf is set.
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).
If you don't understand really how this works, do not use it :-)
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;%->defaultmeans that the
testconfiguration is mapped to the
runtimeconfiguration, but all the other configurations are mapped to the
defaultconfiguration.
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
runtimeconf of the dependency is required, but if doesn't exist, it will use the
defaultconf instead. If
defaultconf doesn't exist then it will be considered as an error. Note that the
*wildcard can be used as fallback conf.
since 2.1 It is also possible to define dependencies on configurations intersection. A configuration intersection is defined using a '+' sign to separate the configuration (eg 'A+B' means the intersection of configuration 'A' and 'B'). In that case only artifacts and dependencies defined in both configurations in the dependency will be part of the master configuration defining the dependency on the configuration intersection.
Configuration intersections can also be used when specifying the confs to resolve.
Moreover, the mapping '*->@' is handled as a specific case with configuration intersections: it maps also the intersections. So if one resolve conf A+B in a module which defines a dependency with mapping *->@, the mapping *->@ is interpreted as A+B->A+B so the intersection of A and B will be resolved in the dependency.
since 2.1 you can refer to a group of configurations sharing the same value for an attribute as left side part of the dependency mapping.
The syntax is
*[att=value]where att is the name of the attribute shared by the configurations of the group, and value
For instance, if you have:
<configurations>Then you can do:
<conf name="red" e:axis="color" />
<conf name="blue" e:axis="color" />
<conf name="windows" e:axis="platform" />
<conf name="linux" e:axis="platform"/>
</configurations>
<dependency org="acme" name="foo" rev="2.0" conf="*[axis=platform]->default"/>To map the windows and linux configurations (the one which have the attribute axis equal to platform) to the default configuration of foo.
since 1.4 you can add simple conditions in the right side of 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]defaultmeans that the
testconfiguration will be mapped to the
runtimeconf for the dependencies of organisation 'A' and to the
defaultconf for dependencies of organisation 'B'.
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 indicationto 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 setting for the dependency. |
| rev | the revision of the dependency. See above for details. | Yes |
| revConstraint | the dynamic revision constraint originally used for this dependency. See above for details. | No, defaults to the value of rev |
| 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). See cache and change management for details. | 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
mymodulefrom 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-langfrom 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
defaultconf of commons-lang will be used in the
defaultconf of the master module. If
*->runtimewas 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
barfrom 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
barfrom 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
defaultconf 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
| Attribute | Description | Required |
|---|---|---|
| name | the name of the master configuration to map. '*' wildcard can be used to designate all configurations of this module |
Yes |
| mapped | a 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
| Element | Description | Cardinality |
|---|---|---|
| mapped | map dependency configurations for this master configuration | 0..n |
mapped
Tag: mapped Parent: conf
Describes a mapped dependency configuration for a master configuration.
Attributes
| Attribute | Description | Required |
|---|---|---|
| name | the 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">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 the url if it cannot be found at the standard location in the repository.
<artifact name="art1" type="jar" conf="A,B"/>
<artifact name="art2" type="jar" conf="A"/>
</dependency>
since 1.4 This tag supports extra attributes.
since 2.0 This feature can also be used for modules having their own module descriptor, but which doesn't declare an artifact you know that is published. Note that in this case artifacts declared to be published by the dependency will be ignored, so do not forget to include all artifacts you want.
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">Declares a dependency on module bar which only publish one artifact: baz.jar.
<artifact name="baz" type="jar"/>
</dependency>
<dependency org="foo" name="bar" rev="1.0">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.
<artifact name="baz" type="jar" url="http://www.acme.com/repository/bar/baz-1.0-acme.jar"/>
</dependency>
<dependency org="foo" name="bar" rev="1.0">Declares a dependency on module bar for which all artifacts declared will be used (thanks to the include tag) plus an artifact baz of type source and ext jar (which is not declared in module bar module descriptor).
<include name="*"/>
<artifact name="baz" type="source" ext="jar"/>
</dependency>
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 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">since 2.0 A module wide exclude can also be used to exclude dependencies for the whole module (and not only in the context of one dependency as it is the case here).
<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 an expression matching this name (see matcher attribute below) | 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 an expression matching this name (see matcher attribute below) | 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 excluded. '*' 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 excluded | 0..n |
conf
Tag: conf Parent: artifact
Specify a configuration in which the enclosing artifact exclusion should be included.
Attributes
| Attribute | Description | Required |
|---|---|---|
| name | the 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 an expression matching this name (see matcher attribute below) | No, defaults to .* |
| type | the type of the artifact of the dependency module to add to the include list, or an expression matching this name (see matcher attribute below) | No, defaults to .* |
| ext | the extension of the artifact of the dependency module to add to the include list, or an expression matching this name (see matcher attribute below) | No, defaults to type |
| matcher | the matcher to use to match the modules to include since 2.0 | 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: 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 |
exclude
Tag: exclude Parent: dependencies
since 2.0 This feature gives you more control on a dependency for which you do not control its ivy file.
It allows to exclude artifacts, modules or organizations from the list of dependencies for the whole module.
It is very similar to the dependency exclude element, except that it applies to a whole module, which can be very useful when a lot of dependencies transitively bring a module you don't want.
Attributes
| Attribute | Description | Required |
|---|---|---|
| org | the organization of the dependency module or artifact to exclude, or a regexp matching this organization | No, defaults to * |
| module | the name of the dependency module or the artifact to exclude, or a regexp matching this module name | No, defaults to * |
| artifact | the name of an artifact of the dependency module to add to the exclude list, or an expression matching this name (see matcher attribute below) | 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 an expression matching this name (see matcher attribute below) | No, defaults to type |
| matcher | the matcher to use to match the modules to excludes | 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 |
override
Tag: override Parent: dependencies
(since 2.0) Specify an override mediation rule, overriding the revision and/or branch requested for a transitive dependency.
This can be useful when a direct dependency is bringing a transitive dependency for which you want to change the revision, without actually declaring a dependency on it (because the module doesn't actually depend on it) and without using conflict management for this purpose (maybe because there is no conflict at all, or because you want to by pass conflict management for this particular transitive dependency).
Overriding is done before any else, in a phase called dependency descriptor mediation. The transitive dependency then behave exactly as if it were declared with the new value.
Note that even though no attribute is required, it makes no sense to set no attributes at all. It would mean that overriding is triggered for all transitive dependencies, but doesn't override anything. Most of the time, at least org or module should be set to override only a subset of transitive dependencies, and at least branch or rev should be set to actually override something.
Attributes
| Attribute | Description | Required |
|---|---|---|
| org | the name, or an expression matching the name of organisation to which overriding should be applied (see matcher attribute below) | No, defaults to * (match all) |
| module | the name, or an expression matching the name of module to which overriding should be applied (see matcher attribute below) | No, defaults to * (match all) |
| branch | the branch to set for all the overriden dependency descriptors | No, by default branch is not overriden |
| rev | the revision to set for all the overriden dependency descriptors | No, by default revision is not overriden |
| matcher | the matcher to use to match the modules for which the conflict manager should be used | No, defaults to exact |
conflict
Tag: conflict Parent: dependencies
(since 2.0) 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.
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 no specific conflict manager is defined, a default conflict manager is used for all modules.
The current default conflict manager is the "latest-revision" conflict manager.
Attributes
| Attribute | Description | Required |
|---|---|---|
| org | the name, or an expression matching the name of organisation to which this conflict manager should apply (see matcher attribute below) | No, defaults to * (match all) |
| module | the name, or an expression matching the name of module to which this conflict manager should apply (see matcher attribute below) | No, defaults to * (match all) |
| manager | the name of the conflict manager to use | Exactly one of two |
| rev | a comma separated list of revisions this conflict manager should select | |
| matcher | the matcher to use to match the modules for which the conflict manager should be used | No, defaults to exact |
conflicts
Tag: conflicts Parent: ivy-module
(since 2.0) the conflicts section is deprecated. Use the conflict instead.
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
| Element | Description | Cardinality |
|---|---|---|
| manager | declares a conflict manager for this module | 1..n |
manager
Tag: manager Parent: conflicts
(since 2.0) the conflicts section is deprecated. Use the conflict instead.
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
| Attribute | Description | Required |
|---|---|---|
| org | the name, or an expression matching the name of organisation to which this conflict manager should apply (see matcher attribute below) | No, defaults to * (match all) |
| module | the name, or an expression matching the name of module to which this conflict manager should apply (see matcher attribute below) | No, defaults to * (match all) |
| name | the name of the conflict manager to use | Exactly one of two |
| rev | a comma separated list of revisions this conflict manager should select | |
| matcher | the 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 |
Ant Tasks
The main and most frequent way to use ivy is from an ant build file. However, ivy can also be called as a standalone application
If you use ant version 1.6.0 or superior, you just have to add ivy namespace to your project (
xmlns:ivy="antlib:org.apache.ivy.ant"attribute of your project tag), and you can call ivy tasks.
If you want to make your build handle ivy.jar in either ant lib dir or a local lib dir, you can use a taskdef like this:
<path id="ivy.lib.path">Combined with the antlib definition in the project namespace, it will load Ivy classes either from your ant lib or a local directory (path/to/dir/with/ivy/jar in this example).
<fileset dir="path/to/dir/with/ivy/jar" includes="*.jar"/>
</path>
<taskdef resource="org/apache/ivy/ant/antlib.xml"
uri="antlib:org.apache.ivy.ant" classpathref="ivy.lib.path"/>
If you use ant 1.5.1 or superior, you have to define the tasks you use in your build file. For instance:
<taskdef name="ivy-configure" classname="org.apache.ivy.ant.IvyConfigure"/>Note: the tasks listed above are non exhaustive. For a complete list of tasks with the corresponding classes, see the antlib.xml file in svn or the version you use.
<taskdef name="ivy-resolve" classname="org.apache.ivy.ant.IvyResolve"/>
<taskdef name="ivy-retrieve" classname="org.apache.ivy.ant.IvyRetrieve"/>
<taskdef name="ivy-deliver" classname="org.apache.ivy.ant.IvyDeliver"/>
<taskdef name="ivy-publish" classname="org.apache.ivy.ant.IvyPublish"/>
Then you can use the tasks, but check their name, following samples assume you use the ivy namespace (ivy:xxx tasks), whereas with ant 1.5 you cannot use namespace, and should therefore use ivy-xxx tasks if you have followed the taskdefs above.
If you use an ant version lower than 1.5.1, you can not use the ivy tasks... you should then call ivy as any external program.
Calling ivy from ant: first steps
Once your build file is ok to call ivy tasks, the simplest way to use ivy is to call the ivy retrieve task with no parameters:<ivy:retrieve />This calls ivy with default values, which might be ok in several projects. In fact, it is equivalent to:
<target name="resolve">Those 3 tasks follow the 3 main steps of the ivy retrieving dependencies process:
<ivy:configure />
<ivy:resolve file="${ivy.dep.file}" conf="${ivy.configurations}" />
<ivy:retrieve pattern="${ivy.retrieve.pattern}" conf="${ivy.configurations}" />
</target>
- First the configure task tells it how it can find dependencies giving it a path to an xml settings file.
- Then the resolve task actually resolves dependencies described by an ivy file, and puts those dependencies in the ivy cache (a directory configured in the settings file).
- Finally the retrieve task copies dependencies from the cache to anywhere you want in your file system. You can then use those dependencies to make your classpath with standard ant paths.
ivy.project.dir = ${basedir}
ivy.lib.dir = ${ivy.project.dir}/lib
ivy.build.artifacts.dir = ${ivy.project.dir}/build/artifacts
ivy.distrib.dir = ${ivy.project.dir}/distrib
ivy.resolver.default.check.modified = false
ivy.default.always.check.exact.revision = true
ivy.configurations = *
ivy.resolve.default.type.filter = *
ivy.status = integration
ivy.dep.file = ivy.xml
ivy.settings.file = ivysettings.xml
ivy.retrieve.pattern = ${ivy.lib.dir}/[artifact]-[revision].[ext]
ivy.deliver.ivy.pattern = ${ivy.distrib.dir}/[type]s/[artifact]-[revision].[ext]
ivy.publish.src.artifacts.pattern = ${ivy.distrib.dir}/[type]s/[artifact]-[revision].[ext]
ivy.report.output.pattern = [organisation]-[module]-[conf].[ext]
ivy.buildlist.ivyfilepath = ivy.xml
ivy.checksums=sha1,md5
For the latest version of these properties, you can check the svn version.since 2.0 After calling the first Ivy task, the property ivy.version will be available and contains the version of the used Ivy library.
Ivy tasks attributes : generalities
Some tasks attributes values may be given through different places. The three possible places are :- task attribute
- ivy instance
- project property
The ivy instance considered here is an instance of the class Ivy, which is setup by a call to the configure task, and then reused for other tasks. Because most of the tasks need an ivy instance, they first check if one is available (i.e. configure has been called), and if none is available, then a default configure is called and the resulting ivy instance is used in the remaining tasks (unless another configure is called).
It isn't generally necessary to understand this, but it can lead to some issues if you forget to call configure before another task and if the configure step was required in your environment.
Usual cycle of main tasks
Example
Here is a more complete example of build file using ivy:<project xmlns:ivy="antlib:org.apache.ivy.ant" name="sample" default="resolve">All ivy tasks are documented in the following pages.
<target name="resolve">
<ivy:configure file="../ivysettings.xml" />
<ivy:resolve file="my-ivy.xml" conf="default, myconf" />
</target>
<target name="retrieve-default" depends="resolve">
<ivy:retrieve pattern="lib/default/[artifact]-[revision].[ext]" conf="default" />
</target>
<target name="retrieve-myconf" depends="resolve">
<ivy:retrieve pattern="lib/myconf/[artifact]-[revision].[ext]" conf="myconf" />
</target>
<target name="retrieve-all" depends="resolve">
<ivy:retrieve pattern="lib/[conf]/[artifact]-[revision].[ext]" conf="*" />
</target>
<target name="deliver" depends="retrieve-all">
<ivy:deliver deliverpattern="distrib/[artifact]-[revision].[ext]"
pubrevision="1.1b4" pubdate="20050115123254" status="milestone" />
</target>
<target name="publish" depends="deliver">
<ivy:publish resolver="internal"
artifactspattern="distrib/[artifact]-[revision].[ext]"
pubrevision="1.1b4" />
</target>
</project>
artifactproperty
since 1.1
Sets an ant property for each dependency artifacts previously resolved.since 2.0 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).
The property name and value are generated using the classical pattern concept, all artifact tokens and ivy variables being available.
since 2.0 This tag will follow the ant usual behavior for properties. If a property of the same name already exist, it's value will be unchanged. This behavior can be changed using the 'overwrite' attribute.
WARNING : Before 2.0, the behavior was to overwrite the properties. Since 2.0, the default is to not overwrite to properties
Attributes
| 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) |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
| overwrite | Overwrite the value of the property if it already exist (since 2.0). Before 2.0, the properties were always overwritten. | No, 'false' by default. |
Example
Suppose we have one dependency called mydep in revision 1.0 publishing two artifacts: foo.jar and bar.jar.Then:
<artifactproperty conf="build"will set two properties:
name="[module].[artifact]-[revision]"
value="${cache.dir}/[module]/[artifact]-[revision].[ext]"/>
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.
since 2.0 This is a post resolve task, with all the behaviour and attributes common to all post resolve tasks.
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">
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>
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 |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
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.
When the ivy.xml of the modules that you want to order doesn't contains a revision numbers, the rev attributes declared in the dependency is not used.
When the ivy.xml of the modules that you want to order contains a revision numbers, the revision numbers are used. If the revision number doesn't match a dependency description a warning is logged and the modules is considered as different modules.
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.
since 2.0 The root and leaf attributes can be a delimited list of modules to use as roots. These modules, and all their dependencies will be included in the build list.
since 2.0 By default, all the modules included in a circular dependency are grouped together so that any dependency of any module in the loop will apear before the modules in the loop. This garantee that if there is a depedendency path between a module A and a module B (but no dependency path from B to A), B will alway apear before A even if A is included in a loop in the provided set of modules to sort.
Note that circular dependency can also trigger a failure depending on the value configured in the circularDependencyStrategy of your settings
since 2.0 When you are specifying root or leaf modules you can limit the resulting list to only direct dependencies of the roots modules or to modules that directly depends on your leaf modules.
since 2.0 You can also specify a restartFrom modules. The difference with root or leaf, is that you get a list starting at the restartFrom module followed by all the modules that would be after if the parameter would not be there (even if there is no dependency between the restartFrom and the following module).
| 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 2.0 the names of the modules which should be considered as the root of the buildlist. since 1.3 Was limited to only one module name before 2.0. | 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 2.0 the names of the modules which should be considered as the leaf of the buildlist. since 1.4.1 Was limited to only one module name before 2.0. | No. Defaults to no leaf (all modules are used in the build list) |
| onlydirectdep | since 2.0 true if the resulting list should be restricted to direct dependencies of root modules or modules that directly depends on the leaf modules. This field is ignored when neither root neither leaf is filled. | No. Defaults to no false |
| delimiter | since 2.0 delimiter to use when specifying multiple module names in the root and leaf properties. | No. Defaults to the comma (,) character. |
| 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 | Deprecated, use onMissingDescriptor instead. 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 |
| onMissingDescriptor | since 2.0 Specify the action to take when no module descriptor file is found for a file of the fileset. Possible values are:
| No. Defaults to 'head' |
| 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 |
| restartFrom | since 2.0 The name of the module which should be considered as the starting point in the buildlist. This allows for the build to be started at any point in the dependency chain. | No. Defaults to '*' meaning no restart point (all modules are used in the build list). |
| settingsRef | since 2.0 A reference to the ivy settings that must be used by this task | No, 'ivy.instance' is taken by default. |
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
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 |
| 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 |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0). | No, 'ivy.instance' is taken by default. |
| resolver | the name of the resolver to use for build number calculation (since 2.1) | No, all available resolvers will be used by default. |
Examples
Here is how it can be used (suppose 1.3.1 is the latest version of ivy in the repository):<ivy:buildnumber organisation="apache" 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="apache" 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="apache" 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="apache" 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="apache" 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="apache" 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 * |
| settingsRef | (since 2.0) A reference to the ivy settings that must be used by this task | No, 'ivy.instance' is taken by default. |
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.
If you want to make your build more independent from Ivy, you could consider using the retrieve task. Once the artifacts are properly retrieved, you can use standard Ant path creation which makes Ivy not necessary any more.
Built path is registered in ant with a given id, and can thus be used like any other ant path using refid.
| 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 * |
| settingsRef | (since 2.0) A reference to the ivy settings that must be used by this task | No, 'ivy.instance' is taken by default. |
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"/>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.
<taskdef resource="emma_ant.properties" classpathref="emma.classpath" />
cleancache
since 2.0 Cleans the Ivy cache.
This task is roughly equivalent to:
<delete dir="${ivy.cache.dir}" />
Using the regular Ant delete task is more flexible, since it allows to specify the files to delete. But it requires an Ivy settings to be loaded, and settings scoping is possible only by using suffixed ant property for the cache directory. This task loads the Ivy settings as any other post settings task, and allows easy scoping with the attribute settingsRef.
Attributes
| Attribute | Description | Required |
|---|---|---|
| settingsRef | A reference to the ivy settings that must be used by this task | No, 'ivy.instance' is taken by default. |
Examples
<ivy:cleancache />Cleans the cache directory as defined in the loaded settings (by default ~/.ivy2/cache)
<ivy:cleancache settingsRef="mysettings"/>Cleans the cache directory as defined in the loaded settings identified as 'mysettings'
configure
The configure task is used to configure ivy with an xml settings file.
See Settings Files for details about the settings file itself.
since 2.0 The file loaded used to be called configuration file in versions prior to 2.0. The name 'settings' and the use of the ivy.settings.file is new to 2.0.
since 2.0 It is also possible to configure Ivy with the settings declaration. The difference with this task is that when using the settings declaration, the configuration of Ivy will be done when the settings are first needed (for instance when you do a resolve), while the configure task will perform a configuration of Ivy instantly, which makes it easier to see the problem if something goes wrong.
| Attribute | Description | Required |
|---|---|---|
| settingsId | The settings id useable in the settingsRef attributes of the ivy task that needs a setting. Note that the ivy tasks will search by default for the settings with the id "ivy.instance", which is the default value. | No, defaults to "ivy.instance" |
| file | path to the settings 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.settings.file}, and if this file does not exist, it uses a default settings file |
| url | url of the settings file to use | |
| override | Specify what to do when another settings with the same id has already been loaded.
| No, defaults to "notallowed" |
| host | http authentication host | No, unless authentication is required |
| realm | http authentication realm | |
| username | http authentication user name | |
| passwd | http authentication password |
HTTP Authentication
Note: HTTP Authentication can be used only if commons-httpclient.jar is in your classpathIf 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
Examples
Simplest settings
<ivy:configure />Use either ${ivy.settings.file} if it exists, or the default settings 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/ivysettings.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
Deliver a resolved descriptor of the current module, and possibly perform a recursive delivery of dependencies.
This task does two main things:
Generate a resolved ivy file
This task generates a resolved descriptor 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. This is an exception to the recommended standard that published module descriptors be fully resolved, so use it with caution.
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)
dependency.published.statusand
dependency.published.versioncan 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
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 |
| pubbranch | the branch to use for the publication | No. Defaults to ${ivy.deliver.branch} if set, or the branch resolved if set, or nothing (branch info won't be updated) |
| 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 dynamic revisions by static ones in the delivered file, false to avoid this replacement (since 1.3) | No. Defaults to true |
| replaceForcedRev | true to replace revisions (static or dynamic) by the revision of the resolver in forced mode, false to avoid this replacement (since 2.2) | No. Defaults to false |
| merge | if a descriptor extends a parent, merge the inherited information directly into the delivered descriptor. The extends element itself will be commented out in the delivered descriptor. (since 2.2) | No. Defaults to true. |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
| conf | comma-separated list of configurations to include in the delivered file. Accepts wildcards. (since 2.0) | No. Defaults to all configurations |
| generateRevConstraint | true to automatically generate a 'revConstraint' attribute in the deliverd file (see the dependency page for more info about this attribute), false to never generate this attribute (since 2.1.0) | No. Defaults to true |
Example
Deliver an ivy file without the private configurations:<deliver conf="*(public)" />
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 |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
Examples
<ivy:findrevision organisation="apache" 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="apache" 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:
| Property | Description |
|---|---|
| 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.branch | The branch of the module if any, 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.status | The status of the module, as found in the info tag of the ivy file parsed. |
| ivy.publication | The publication time of the module, as found in the info tag of the ivy file parsed. (Since 2.2) |
| ivy.extra.[any extra attribute] | Corresponding extra attribute value, 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 |
| ivy.configuration.[config name].desc | For each configuration with a description, a property is created containing this description. (Since 2.2) |
| ivy.artifact.[index].name | For each published artifact, a property is created containing its name. (Since 2.2) |
| ivy.artifact.[index].type | For each published artifact, a property is created containing its type. (Since 2.2) |
| ivy.artifact.[index].ext | For each published artifact, a property is created containing its ext. (Since 2.2) |
| ivy.artifact.[index].conf | For each published artifact, a property is created containing its conf. (Since 2.2) |
| ivy.artifact.[index].extra.[any extra attribute] | For each extra attribute of the published artifact, a property is created containing its name. (Since 2.2) |
since 2.0 Since Ivy 2.0 this task has been enhanced to allow you to retrieve information about ivy modules in a repository. Instead of specifying a local ivy file you may specify the organisation, module, revision pattern and (optionally) the branch of the ivy module in the repository you wish to retrieve the information for.
The revision pattern is what is used when declaring a dependency on a module, identical to how the findrevision task works. In fact this task can now be used in place of the findrevision task.
If no matching module is found then no property values are set.
You may now also set the property attribute to change the first part of the property names that are set by this task e.g. if you set the property attribute to 'mymodule' this task will set the ant properties mymodule.organisation, mymodule.module, mymodule.revision etc.
since 2.2 Since Ivy 2.2 this task has been enhanced to also retrieve detailed information about the module's published artifacts, as well as the publication time.
Attributes
| Attribute | Description | Required |
|---|---|---|
| file | the ivy file to parse | Yes, if you wish to parse an ivy file. No, if you are retrieving information about a module from an ivy repository. |
| organisation | the organisation of the module to find (since 2.0) | No, if you wish to parse an ivy file. Yes, if you are retrieving information about a module from an ivy repository. |
| module | the the name of the module to find (since 2.0) | No, if you wish to parse an ivy file. Yes, if you are retrieving information about a module from an ivy repository. |
| branch | the branch of the module to find (since 2.0) | No, defaults to the default branch for the given module if you are retrieving information about a module from an ivy repository. |
| revision | the revision constraint to apply (since 2.0) | No, if you wish to parse an ivy file. Yes, if you are retrieving information about a module from an ivy repository. |
| property | the name to use as the base of the property names set by this task (since 2.0) | No, will default to 'ivy' if not set. |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
Examples
Given this ivy.xml file:<ivy-module version="1.0" xmlns:e="http://ant.apache.org/ivy/extra">
<info organisation="apache"
module="info-all"
branch="trunk"
revision="1.0"
status="release"
e:myextraatt="myvalue"
/>
<configurations>
<conf name="default" />
<conf name="test" />
<conf name="private" visibility="private"/>
</configurations>
<publications>
<artifact name="thing1" type="jar" ext="jar" conf="default" e:data="main"/>
<artifact name="thing2" type="jar" ext="jar" conf="default" e:data="client"/>
</publications>
<dependencies>
<dependency org="org1" name="mod1.2" rev="2.0"/>
</dependencies>
</ivy-module>
<ivy:info file="${basedir}/path/to/ivy.xml" />
Parses ${basedir}/path/to/ivy.xml and set properties as described above accordingly:
ivy.organisation=apacheGiven the same ivy module in a repository:
ivy.module=info-all
ivy.branch=trunk
ivy.revision=1.0
ivy.status=release
ivy.extra.myextraatt=myvalue
ivy.configurations=default, test, private
ivy.public.configurations=default, test
ivy.artifact.1.name=thing1
ivy.artifact.1.type=jar
ivy.artifact.1.ext=jar
ivy.artifact.1.conf=default
ivy.artifact.1.extra.data=main
ivy.artifact.2.name=thing2
ivy.artifact.2.type=jar
ivy.artifact.2.ext=jar
ivy.artifact.2.conf=default
ivy.artifact.2.extra.data=client
<ivy:info organisation="apache" module="info-all" revision="1.0" />will set the exact same set of properties as above. Using:
<ivy:info organisation="apache" module="info-all" revision="1.0" property="infotest"/>will set:
infotest.organisation=apache
infotest.module=info-all
infotest.branch=trunk
infotest.revision=1.0
infotest.status=release
infotest.extra.myextraatt=myvalue
infotest.configurations=default, test, private
infotest.public.configurations=default, test
infotest.artifact.1.name=thing1
infotest.artifact.1.type=jar
infotest.artifact.1.ext=jar
infotest.artifact.1.conf=default
infotest.artifact.1.extra.data=main
infotest.artifact.2.name=thing2
infotest.artifact.2.type=jar
infotest.artifact.2.ext=jar
infotest.artifact.2.conf=default
infotest.artifact.2.extra.data=client
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 |
| branch | the branch of the module to install since 2.0 | No, defaults to default branch with exact matcher, '*' with any other matcher |
| revision | the revision of the module to install | Yes |
| type | the type(s) of artefact(s) to install. You can give multiple values separated by commas | No, defaults to '*' meaning all types |
| 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 |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
| haltonfailure | true to fail build on unresolved dependencies since 2.0 | No, defaults to true |
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 |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
| resolver | The name of the resolver to use for searching the modules (since 2.2.0) | No, all available resolvers will be used by default. |
Examples
<ivy:listmodules organisation="apache" module="ivy" revision="*" property="ivy.[revision]" value="found"/>will find all revisions of the module ivy in the org apache, 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=apache
modules.ivyde=apache
modules.ivytools=ivytools
makepom
since 2.0 The makepom task allows to convert an ivy file to a pom file.
An example of use is to publish an Ivy managed module to a maven 2 repository.
Note that all Ivy features are not supported by maven poms, so the converted pom may not resolve to the exact same dependencies as the original ivy file.
since 2.2 It is possible to specify a template file defining the structure of the generated POM. The following processing is done on this template:
- properties like ${property.name} are replaced if they are defined in Ant or by the ivy:makepom task (see below for the standard properties)
- lines containg the string SKIP_LINE are skipped.
- the defined dependencies will be added to the first
element encountered in the pom template. If the template doesn't contain a element, it is generated a the end of the pom.
- ivy.pom.groupId: defaults to the organisation as defined in the ivy.xml file
- ivy.pom.artifactId: defaults to the value of the 'atifactName' attribute of this task, or the name of the module as defined in the ivy.xml file
- ivy.pom.packaging: defaults to the value of the 'artifactPackaging' attribute of this task, or the extenstion of the artifact
- ivy.pom.version: defaults to the revision as defined in the ivy.xml file
- ivy.pom.name: defaults to 'SKIP_LINE'
- ivy.pom.description: defaults to the value of the 'description' attribute of this task, or 'SKIP_LINE' when not specified
- ivy.pom.url: defaults to the homepage as defined in the ivy.xml file
- ivy.pom.license: the content of the specified headerFile, or 'SKIP_LINE' if not specified
- ivy.pom.header: some Ivy information, or 'SKIP_LINE' if the 'printIvyInfo' attribute is set to false.
The default template that ships with Ivy looks like this:
${ivy.pom.license}
${ivy.pom.header}
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>${ivy.pom.groupId}</groupId>
<artifactId>${ivy.pom.artifactId}</artifactId>
<packaging>${ivy.pom.packaging}</packaging>
<version>${ivy.pom.version}</version>
<name>${ivy.pom.name}</name>
<description>${ivy.pom.description}</description>
<url>${ivy.pom.url}</url>
</project>
Attributes
| Attribute | Description | Required |
|---|---|---|
| ivyfile | the source ivy file to convert | Yes |
| pomfile | the destination pom file to write | Yes |
| templatefile | the template file to use when generating the pom (since 2.2) | No, defaults to the internal template file. |
| artifactName | The name of the artifact which is represented by the generated pom file. (since 2.2) | No, defaults to the module name in the source ivy file. |
| artifactPackaging | The packaging of the artifact which is represented by the generated pom file. (since 2.2) | No, the artifact ext is taken by default. Defaults to 'pom' if no such artifact is defined. |
| conf | a comma separated list of the configurations to include in the generated pom. Wildcards are supported here. (since 2.2) | No, defaults to all configurations. |
| settingsRef | A reference to the ivy settings that must be used by this task | No, 'ivy.instance' is taken by default. |
| printIvyInfo | Add some information about Ivy to the generated POM. (since 2.2) | No, defaults to 'true'. |
| headerFile | the header of the generated pom file | No |
| description | The description that will be added to the generated pom. (since 2.2) | No, defaults to no description. |
Child elements
| Element | Description | Cardinality |
|---|---|---|
| mapping | describes the mapping from an Ivy module configuration to a Maven POM scope. These elements takes two attributes:
|
0..n |
| dependency | describes extra dependencies that should be added to the generated Maven POM file. These elements takes the following attributes:
|
0..n |
Examples
<ivy:makepom ivyfile="${basedir}/path/to/ivy.xml" pomfile="${basedir}/path/to/module.pom" conf="default,runtime">
<mapping conf="default" scope="compile"/>
<mapping conf="runtime" scope="runtime"/>
<dependency group="com.acme" artifact="acme-logging" version="1.0" optional="true"/>
</ivy:makepom>
Converts ${basedir}/path/to/ivy.xml to a pom and writes the result to ${basedir}/path/to/module.pom. The configuration 'default' in the parsed ivy file will be mapped to the scope 'compile', the configuration 'runtime' will be mapped to 'runtime', and other configurations will be excluded.The com.acme.acme-logging artifact with version 1.0 will be added as an optional dependency.
post resolve tasks
Several tasks in Ivy are considered as post resolve task and share a common behaviour and settings accordingly.
These tasks are:
- retrieve
- cachefileset
- cachepath
- artifactproperty (since 2.0)
- artifactreport (since 2.0)
- none has already been called in the current build with the attribute keep set to true (see below)
- organisation and module are not set
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. You 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 or '*'. Since 2.0 you can also use '*(public)' or '*(private)'. Note that '*' is interpreted as '*(public)' when inline is true. |
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 |
| branch | the name of the branch to resolve in inline mode (since 2.1) | Defaults to no branch in inline mode, nothing in standard mode. |
| changing | indicates that the module may change when resolving in inline mode. See cache and change management for details. Ignored when resolving in standard mode. (since 2.2.0) | No. Defaults to false. |
| transitive | true to resolve dependencies transitively, false otherwise since 1.4 | No. Defaults to true |
| resolveMode | the resolve mode to use when an automatic resolve is triggered (since 2.1) | No. defaults to using the resolve mode set in the settings |
| keep | true to keep the results of the automatic resolve in memory, false to discard them. When this is false, the standard ivy properties won't be set and other postresolve-tasks (like retrieve and cachepath) won't be able to resuse the results of this resolve! | No. defaults to false for an inline resolve and to true in any other case |
| 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) |
| refresh | true to force Ivy to resolve dynamic revision in this resolve process, false to use cached resolved revision since 2.1 | No. defaults to false |
| file | the file to resolve if a resolve is necessary since 2.0 | No. Defaults to the previous resolved Ivy file or to ${ivy.dep.file} |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
| resolveId | The id which was used for a previous resolve, or the resolveId if a new resolve is performed (since 2.0) | No, defaults to '[org]-[module]'. |
| log | the log setting to use during the resolve process. (since 2.0) Available options are:
| No, defaults to 'default'. |
Examples
<ivy:cachepath organisation="emma" module="emma" revision="2.0.4217" inline="true" conf="ant" pathid="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.
<taskdef resource="emma_ant.properties" classpathref="emma.classpath" />
publish
Publishes the current module's artifacts and the resolved descriptor (delivered ivy file).
This task is meant to publish the current module descriptor together with its declared publication artifacts to a repository.
All the artifacts must have been created before calling this task. It does not create the artifacts themselves, but expects to find them at the location indicated by the artifacts pattern.
The target repository is given through the name of a resolver declared in current ivy settings. See Settings Files 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. See the illustration below:
| Attribute | Description | Required |
|---|---|---|
| organisation | the name of the organisation of the module to publish | No. Defaults to ${ivy.organisation} or the last resolved module organisation. |
| module | the name of the module to publish | No. Defaults to ${ivy.module} or the last resolved module name. |
| revision | the revision of the module to publish and also the published revision unless pubrevision is set | No. Defaults to ${ivy.revision} or the last resolve module revision. |
| 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} |
| pubbranch | the branch to use for the publication | No. Defaults to the ${ivy.deliver.branch} |
| 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 |
| update | true to update ivy file metadata (revision, branch, publication date and status) before publishing, false otherwise. This is usually not necessary when using deliver before publish. | No. Defaults to false |
| merge | if this descriptor extends a parent, merge the inherited information directly into this descriptor on publish. The extends element itself will be commented out in the published descriptor. (since 2.2) | 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 settings file) |
| replacedynamicrev | true to replace dynamic 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 (since 1.4.1). Accepts wildcards (since 2.2). | No. Defaults to all configurations |
| 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 |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
Child elements
| Element | Description | Cardinality |
|---|---|---|
| artifact | Describe additional artifacts to publish These elements can have any attribute: standard artifact attributes and (since 2.2) extra attributes are supported. |
0..n |
| artifacts | Specify the pattern used to find the artifact. These elements have a pattern attribute containing the pattern used to find the artifact. |
0..n |
Examples
<ivy:publish resolver="local" pubrevision="1.0">Publishes the last resolved module in the local resolver with revision 1.0, looking for artifacts in directories build/artifacts/jars and build/artifacts/zips.
<artifacts pattern="build/artifacts/jars/[artifact].[ext]" />
<artifacts pattern="build/artifacts/zips/[artifact].[ext]" />
</ivy:publish>
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.
Limitation: this task requires to be able to browse the repository, and is thus limited to resolvers supporting repository listing. In particular, it means it doesn't work to report all organizations in a repository using m2compatible mode.
Moreover, to be able to list organizations, this task requires an [organisation] token in the resolver(s) used.
| 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) |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
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 the resolved dependencies are changes since the last resolve, and to false otherwise:
ivy.deps.changedSince 2.0:
The property ivy.deps.changed will not be set (and not be computed) if you set the parameter checkIfChanged to false. (by default it is true to keep backward compatibility). This allow to optimize your build when you have multi-module build with multiple configurations.
Since 2.0:
In addition, if the resolveId attribute has been set, the following properties are set as well:
- ivy.organisation.${resolveId}
- ivy.module.${resolveId}
- ivy.revision.${resolveId}
- ivy.resolved.configurations.${resolveId}
- ivy.deps.changed.${resolveId}
---------------------------------------------------------------------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 || artifacts |
| conf | number| search|dwnlded|evicted|| number|dwnlded|
---------------------------------------------------------------------
| default | 4 | 0 | 0 | 0 || 4 | 0 |
---------------------------------------------------------------------
- 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)
- dwnlded 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.
Inline mode
since 1.4 The 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 an 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.Remark: if you want the standard ivy properties to be set or to reuse the results of an inline resolve by other post-resolve tasks like retrieve, cachepath, report, ..., you must set the keep attribute to true!
Resolve mode
since 2.0 The resolve mode allows to define how Ivy should use dependency revision constraints when performing the resolution.Two modes are available:
- default In this mode the default revision constraint (expressed with the rev attribute in the dependency element) is used.
- dynamic In this mode the dynamic revision constraint (expressed with the revConstraint attribute in the dependency element) is used.
Concurrency
During resolve, Ivy creates a file in the resolution cache. The creation of this file is not aimed to support concurrency, meaning that you can't have two concurrent resolve of the same module, in the same resolution cache, with the same resolveId.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".
Attributes
| 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, or '*'. Since 2.0, you can also use '*(private)', '*(public)'. Note that when inline is true, the configuration '*' is equivalent as '*(public)'. | No. Defaults to ${ivy.configurations} |
| refresh | true to force Ivy to resolve dynamic revision in this resolve process, false to use cached resolved revision since 2.0 | No. defaults to false |
| resolveMode | the resolve mode to use for this dependency resolution process since 2.0 | No. defaults to using the resolve mode set in the settings |
| inline | true to use inline mode, false to resolve an ivy file since 1.4 | No. defaults to false |
| keep | true to keep the results of the resolve in memory, false to discard them. When this is false, the standard ivy properties won't be set and other postresolve-tasks (like retrieve and cachepath) won't be able to resuse the results of this resolve! | No. defaults to false for an inline resolve and to true in any other case |
| 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. |
| branch | the name of the branch to resolve in inline mode (since 2.1.0) | Defaults to no branch in inline mode, nothing in standard mode. |
| changing | indicates that the module may change when resolving in inline mode. See cache and change management for details. Ignored when resolving in standard mode. (since 1.4) | No. Defaults to false. |
| 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) |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
| resolveId | An id which can be used later to refer to the results of this resolve (since 2.0) | No, defaults to '[org]-[module]'. |
| log | the log setting to use during the resolve process. (since 2.0) Available options are:
| No, defaults to 'default'. |
| checkIfChanged | When set to true, the resolve will compare the result with the last resolution done on this module, with those configurations in order to define the property ivy.deps.changed. Put it to false may provides slightly better performance. (since 2.0) | No, default to 'true' |
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
| 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. |
| overwriteMode | option to configure when the destination file should be overwritten if it exist (since 2.2.0). Possible values are:
| No. Defaults to 'newer'. |
| symlink | true to create symbolic links, false to copy the artifacts. The destination of the symbolic links depends on the value of the useOrigin attribute (since 2.0) | No. Defaults to false |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
| log | the log setting to use during the resolve and retrieve process. (since 2.0) Available options are the same as for resolve when used to trigger resolve automatically (see postresolvetask), or the following for the retrieve process only:
| No, defaults to 'default'. |
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:
libNote 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.
default
commons-lang.jar
commons-logging.jar
test
junit.jar
<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:
libAnd now suppose commons-logging is no longer part of the dependencies of the default configuration, then a new call to retrieve will result in:
default
commons-lang.jar
commons-logging.jar
test
junit.jar
libWith no synchronisation, commons-logging would not have been removed by the call.
default
commons-lang.jar
test
junit.jar
<ivy:retrieve pattern="${lib.dir}/[type]/[artifact]-[revision].[ext]" conf="runtime"/>
Retrieves only the dependencies of the runtimeconfiguration 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 graphviz 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 resolveId has not been specified and 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 resolveId has not been specified and 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 |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
| resolveId | The id which was used for a previous resolve (since 2.0) | No, defaults to '[org]-[module]'. |
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).
settings
(since 2.0) The settings declaration is used to configure ivy with an xml settings file. The difference with the configure task is that when using the settings declaration, the configuration of Ivy will be done when the settings are first needed (for instance when you do a resolve), while the configure task will perform a configuration of Ivy instantly, which makes it easier to see the problem if something goes wrong.
See Settings Files for details about the settings file itself.
Multiple settings can be defined in a build script. Every task can reference its own settings.
All Ivy variables set during the settings are available in the Ant project as long as they were not set in Ant before (Ant properties are immutable).
Moreover, the variables are exposed under two names: the variable name, and the variable name suffixed by dot + the settings id.
For instance, if you load a settings with the id 'myid', and define a variable my.variable=my.value in the Ivy settings, both my.variable and my.variable.myid will now be available as properties in Ant and equal to 'my.value'. If you later load another settings with the id 'yourid', and in this settings assign the variable 'my.variable' the value 'your.value', in the Ant project you will have:
my.variable=my.value
my.variable.myid=my.value
my.variable.yourid=your.value
Attributes
| Attribute | Description | Required |
|---|---|---|
| id | The settings id useable in the settingsRef attributes of the ivy task that needs a setting. Note that the ivy tasks will search by default for the settings with the id "ivy.instance", which is the default value. | No, defaults to "ivy.instance" |
| file | path to the settings 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.settings.file}, and if this file does not exist, it uses a default settings file |
| url | url of the settings file to use | |
| host | http authentication host | No, unless authentication is required |
| realm | http authentication realm | |
| username | http authentication user name | |
| passwd | http authentication password |
HTTP Authentication
Note: HTTP Authentication can be used only if commons-httpclient.jar is in your classpathIf 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.
Multiple classloader
A special attention should be applied when you have a multi-project build with subant call, using ivy task loaded by a typedef. Indeed in this situation, it is possible to pass settings reference to a subbuild. When you do that, you should take of the classloader. The ivy task of your subant should not be defined in a different classloader than the parent one. This can be achieved by using the loader parameter of the antlib declaration, or avoid to reload the ivy antlib in the subbuild (place the taskdef in a target only executed when the antlib is not yet loaded).Examples
Simplest settings
<ivy:settings />Use either ${ivy.settings.file} if it exists, or the default settings file
This simplest setting is implicit.
Configure with a file
<ivy:settings file="mysettings.xml" />
Configure with an url
<ivy:settings url="http://mysite.com/mysettings.xml" />
Configure multiple realms which require autentication
<ivy:settings file="path/to/my/ivysettings.xml">
<credentials host="myhost.com" realm="My Realm" username="myuser" passwd="mypasswd" />
<credentials host="yourhost.com" realm="Your Realm" username="myuser" passwd="myotherpasswd" />
</ivy:settings>
Configure 2 different settings
You can use multiple ivy settings during a build. Then every ivy task should specify the settings it uses using the settingsRef attribute.<ivy:settings id="ivy.normal.settings" file="normal_settings.xml" />
<ivy:settings id="ivy.release.settings" file="release_settings.xml" />
<ivy:resolve settingsRef="ivy.normal.settings" />
<ivy:resolve settingsRef="ivy.release.settings" />
var
Sets a variable (by name and value), or set of variables (from file or url) in ivy.
Variables are case sensitive.
Contrary to ant properties, ivy variables are mutable. But a problem with this is that you do not control when
variables are substituted, and usually it is done as soon as possible. So changing the value of a variable will
have no effect if it has already been substituted. Consequently, using this task is NOT recommended.
See reference page for details about ivy variables.
| Attribute | Description | Required |
|---|---|---|
| name | the name of the variable to set | No |
| value | the value of the variable to set | Yes when using the name attribute |
| file | the filename of the property file to load as ivy variables | One of these, when not using the name attribute |
| url | the url from which to read ivy variables | |
| prefix | Prefix to apply to variables. A "." is appended to the prefix if not specified. | No |
| settingsRef | A reference to the ivy settings that must be used by this task (since 2.0) | No, 'ivy.instance' is taken by default. |
Using standalone
Ivy can be used as a standalone program very easily. All you need is a java 1.4+ runtime environment (JRE)!
Then here is how to call it:
java -jar ivy.jar -?It will display an online help like this:
==== settings optionssince 1.3 System properties are included as ivy variables, so you can easily define an ivy variable like this:
-settings <settingsfile> use given file for settings
-cache <cachedir> use given directory for cache
-novalidate do not validate ivy files against xsd
-m2compatible use maven2 compatibility
==== resolve options
-ivy <ivyfile> use given file as ivy file
-dependency <organisation> <module> <revision>
use this instead of ivy file to do the rest of the
work with this as a dependency.
-confs <configurations> resolve given configurations
==== retrieve options
-retrieve <retrievepattern> use given pattern as retrieve pattern
-sync use sync mode for retrieve
==== cache path options
-cachepath <cachepathfile> outputs a classpath consisting of all dependencies
in cache (including transitive ones) of the given
ivy file to the given cachepathfile
==== deliver options
-deliverto <ivypattern> use given pattern as resolved ivy file pattern
==== publish options
-publish <resolvername> use given resolver to publish to
-publishpattern <artpattern> use given pattern to find artifacts to publish
-revision <revision> use given revision to publish the module
-status <status> use given status to publish the module
==== http auth options
-realm <realm> use given realm for HTTP AUTH
-host <host> use given host for HTTP AUTH
-username <username> use given username for HTTP AUTH
-passwd <passwd> use given password for HTTP AUTH
==== launcher options
-main <main> the FQCN of the main class to launch
-args <args> the arguments to give to the launched process
-cp <cp> extra classpath to use when launching process
==== message options
-debug set message level to debug
-verbose set message level to verbose
-warn set message level to warn
-error set message level to error
==== help options
-? display this help
-deprecated show deprecated options
java -Dmyivyvar=myvalue org.apache.ivy.Main [parameters]
Examples
java -jar ivy.jarcalls ivy with default configuration using ivy.xml in the current dir
java -jar ivy.jar -settings path/to/myivysettings.xml -ivy path/to/myivy.xmlcalls ivy with given ivysettings file using given ivy file
since 1.3
java -jar ivy.jar -settings path/to/myivysettings.xml -dependency apache commons-lang 2.0calls ivy with given ivysettings file and resolve apache commons-lang 2.0.
This is equivalent to:
java -jar ivy.jar -settings path/to/myivysettings.xml -ivy ivy.xmlwith 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 -jar ivy.jar -settings path/to/myivysettings.xml -ivy path/to/myivy.xml -cachepath mycachefile.txtcalls ivy with given ivysettings 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 -jar ivy.jar -settings path/to/myivysettings.xml -dependency bar foo 2.0 -main org.bar.foo.FooMaincalls ivy with given ivysettings file and resolve bar foo 2.0, and then run org.foo.FooMain class with the resolved artifacts as classpath
Developer doc
Building from source
To build Ivy from source it's really easy.Requirements
All you need is- an svn client to check out Ivy sources from apache svn, not required if you build from sources packaged in a release
- Apache Ant 1.6.0 or greater We recommend either ant 1.6.5 or 1.7.0
- junit 3.8.2 jar in your ant lib this is not required if you use ant 1.7
- a jdk 1.4 or greater Build instructions have been successfully tested with sun jdk 1.4.2, 1.5.0 and 1.6.0
Procedure
Get the source
You can either get the sources from a release, or get them directly from svn. For instance, to get the trunk version:svn co https://svn.apache.org/repos/asf/ant/ivy/core/trunk ivy
Build
Go to the directory where you get the Ivy sources (you should see a file named build.xml) and run:ant
Check the result
The ant build will compile the core classes of Ivy and use them to resolve the dependencies (used for some optional features). Then it will compile and run tests with coverage metrics.If everything goes well, you should see the message
BUILD SUCCESSFULThen you can check the test results in the build/doc/reports/test directory, the jars are in build/artifacts, and the test coverage report in build/doc/reports/coverage
Coding conventions
The Ivy code base is supposed to follow the standard java conventions:http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
This is a work in progress though (see IVY-511), but patches helping migration to these conventions are welcome.
Developing with eclipse
Even though you can develop Ivy with your IDE of choice, we support eclipse development by providing ad hoc metadata.We currently provide two options:
Eclipse alone
To develop with a simple eclipse install all you need is eclipse 3.1 or greater, with no particular plugin.First call the following ant target in your Ivy workspace:
ant eclipse-defaultThis will resolve the dependencies of Ivy and produce a .classpath using the resolved jars for the build path.
Then you can use the "Import->Existing project into workspace" eclipse feature to import the Ivy project in your workspace.
Eclipse + IvyDE
You can also leverage the latest IvyDE version to be able to easily resolve the ivy dependencies from Eclipse.To do so all you need is call the following ant target in your Ivy workspace:
ant eclipse-ivydeor if you don't have ant installed you can simply copy the file .classpath.ivyde and rename it to .classpath
Then you can import the project using "Import->Existing project into workspace" as long as you already have latest IvyDE installed.
To install latest IvyDE version compatible with the latest Ivy used to resolve Ivy dependencies, you will need to use a snapshot build, not endorsed by the ASF, available here:
http://people.apache.org/~xavier/ivyde/snapshot/
Download the file and unzip its content in your eclipse installation directory.
recommended plugins
The Ivy project comes with settings for the checkstyle plugin we recommend to use to avoid introducing new disgression to the checkstyle rules we use.If you use this plugin, you will many errors in Ivy. As we said, following strict checkstyle rules is a work in progress and we used to have pretty different code conventions (like using _ as prefix for private attributes), so we still have things to fix. We usually use the filter in the problems view to filter out checkstyle errors from this view, which helps to know what the real compilation problem are.
Besides this plugin we also recommend to use a subversion plugin, subversive or subclipse being the two options currently available in the open source landscape.
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.
Many things are pluggable in Ivy:
- module descriptor parsers
- dependency resolvers
- lock strategies
- latest strategies
- circular dependency strategies
- conflict managers
- report outputters
- version matchers
- triggers
If you still don't find what you need, then you'll have to develop your own plugin or find someone who could do that for you.
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.
All pluggable code in Ivy is located in the org.apache.ivy.plugins package. In each package you will find an interface that you must implement to provide a new plugin. We usually also provide an abstract class easing the implementation and making your code more independent of interface changes. We heavily recommend using these abstract classes as a base class.
To understand how your implementation can be done, we suggest looking at existing implementations we provide, it's the best way to get started.
Making a release
Making a release
Requirements
Requirements for making a release are similar to the requirements for building from source, except that sun jdk 1.6 and ant 1.7 are required.Procedure
1. Check the files which needs to be updated for the release.
On the trunk, check that files which require update for the release are up to date.This includes particularly:
RELEASE_NOTES
CHANGES
README
2. Create a release branch
This will allow to work separately from other developers, in case you need any last modification.svn copy https://svn.apache.org/repos/asf/ant/ivy/core/trunk \
https://svn.apache.org/repos/asf/ant/ivy/core/branches/2.0.0-beta1 \
-m "Creating a release branch for 2.0.0-beta1."
3. Check out the branch
svn co https://svn.apache.org/repos/asf/ant/ivy/core/branches/2.0.0-beta1 ivy-2.0.0-beta1
4. Add Ivy xsd file.
You need to store the current ivy xml schema in the documentation, so that it will later be accessible on public web site. To do so, run the following command in the directory in which you checked out the release branch:ant -f build-release.xml release-xsd
5. Add release note page in the documentation.
Open the file doc/index.html with your favorite browser, and click on the plus button in the upper right. Choose "Release Notes" as title, and "release-notes" as page id.Then edit the page (hit the first button at the upper right), and copy the content of the RELEASE_NOTES file.
You can also add the announcement for the release if it's already ready. If this is an incubator version, add the usual incubator disclaimer too.
Move the page up in the TOC using the arrow button in the toolbar at the upper right, so that it's the first child page under the "Documentation" page.
If you take the time to make the content of the release notes more "xooki compliant" (by removing unnecessary end of lines and adding h2 h3 and h4 tags), the page could then look like something like that:
http://ant.apache.org/ivy/history/2.0.0-alpha-1.html
6. Commit your changes
svn status
svn add doc/ivy.xsd
svn add doc/release-notes.html
svn ci -m "update templates, add release notes and ivy.xsd in documentation."
7. Check that you have no pending modifications
svn statusIf your working copy is clean, you can launch the release script. If it isn't, make sure to clean it properly. Sometimes you may need to call ant clean-all if you have started to work with ant builds. If you are confused about your working copy state, delete it and check it out again.
8. Launch the release script
ant -f build-release.xml releaseThe status should be release only for final releases, and milestone for any other intermediate release.
If anything is wrong, fix and go back to step 4.
If the release script is successful, release artifacts will be waiting for you in the build/distrib directory.
9. Verify the release
Check that all zips can be opened correctly, and that running 'ant' after unzipping the source distribution works properly.You can also do a smoke test with the generated ivy.jar , to see if it is able to resolve properly a basic module (for instance you can run some tutorials provided in the src/example directory in all distributions).
10. Sign and upload the artifacts
It's now time to sign the release artifacts and upload them to a location accessible by other Apache commiters.Here is a simple way to sign the files using gnupg:
gpg --armor --output file.zip.asc --detach-sig file.zipHere is a ruby script you can use to sign the files:
require 'find'Be prepared to enter your passphrase several times if you use this script, gpg will ask for your passphrase for each file to sign.
Find.find('build/distrib') do |f|
`gpg --armor --output #{f}.asc --detach-sig #{f}` if File.file?(f) && ['.zip', '.gz', '.jar', '.pom'].include?(File.extname(f))
end
When you're done upload the content of the distrib directory to a publicly accessible web site, your apache personal site being a good location for this. Make sure you include some kind of disclaimer somewhere to inform people the release is not approved yet.
You can for example add a HEADER.html like this:
<h2>WARNING: files available here are NOT an Apache approved release yet.</h2>
11. Prepare the Eclipse update site
To be able to test the release within IvyDE, it can be deployed in the IvyDE update site. See that page to know how to process.12. Tag the svn repository
As soon as you are happy with the artifacts to be released, it is time to tag the svn reposvn copy https://svn.apache.org/repos/asf/ant/ivy/core/branches/2.0.0-beta1 \And don't forget to set the svn:external on doc/xooki to a fixed revision. Edit the svn:external property on the folder doc/xooki in the tag and set it to the revision of the commit of the tag. It should look like:
https://svn.apache.org/repos/asf/ant/ivy/core/tags/2.0.0-beta1 \
-m "Tag release 2.0.0-beta1."
xooki -r790212 https://svn.apache.org/repos/asf/ant/ivy/site/xooki/And commit that modification.
13. Call for a vote to approve the release
Cast a vote to approve the release on the dev@ant.apache.org mailing list.Here is an example:
Subject: [VOTE] Ivy ${version} Release
I have built a release candidate for Ivy ${version}
You can download it from this URL: ${url}
Do you vote for the release of these binaries?
[ ] Yes
[ ] No
Regards,
${me}, Ivy ${version} release manager
14. Upload to public repository
If the release is approved, it's now time to make it public by uploading it to the public Apache distrib repository (i.e. /www/www.apache.org/dist/ant/ivy/[version] on people.a.o).Copy also the staging maven 2 repository to apache maven 2 rsync repo:
/www/people.apache.org/repo/m2-ibiblio-rsync-repository
15. Update the web site
Add a link to the released version documentation in the web site.To do so, you need to:
- add a svn externals reference to the documentation edit the svn properties of site/history, and in the svn:externals property, add a line like this one:
- edit the toc.json file in the site component of Ivy and add something like that:
- Now generate the part of the site for the new version
2.0.0-beta1 https://svn.apache.org/repos/asf/ant/ivy/core/branches/2.0.0-beta1/docYou should also change the latest-milestone external link.
You can use "svn propedit svn:externals path/to/history" to do so.
Once you've changed the property, use "svn up" to checkout the proper documentation.
{
"title":"2.0.0-beta1",
"url":"http://ant.apache.org/ivy/history/2.0.0-beta1/index.html"
}
You can also edit the title of the main documentation node pointing to latest-milestone / latest-release if necessary.ant generate-history-ivy -Dhistory.version=2.0.0-beta1
It's time to update the download image used on the home page and the download page. Use site/images/ivy-dl.xcf as a basis if you have gimp installed. Then you can update the home page to refer to this image, and add a news item announcing the new version. Update also the download page with the new image and update the links to the download location (using a search/replace on the html source is recommended for this).
All site editing being done, commit your changes.
And now let's generate the site and deploy it:
- generate the part of the site for the new version:
- generate the website with the new toc:
- you should verify that the site generated in target is OK. And once your happy with it, commit the changes in target (some svn add might be needed !)
- deploy the website: go on people.apache.org and svn up /www/ant.apache.org/ivy/
ant generate-history-ivy -Dhistory.version=2.0.0-beta1WARNING: that target is modifiying the toc.json in the imported branch so that the generated html have a proper version declared in the toc. You should not commit that change. Once the site has been generated, you may want to revert the changes so you won't commit it by mistake. (TODO: process to improve so we shouldn't worry).
ant /all generate-site-ivy
16. Deploy the Eclipse updatesite
If the Eclipse update site has already been prepared to include that new Ivy release, it is now needed to be deployed. Then follow the deployment instruction on that page.17. Announce
Announce the release on the dev@ant.a.o, ivy-user@ant.a.o, user@ant.apache.org and announce@apache.org mailing lists.You can also announce the release on popular web sites, like freshmeat.net (xavier is the owner of the Ivy project on freshmeat), javalobby.org, theserverside.com, dzone.com, ...
16. Update this doc
If you feel like anything is missing or misleading in this release doc, update it as soon as you encounter the problem.17. Merge your modifications back to the trunk if necessary.
Modifications on the template files do not need to be merged, but if you had troubles during your release you may want to merge your fixes back to the trunk.18. Prepare next release
Update the file version.properties with the version of the next release so that anyone building from the trunk will obtain jar with the correct version number.Release the version in jira, and create a new unreleased version for the next planned version.
Updating the updatesite
Once a release have been build for Ivy or IvyDE, they should be pushed to the Eclipse updatesite so that Eclipse users will be able to update automatically their installed version of Ivy or IvyDE.
This doc is in two parts, the setup of the updatesite which will be the candidate for the vote of the Ivy or IvyDE release, and the final deployment once the release is accepted.
Important note: in this doc, the released version is denoted as $VERSION (and have to be replaced accordingly in every commands), but this is the OSGi one, not the usually shown one, in particular for release candidate versions. For instance an Ivy version can be 2.0.0-RC1 but the OSGi one, and the one to use here is 2.0.0.cr1.
Build the updatesite
Push the new version
The update site svn location is there: https://svn.apache.org/repos/asf/ant/ivy/updatesite/trunk . You will update it so it will contain the new artifacts.Before installing the new version, you probably want to remove some deprecated version. For instance is the new release is a RC2, then the RC1 should be removed. But do keep old final release; some users might not want use to the exact same version of Ivy they use in Ant, which might not be the latest one. To do so just svn rm the jars, checksums and signatures of the features and plugins to remove.
- For an Ivy release:
As you have a build jar for Ivy, just do:ant install-ivy -Divy.jar=...../path/to/ivy.jar
-
For an IvyDE release:
The zip distribution needs to be unpacked into the updatesite directory:ant install-ivyde -Divyde.zip=...../path/to/org.apache.ivyde.feature-${VERSION}.zip
Prepare the update site
The update site is optimized: the metadata of the features are aggregated into the digest.zip, and the jar of the plugins are compressed with a better algorithm.Important note: the following optimize tasks need to be run in java 5 jre. The pack200 didn't existed before java 5 and the jar compressed with java 6 can not be uncompressed by some java 5 jre (at least the IBM one).
To accomplish this task, just run at the root of your working copy of the updatesite:
- For an Ivy release:
ant optimize-ivy
-
For an IvyDE release:
ant optimize-ivyde
ant checksumAnd sign the binaries:
- For an Ivy release:
./signIvyArtifacts.sh
-
For an IvyDE release:
./signIvyDEArtifacts.sh
And finally commit your changes.
As soon as you ar happy with the committed artifacts, we can tag the updatesite:
svn cp https://svn.apache.org/repos/asf/ant/ivy/updatesite/trunk https://svn.apache.org/repos/asf/ant/ivy/updatesite/tags/$TAGNAMEwith $TAGNAME the name of the release, so it would be either ivy-$VERSION or ivyde-$VERSION.
Test the updatesite
The updatesite is ready to be tested. You can deploy it where ever you want with the command:svn export https://svn.apache.org/repos/asf/ant/ivy/updatesite/trunk/dist updatesiteFor both local and remote testing, as the new jars are not yet deployed on Apache mirrors, the updatesite mirroring have to be disable.
Basically it is just about modifying the site.xml and remove the reference to the eclipse-update--xml files: remove the attribute mirrorsURL.
To let the developper community test the updatesite, you can setup a staging updatesite in your public_html directory on people.apache.org. So if you deploy it on people.apache.org, in the directory ~/public_html/staging, then the developpers should setup the updatesite with the URL http://people.apache.org/~LOGIN/staging/updatesite .
Deployment of a release
Then backup and deploy. On people.apache.org:cd /www/www.apache.org/dist/ant/ivyde/
mv updatesite ~/updatesite.backup
svn export https://svn.apache.org/repos/asf/ant/ivy/updatesite/tags/$TAGNAME/dist updatesite