You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by hi...@apache.org on 2014/12/26 17:35:11 UTC
svn commit: r1647996 [2/13] - in /ant/site/ivy/production/history/2.4.0: ./
dev/ js/ osgi/ samples/ samples/eclipse-plugin/ samples/standard-osgi/
samples/target-platform/ style/
Added: ant/site/ivy/production/history/2.4.0/book.html
URL: http://svn.apache.org/viewvc/ant/site/ivy/production/history/2.4.0/book.html?rev=1647996&view=auto
==============================================================================
--- ant/site/ivy/production/history/2.4.0/book.html (added)
+++ ant/site/ivy/production/history/2.4.0/book.html Fri Dec 26 16:35:10 2014
@@ -0,0 +1,6005 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<html>
+<head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <script type="text/javascript">var xookiConfig = {level: 0};</script>
+
+
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+<title>Documentation (2.4.0) | Apache Ivy™ @version@</title>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <link rel="stylesheet" type="text/css" href="style/print-style.css" />
+
+<script language="javascript" type="text/javascript">xooki = {u: function(url) {return "xooki/"+url;}};</script>
+</head>
+<body>
+
+<div id="body">
+
+<table id="header" summary="Navigation elements." border="0"
+ cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td id="home" width="30%"><a href="http://ant.apache.org/"
+ title="Apache Ant"><img src="images/ant-group-logo.gif" alt="Apache Ant"
+ border="0" /></a></td>
+
+ <td class="product" width="70%" align="right" valign="middle"><img
+ src="images/logo.png" alt="ivy" border="0" /></td>
+ </tr>
+</table>
+
+ <div id="main">
+ <div id="xooki-messages" onclick="xooki.html.hide('xooki-messages')" style="zIndex:999;display:none;position:absolute;top:30px;padding:10px;border-style:solid;background:#eeeeee;"></div><div class='toc-title toc-title-1'>Documentation (2.4.0)</div><br class="xooki-br"/>Welcome to the official Ivy documentation.<br class="xooki-br"/><br class="xooki-br"/><h1>What is Ivy?</h1>
+Ivy is a tool for managing (recording, tracking, resolving and reporting) project dependencies. It is characterized by the following:<br class="xooki-br"/><ol>
+<li>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.</li>
+
+<li>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.</li>
+</ol>
+Ivy is open source and released under a very permissive Apache License.<br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/>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 <a href="ivyfile.html">ivy file</a>. To find the metadata and your dependencies' artifacts (usually jars), Ivy can be configured to use a lot of different <a href="configuration/resolvers.html">repositories</a>.<br class="xooki-br"/><br class="xooki-br"/><h1>About this doc</h1>
+<div class="postit" style="width: 250px;">
+Tip: The menu on the left is dynamic, you can click on the arrows to browse the menu without going to each page.
+</div>
+This documentation has been migrated from the old Ivy web site hosted by Jayasoft, feel free to report any problem on the mailing-lists.<br class="xooki-br"/><br class="xooki-br"/>If you browse this documentation from your installation of Ivy, you can also check the <a href="http://ant.apache.org/ivy/">online version</a> for the latest updates.<br class="xooki-br"/><br class="xooki-br"/>You can also browse this documentation offline either by downloading the documentation distribution, or by checking out the doc directory from git. This documentation uses <a href="http://xooki.sourceforge.net/">xooki</a> as its documentation engine, so you can very easily edit it and submit patches when you browse it from source.<br class="xooki-br"/><br class="xooki-br"/>A <a href="book.html">printer-friendly version</a> of this whole documentation is also provided for your convenience.<br class="xooki-br"/><br class="xooki-br"/>Since Ivy 2.0.0-alpha-2, we keep an online history of the documentatio
n. 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.<br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/><h1>Other places to go</h1>
+Check out Ivy features. <br class="xooki-br"/>Read our FAQ.<br class="xooki-br"/>Ask for help on our mailing lists.<br class="xooki-br"/>Report a bug or feature request in our issue tracking system.<br class="xooki-br"/>Check external tools and resources.<br class="xooki-br"/><br class="xooki-br"/><h1>Overview</h1>
+This documentation is composed of three main parts:
+<ul>
+ <li><a href="tutorial.html">Tutorials</a></li>
+The tutorials is the best way to begin to play with Ivy. You will easily and quickly learn the basics of Ivy.<br class="xooki-br"/> <li><a href="reference.html">Reference</a></li>
+The reference documentation gives you all the details of Ivy. <br class="xooki-br"/>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. <br class="xooki-br"/>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).<br class="xooki-br"/> <li><a href="dev.html">Developer doc</a></li>
+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.
+</ul>
+<hr/><div class='toc-title toc-title-2'>Release Notes</div><br class="xooki-br"/><br class="xooki-br"/><h2>Announcement</h2>
+
+<pre>
+December 21, 2014 - The Apache Ivy project is pleased to announce its 2.4.0 release.<br class="xooki-br"/> <br class="xooki-br"/>Apache Ivy is a tool for managing (recording, tracking, resolving and<br class="xooki-br"/>reporting) project dependencies, characterized by flexibility,<br class="xooki-br"/>configurability, and tight integration with Apache Ant.<br class="xooki-br"/><br class="xooki-br"/>Key features of this 2.4.0 release are<br class="xooki-br"/>* some new Ant tasks<br class="xooki-br"/>* improved OSGI support<br class="xooki-br"/>* a Bintray resolver<br class="xooki-br"/>* numerous bug fixes as documented in Jira and in the release notes<br class="xooki-br"/> <br class="xooki-br"/>You can download this 2.4.0 release at:<br class="xooki-br"/><a href="http://ant.apache.org/ivy/download.cgi">http://ant.apache.org/ivy/download.cgi</a><br class="xooki-br"/> <br class="xooki-br"/>Issues should be reported to:<br class="xooki-br"/><a href="https://issues.apache.org/jira/brows
e/IVY">https://issues.apache.org/jira/browse/IVY</a><br class="xooki-br"/> <br class="xooki-br"/>More information can be found on the website:<br class="xooki-br"/><a href="http://ant.apache.org/ivy/">http://ant.apache.org/ivy/</a>
+</pre>
+
+<h2>List of Changes in this Release</h2>
+
+For details about the following changes, check our JIRA install at <br class="xooki-br"/><a href="http://issues.apache.org/jira/browse/ivy">http://issues.apache.org/jira/browse/ivy</a><br class="xooki-br"/> <br class="xooki-br"/>List of changes since Ivy 2.3.0:<br class="xooki-br"/><br class="xooki-br"/>- NEW: the buildobr task can now work a set of resolved artifacts: useful for managing an OSGi target platform<br class="xooki-br"/>- NEW: fixdeps task: serializes transitively resolved dependencies into an ivy.xml file<br class="xooki-br"/>- NEW: IvyDependencyTree task : display a dependency tree on the console<br class="xooki-br"/>- NEW: Support Conditional Setting of a Property (<a href="https://issues.apache.org/jira/browse/IVY-1367">IVY-1367</a>)<br class="xooki-br"/>- NEW: Exposing some parent metadata (organisation, module, revision, branch) as properties (<a href="https://issues.apache.org/jira/browse/IVY-1288">IVY-1288</a>)<br class="xooki-br"/>- NEW: symlinkmass feature bas
ed on symlink feature of ivy:retrieve (<a href="https://issues.apache.org/jira/browse/IVY-1252">IVY-1252</a>) (Thanks to Gene Smith)<br class="xooki-br"/>- NEW: Agent authentication for SSH and SFTP transports (<a href="https://issues.apache.org/jira/browse/IVY-1421">IVY-1421</a>)<br class="xooki-br"/>- NEW: New OSGi resolver 'osgi-agg': a chain resolver dedicated to better handle OSGi dependencies<br class="xooki-br"/>- NEW: Add support for "packed" artifacts: .pack.gz bundles in an OSGi P2 repository for instance<br class="xooki-br"/>- NEW: Ivy Bintray resolver (<a href="https://issues.apache.org/jira/browse/IVY-1474">IVY-1474</a>) (Thanks to Evgeny Goldin)<br class="xooki-br"/><br class="xooki-br"/>- IMPROVEMENT: Generate POMs with /xsd/maven-4.0.0.xsd reference instead of old /maven-v4_0_0.xsd (<a href="https://issues.apache.org/jira/browse/IVY-1491">IVY-1491</a>) (thanks to Hervé Boutemy)<br class="xooki-br"/>- IMPROVEMENT: Add support for packed jar within an OSGi bundle<br
class="xooki-br"/>- IMPROVEMENT: ModuleRules.getRule is O(n) leading to resolution slowness (<a href="https://issues.apache.org/jira/browse/IVY-1465">IVY-1465</a>) (Thanks to Zhong Wang aka Kewpie)<br class="xooki-br"/>- IMPROVEMENT: ivy:makepom will generate an exclusion when transitive=false on a dependency (<a href="https://issues.apache.org/jira/browse/IVY-1470">IVY-1470</a>)<br class="xooki-br"/>- IMPROVEMENT: New LockStrategy available based on NIO FileLocks (<a href="https://issues.apache.org/jira/browse/IVY-1424">IVY-1424</a>)<br class="xooki-br"/>- IMPROVEMENT: Optional <include> ivysettings directives (<a href="https://issues.apache.org/jira/browse/IVY-1392">IVY-1392</a>) (thanks to Yanus Poluektovich)<br class="xooki-br"/>- IMPROVEMENT: add support for source bundles from p2 repositories<br class="xooki-br"/>- IMPROVEMENT: add support for source URI from OBR repositories<br class="xooki-br"/>- IMPROVEMENT: Also copy original metadata artifact (e.g. POM) on ivy:install (<
a href="https://issues.apache.org/jira/browse/IVY-1431">IVY-1431</a>) (Thanks to Erwin Tratar)<br class="xooki-br"/>- IMPROVEMENT: useOrigin will do avoid copy with url resolvers configured with a 'file:/' URL<br class="xooki-br"/>- IMPROVEMENT: add support for source artifacts in buildobr task<br class="xooki-br"/>- IMPROVEMENT: add possibility to configure the User-Agent http header by setting a property http.agent (Thanks to Tony Likhite)<br class="xooki-br"/> <br class="xooki-br"/>- FIX: impossible to get artifacts when data has not been loaded. (<a href="https://issues.apache.org/jira/browse/IVY-1399">IVY-1399</a>) (Thanks to David Turner)<br class="xooki-br"/>- FIX: regression introduced by <a href="https://issues.apache.org/jira/browse/IVY-1457">IVY-1457</a>, dependency management wasn't properly handled introducing lots of resolution failures<br class="xooki-br"/>- FIX: The SSH resolvers fails if the un-required jsch jar is missing (<a href="https://issues.apache.org/jira/br
owse/IVY-1471">IVY-1471</a>)<br class="xooki-br"/>- FIX: failed to resolve dynamic revisions in some cases for URL repositories (<a href="https://issues.apache.org/jira/browse/IVY-1472">IVY-1472</a>)<br class="xooki-br"/>- FIX: ClassCastException in Eclipse 4.4.1 (<a href="https://issues.apache.org/jira/browse/IVY-1487">IVY-1487</a>) (Thanks to Carsten Pfeiffer)<br class="xooki-br"/>- FIX: NullPointerException when accessing charset to invalid URL (<a href="https://issues.apache.org/jira/browse/IVY-1452">IVY-1452</a>) (Thanks to Frédéric Riviere)<br class="xooki-br"/>- FIX: Can't resolve wildcard dependencies when remote artifact server does not set content-type header (<a href="https://issues.apache.org/jira/browse/IVY-1493">IVY-1493</a>) (Thanks to Andrew Bernhagen)<br class="xooki-br"/>- FIX: In IvyDE, Ivy fails to parse ivy-settings.xml file if it contains <pgp> element (thanks to Gregory Amerson) (<a href="https://issues.apache.org/jira/browse/IVY-1441">IVY-1441</a>)<br c
lass="xooki-br"/>- FIX: ParseException when "Bundle-Description" is present in OSGi MANIFEST.MF (<a href="https://issues.apache.org/jira/browse/IVY-1438">IVY-1438</a>)<br class="xooki-br"/>- FIX: NIO FileLocker released locks too early (<a href="https://issues.apache.org/jira/browse/IVY-1424">IVY-1424</a>) (thanks to Charles Duffy)<br class="xooki-br"/>- FIX: Ssh Resolver doesn't work with Java 7 (<a href="https://issues.apache.org/jira/browse/IVY-1408">IVY-1408</a>) (thanks to Mykhailo Delegan)<br class="xooki-br"/>- FIX: Parsing publication date in Ant tasks not thread-safe (<a href="https://issues.apache.org/jira/browse/IVY-1412">IVY-1412</a>)<br class="xooki-br"/>- FIX: NullPointerException when using httpclient and server doesn't return content-type header (<a href="https://issues.apache.org/jira/browse/IVY-1400">IVY-1400</a>) (thanks to Frederic Riviere)<br class="xooki-br"/>- FIX: Properly handle evicted nodes in ResolveReport<br class="xooki-br"/>- FIX: Artifact repository l
ocking did not correctly handle threaded use (<a href="https://issues.apache.org/jira/browse/IVY-1454">IVY-1454</a>) (thanks to Carsten Pfeiffer)<br class="xooki-br"/>- FIX: Better support for "Bundle-RequiredExecutionEnvironment" from an OSGi MANIFEST.MF<br class="xooki-br"/>- FIX: When inheriting a module descriptor, also merge the exclude rules<br class="xooki-br"/>- FIX: Correct application of mediators (ie. override) during conflict resolution (<a href="https://issues.apache.org/jira/browse/IVY-1455">IVY-1455</a>)<br class="xooki-br"/>- FIX: Fix revision number mapping across namespaces (<a href="https://issues.apache.org/jira/browse/IVY-1423">IVY-1423</a>)<br class="xooki-br"/>- FIX: fix a NPE when loading a composite P2 repository with no children<br class="xooki-br"/>- FIX: fix missing configuration when fixdeps is used with a partial resolve<br class="xooki-br"/>- FIX: XmlModuleDescriptorWritter doesn't support fully extra infos elements (<a href="https://issues.apache.org/
jira/browse/IVY-1457">IVY-1457</a>)<br class="xooki-br"/> <br class="xooki-br"/>- DOCUMENTATION: Broken link in <dependency> documentation (<a href="https://issues.apache.org/jira/browse/IVY-1405">IVY-1405</a>)<br class="xooki-br"/>- DOCUMENTATION: Explicitly document that threaded use is not supported.<br class="xooki-br"/><br class="xooki-br"/><h2>Committers and Contributors</h2>
+
+Here is the list of people who have contributed source code and documentation up to this release. Many thanks to all of them, and also to the whole IvyDE community contributing ideas and feedback, and promoting the use of Apache Ivy !<br class="xooki-br"/>
+<ul>Committers
+<li>Matt Benson</li>
+<li>Jean-Louis Boudart</li>
+<li>Maarten Coene</li>
+<li>Charles Duffy</li>
+<li>Xavier Hanin</li>
+<li>Nicolas Lalevee</li>
+<li>Jon Schneider</li>
+<li>Gilles Scokart</li>
+</ul>
+
+<ul>Contributors:
+<li>Ingo Adler</li>
+<li>alex322</li>
+<li>Mathieu Anquetin</li>
+<li>Andreas Axelsson</li>
+<li>Stephane Bailliez</li>
+<li>Karl Baum</li>
+<li>Andrew Bernhagen</li>
+<li>Mikkel Bjerg</li>
+<li>Per Arnold Blaasmo</li>
+<li>Jeffrey Blattman</li>
+<li>Jasper Blues</li>
+<li>Jim Bonanno</li>
+<li>Joseph Boyd</li>
+<li>Dave Brosius</li>
+<li>Matthieu Brouillard</li>
+<li>Carlton Brown</li>
+<li>Mirko Bulovic</li>
+<li>Ed Burcher</li>
+<li>Jamie Burns</li>
+<li>Wei Chen</li>
+<li>Chris Chilvers</li>
+<li>Kristian Cibulskis</li>
+<li>Andrea Bernardo Ciddio</li>
+<li>Archie Cobbs</li>
+<li>Flavio Coutinho da Costa</li>
+<li>Stefan De Boey</li>
+<li>Mykhailo Delegan</li>
+<li>Charles Duffy</li>
+<li>Martin Eigenbrodt</li>
+<li>Stephen Evanchik</li>
+<li>Robin Fernandes</li>
+<li>Gregory Fernandez</li>
+<li>Danno Ferrin</li>
+<li>Benjamin Francisoud</li>
+<li>Wolfgang Frank</li>
+<li>Jacob Grydholt Jensen</li>
+<li>John Gibson</li>
+<li>Mitch Gitman</li>
+<li>Evgeny Goldin</li>
+<li>Scott Goldstein</li>
+<li>Pierre Hägnestrand</li>
+<li>Scott Hebert</li>
+<li>Tobias Himstedt</li>
+<li>Aaron Hachez</li>
+<li>Ben Hale</li>
+<li>Stephen Haberman</li>
+<li>Peter Hayes</li>
+<li>Scott Hebert</li>
+<li>Payam Hekmat</li>
+<li>Achim Huegen</li>
+<li>Matt Inger</li>
+<li>Anders Jacobsson</li>
+<li>Anders Janmyr</li>
+<li>Steve Jones</li>
+<li>Christer Jonsson</li>
+<li>Michael Kebe</li>
+<li>Matthias Kilian</li>
+<li>Alexey Kiselev</li>
+<li>Gregory Kisling</li>
+<li>Stepan Koltsov</li>
+<li>Heschi Kreinick</li>
+<li>Sebastian Krueger</li>
+<li>Thomas Kurpick</li>
+<li>Tat Leung</li>
+<li>Costin Leau</li>
+<li>Antoine Levy-Lambert</li>
+<li>Tony Likhite</li>
+<li>Andrey Lomakin</li>
+<li>William Lyvers</li>
+<li>Sakari Maaranen</li>
+<li>Jan Materne</li>
+<li>Markus M. May</li>
+<li>Abel Muino</li>
+<li>J. Lewis Muir</li>
+<li>Stephen Nesbitt</li>
+<li>Joshua Nichols</li>
+<li>Bernard Niset</li>
+<li>Ales Nosek</li>
+<li>David Maplesden</li>
+<li>Glen Marchesani</li>
+<li>Phil Messenger</li>
+<li>Steve Miller</li>
+<li>Mathias Muller</li>
+<li>Randy Nott</li>
+<li>Peter Oxenham</li>
+<li>Douglas Palmer</li>
+<li>Jesper Pedersen</li>
+<li>Emmanuel Pellereau</li>
+<li>Carsten Pfeiffer</li>
+<li>Yanus Poluektovich</li>
+<li>Roshan Punnoose</li>
+<li>Jean-Baptiste Quenot</li>
+<li>Carl Quinn</li>
+<li>Damon Rand</li>
+<li>Geoff Reedy</li>
+<li>Torkild U. Resheim</li>
+<li>Christian Riege</li>
+<li>Frederic Riviere</li>
+<li>Jens Rohloff</li>
+<li>Andreas Sahlbach</li>
+<li>Brian Sanders</li>
+<li>Adrian Sandor</li>
+<li>Michael Scheetz</li>
+<li>Ben Schmidt</li>
+<li>Ruslan Shevchenko</li>
+<li>John Shields</li>
+<li>Nihal Sinha</li>
+<li>Gene Smith</li>
+<li>Simon Steiner</li>
+<li>Johan Stuyts</li>
+<li>John Tinetti</li>
+<li>Erwin Tratar</li>
+<li>Jason Trump</li>
+<li>David Turner</li>
+<li>Tjeerd Verhagen</li>
+<li>Richard Vowles</li>
+<li>Sven Walter</li>
+<li>James P. White</li>
+<li>Tom Widmer</li>
+<li>John Williams</li>
+<li>Chris Wood</li>
+<li>Patrick Woodworth</li>
+<li>Jaroslaw Wypychowski</li>
+<li>Sven Zethelius</li>
+<li>Aleksey Zhukov</li>
+<li>Zhong Wang</li>
+</ul>
+
+ <hr/><div class='toc-title toc-title-2'>Tutorials</div><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/><b>First Tutorial</b><br class="xooki-br"/><ol>
+<li>Make sure you have <a href="http://ant.apache.org/">ant</a> 1.6.0 or greater and a <a href="http://java.sun.com">jdk</a> properly installed</li>
+<li>Copy <a href="samples/build.xml">this build file</a> in an empty directory on your local filesystem (and make sure you name it build.xml)</li>
+<li>Open a console in this directory and run "ant". That's it!</li>
+</ol>
+If you have any trouble, check the <a href="http://ant.apache.org/ivy/faq.html">FAQ</a>. It is most likely related to your internet connection (proxy anyone?).<br class="xooki-br"/><br class="xooki-br"/>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 <a href="install.html">installed</a> Ivy and downloaded the tutorials sources (included in all Ivy distributions, in the <tt><a href="https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=tree;f=src/example">src/example</a></tt> directory).<br class="xooki-br"/><br class="xooki-br"/>The following tutorials are available:
+<ul>
+<li><a href="tutorial/start.html">Quick Start</a></li>
+Guides you through your very first steps with ivy.
+<li><a href="tutorial/defaultconf.html">Adjusting default settings</a></li>
+Gives you a better understanding of the default settings and shows you how to customize them to your needs.
+<li><a href="tutorial/multiple.html">Multiple Resolvers</a></li>
+Teaches you how to configure Ivy to find its dependencies in multiple places.
+<li><a href="tutorial/dual.html">Dual Resolver</a></li>
+Helps you configure Ivy to find ivy files in one place and artifacts in another.
+<li><a href="tutorial/dependence.html">Project dependencies</a></a></li>
+A starting point for using Ivy in a multi-project environment.
+<li><a href="tutorial/multiproject.html">Using Ivy in multiple projects environment</a></li>
+A more complex example demonstrating the use of Ant+Ivy in a multi-project environment.
+<li><a href="tutorial/conf.html">Using Ivy Module Configurations</a></li> Shows you how to use configurations in an ivy file to define sets of artifacts.
+<li><a href="tutorial/build-repository.html">Building a repository</a></li>
+Shows you how to build your own enterprise repository.
+</ul>
+ <hr/><div class='toc-title toc-title-3'>Quick Start</div><br class="xooki-br"/>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. <br class="xooki-br"/><br class="xooki-br"/><em>You'll find this tutorial's sources in the ivy distribution in the src/example/hello-ivy directory.</em><br class="xooki-br"/><br class="xooki-br"/><h1>The ivy.xml file</h1>
+This file is used to describe the dependencies of the project on other libraries.<br class="xooki-br"/>Here is the sample:
+<pre>
+<ivy-module version="2.0"><br class="xooki-br"/> <info organisation="org.apache" module="hello-ivy"/><br class="xooki-br"/> <dependencies><br class="xooki-br"/> <dependency org="commons-lang" name="commons-lang" rev="2.0"/><br class="xooki-br"/> <dependency org="commons-cli" name="commons-cli" rev="1.0"/><br class="xooki-br"/> </dependencies><br class="xooki-br"/></ivy-module>
+</pre>
+
+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. <br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/>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 <tt>org</tt> and <tt>name</tt> attributes to define the organization and module name of the dependencies we need. The <tt>rev</tt> attribute is used to specify the version of the module you depend on. <br class="xooki-br"/><br class="xooki-br"/>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 <a href="http://mvnrepository.com">mvnrepository.com</a> 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:
+<pre>
+<dependency><br class="xooki-br"/> <groupId>commons-lang</groupId><br class="xooki-br"/> <artifactId>commons-lang</artifactId><br class="xooki-br"/> <version>2.0</version><br class="xooki-br"/></dependency>
+</pre>
+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 <a href="tutorial/build-repository.html">Building a repository</a> that you can use namespaces to redefine these names if you want something cleaner).<br class="xooki-br"/><br class="xooki-br"/>If you want more details on what you can do in Ivy files, you can have a look at the <a href="ivyfile.html">Ivy files reference documentation</a>.<br class="xooki-br"/><h1>The bui
ld.xml file</h1>
+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.<br class="xooki-br"/>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:
+<pre>
+<project xmlns:ivy="antlib:org.apache.ivy.ant" name="hello-ivy" default="run"><br class="xooki-br"/> <br class="xooki-br"/> ...<br class="xooki-br"/> <br class="xooki-br"/> <!-- ================================= <br class="xooki-br"/> target: resolve <br class="xooki-br"/> ================================= --><br class="xooki-br"/> <target name="resolve" description="--> retrieve dependencies with ivy"><br class="xooki-br"/> <ivy:retrieve /><br class="xooki-br"/> </target><br class="xooki-br"/></project>
+</pre>
+As you can see, it's very easy to call Ivy to resolve and retrieve dependencies: all you need if Ivy is properly <a href="install.html">installed</a> is to define an XML namespace in your Ant file (xmlns:ivy="antlib:org.apache.ivy.ant"). Then all the <a href="ant.html">Ivy ant tasks</a> will be available in this namespace.<br class="xooki-br"/><br class="xooki-br"/>Here we use only one task: the <a href="use/retrieve.html">retrieve</a> task. With no attributes, it will use default settings and look for a file named <tt>ivy.xml</tt> for the dependency definitions. That's exactly what we want, so we need nothing more than that.<br class="xooki-br"/><br class="xooki-br"/>Note that in this case we define a <tt>resolve</tt> target and call the <tt><a href="use/retrieve.html">retrieve</a></tt> task. This may sound confusing, actually the retrieve task performs a <a href="use/resolve.html">resolve</a> (which resolves dependencies and downloads them to a cache) followed by a retrieve (a cop
y of those file to a local project directory). Check the <a href="principle.html">How does it work ?</a> page for details about that.<br class="xooki-br"/><h1>Running the project</h1>
+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 <tt>hello-ivy</tt> example directory.<br class="xooki-br"/>Then, at the command prompt, run <tt>ant</tt>:
+<div class="shell"><pre>
+
+</pre></div>
+<h1>What happened ?</h1>
+Without any settings, Ivy retrieves files from the maven 2 repository. That's what happened here. <br class="xooki-br"/>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 <a href="use/retrieve.html">retrieve</a> task).<br class="xooki-br"/><br class="xooki-br"/>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:
+<div class="shell"><pre>
+
+</pre></div>
+Great! The cache was used, so no download was needed and the build was instantaneous.<br class="xooki-br"/><br class="xooki-br"/>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 <a href="../samples/apache-hello-ivy-default.html">this</a>.<br class="xooki-br"/><br class="xooki-br"/>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 <a href="tutorial/conf.html">how to use module configurations</a> 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 <a href="reference.html">reference documentation</a>, and especially the introduction mate
rial which gives a good overview of Ivy. The <a href="bestpractices.html">best practices</a> page is also a must read to start thinking about how to use Ant+Ivy to build a clean and robust build system.<hr/><div class='toc-title toc-title-3'>Adjusting default settings</div><br class="xooki-br"/>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. <br class="xooki-br"/><br class="xooki-br"/>To fully understand the concept of settings and what you can do with them, we suggest reading other tutorials related to settings (like <a href="tutorial/multiple.html">Multiple Resolvers</a> and <a href="tutorial/dual.html">Dual Resolver</a>) or the <a href="settings.html">Settings Files</a> reference documentation.<br class="xooki-br"/><br class="xooki-br"/><h1>Concept</h1>
+The default settings include 3 types of repositories:
+<ul>
+<li>local</li> a repository which is private to the user.
+<li>shared</li> a repository which is shared between all the members of a team
+<li>public</li> a public repository on which most modules, and especially third party modules, can be found
+</ul>
+
+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.<br class="xooki-br"/><br class="xooki-br"/>Now let's describe each of these repository concepts in more detail. We will describe how they are set up physically later.<br class="xooki-br"/><h2>Local</h2>
+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.<br class="xooki-br"/><br class="xooki-br"/>For instance, if you have a module declaring a dependency on the module <i>foo</i> with a revision of <i>latest.integration</i>, then if a revision of <i>foo</i> is found in the local repository, it will be used, <em>even if a more recent revision is available in other repositories</em>. <br class="xooki-br"/><br class="xooki-br"/>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 <i>foo</i> and exploit this new method in module <i>bar</i>. Then if you publish the module <i>foo</i> to your local repository, you will be sure to ge
t it in your <i>bar</i> module, even if someone else publishes a new revision of <i>foo</i> in the shared repository (this revision not having the new method you are currently adding).<br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/>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. <br class="xooki-br"/><h2>Shared</h2>
+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).<br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><h2>Public</h2>
+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.<br class="xooki-br"/><h1>Setting up the repositories</h1>
+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.<br class="xooki-br"/><br class="xooki-br"/>First, several repositories use the same root in your filesystem. Referenced as <tt>${ivy.default.ivy.user.dir}</tt>, this is by default the directory <tt>.ivy2</tt> in your user home.<br class="xooki-br"/><br class="xooki-br"/>Note that several things can be done by setting Ivy variables. To set them without defining your own <tt>ivysettings.xml</tt> file, you can:<ul>
+<li>set an Ant property before any call to Ivy in your build file if you use Ivy from Ant</li>
+<li>set an environment variable if you use Ivy from the command line</li>
+</ul>
+For example:
+<pre>
+<target name="resolve"><br class="xooki-br"/> <property name="ivy.default.ivy.user.dir" value="/path/to/ivy/user/dir"/><br class="xooki-br"/> <ivy:resolve /><br class="xooki-br"/></target>
+</pre>
+
+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.<br class="xooki-br"/><h2>Local</h2>
+By default, the local repository lies in <tt>${ivy.default.ivy.user.dir}/local</tt>. 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: <pre>ivy.local.default.root</pre>. For instance:
+<pre>ivy.local.default.root=/opt/ivy/repository/local</pre>.<br class="xooki-br"/><br class="xooki-br"/>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:
+<pre>ivy.local.default.ivy.pattern</pre> gives the pattern to find ivy files
+<pre>ivy.local.default.artifact.pattern</pre> gives the pattern to find artifacts<br class="xooki-br"/>For example:
+<pre>
+ivy.local.default.root=/opt/ivy/repository/local<br class="xooki-br"/>ivy.local.default.ivy.pattern=[module]/[revision]/ivy.xml<br class="xooki-br"/>ivy.local.default.artifact.pattern=[module]/[revision]/[artifact].[ext]
+</pre>
+<h2>Shared</h2>
+By default, the shared repository lies in <tt>${ivy.default.ivy.user.dir}/shared</tt>. 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 <pre>ivy.shared.default.root</pre> variable to specify a different directory. Moreover, you can also configure the layout with variables similar to the ones used for the local repository:
+<pre>ivy.shared.default.ivy.pattern</pre> gives the pattern to find ivy files
+<pre>ivy.shared.default.artifact.pattern</pre> gives the pattern to find artifacts<br class="xooki-br"/>For example:
+<pre>
+ivy.shared.default.root=/opt/ivy/repository/shared<br class="xooki-br"/>ivy.shared.default.ivy.pattern=[organisation]/[module]/[revision]/ivy.xml<br class="xooki-br"/>ivy.shared.default.artifact.pattern=[organisation]/[module]/[revision]/[artifact].[ext]
+</pre>
+
+<h2>Public</h2>
+By default, the public repository is ibiblio in m2 compatible mode (in other words, the maven 2 public repository).<br class="xooki-br"/><br class="xooki-br"/>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. <br class="xooki-br"/><br class="xooki-br"/>Despite its ease of use, we suggest reading the <a href="bestpractices.html">Best practices</a> 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.<br class="xooki-br"/><br class="xooki-br"/><em>In 1.4 version Ivy was using ivyrep as the default resolver, if you want to restore this, set<br class="xooki-br"/>ivy.14.compatible=true as an ant property</em><br class="xooki-br"/><br class="xooki-br"/><h1>Going further</h1>
+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 ... <br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/>But before explaining how, you will need to have a quick overview of how Ivy is configured by default.<br class="xooki-br"/><br class="xooki-br"/>By default, Ivy is configured using an <tt>ivysettings.xml</tt> which is packaged in the Ivy jar. Here is this settings file:
+<pre>
+<ivysettings><br class="xooki-br"/> <settings defaultResolver="default"/><br class="xooki-br"/> <include url="${ivy.default.settings.dir}/ivysettings-public.xml"/><br class="xooki-br"/> <include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/><br class="xooki-br"/> <include url="${ivy.default.settings.dir}/ivysettings-local.xml"/><br class="xooki-br"/> <include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/><br class="xooki-br"/> <include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/><br class="xooki-br"/></ivysettings>
+</pre>
+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:
+<pre>
+<ivysettings><br class="xooki-br"/> <settings defaultResolver="default"/><br class="xooki-br"/> <include url="<a href="http://myserver/ivy/myivysettings-public.xml">http://myserver/ivy/myivysettings-public.xml</a>"/><br class="xooki-br"/> <include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/><br class="xooki-br"/> <include url="${ivy.default.settings.dir}/ivysettings-local.xml"/><br class="xooki-br"/> <include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/><br class="xooki-br"/> <include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/><br class="xooki-br"/></ivysettings>
+</pre>
+Note that only the <tt>ivysettings-public.xml</tt> inclusion has changed to include a homemade public resolver. Note also that this can be used like that thanks to the fact that <tt>${ivy.default.settings.dir}</tt> is a variable which is always set to the place where Ivy's default settings files are (i.e. packaged in the jar).<br class="xooki-br"/>To finish this example, you have to write your own ivysettings file (that you will make available at <a href="http://myserver/ivy/myivysettings-public.xml">http://myserver/ivy/myivysettings-public.xml</a> in this example) for defining your own public resolver. For instance:
+<pre>
+<ivysettings><br class="xooki-br"/> <resolvers><br class="xooki-br"/> <filesystem name="public"><br class="xooki-br"/> <ivy pattern="/path/to/my/public/rep/[organisation]/[module]/ivy-[revision].xml" /><br class="xooki-br"/> <artifact pattern="/path/to/my/public/rep/[organisation]/[module]/[artifact]-[revision].[ext]" /><br class="xooki-br"/> </filesystem><br class="xooki-br"/> </resolvers><br class="xooki-br"/></ivysettings>
+</pre>
+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:<br class="xooki-br"/><strong>ivysettings-public.xml</strong>
+<pre>
+<ivysettings><br class="xooki-br"/> <resolvers><br class="xooki-br"/> <ibiblio name="public" m2compatible="true"/><br class="xooki-br"/> </resolvers><br class="xooki-br"/></ivysettings>
+</pre>
+<strong>ivysettings-shared.xml</strong>
+<pre>
+<ivysettings><br class="xooki-br"/> <property name="ivy.shared.default.root" value="${ivy.default.ivy.user.dir}/shared" override="false"/><br class="xooki-br"/> <property name="ivy.shared.default.ivy.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/><br class="xooki-br"/> <property name="ivy.shared.default.artifact.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/><br class="xooki-br"/> <resolvers><br class="xooki-br"/> <filesystem name="shared"><br class="xooki-br"/> <ivy pattern="${ivy.shared.default.root}/${ivy.shared.default.ivy.pattern}" /><br class="xooki-br"/> <artifact pattern="${ivy.shared.default.root}/${ivy.shared.default.artifact.pattern}" /><br class="xooki-br"/> </filesystem><br class="xooki-br"/> </resolvers><br class="xooki-br"/></ivysettings>
+</pre>
+<strong>ivysettings-local.xml</strong>
+<pre>
+<ivysettings><br class="xooki-br"/> <property name="ivy.local.default.root" value="${ivy.default.ivy.user.dir}/local" override="false"/><br class="xooki-br"/> <property name="ivy.local.default.ivy.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/><br class="xooki-br"/> <property name="ivy.local.default.artifact.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/><br class="xooki-br"/> <resolvers><br class="xooki-br"/> <filesystem name="local"><br class="xooki-br"/> <ivy pattern="${ivy.local.default.root}/${ivy.local.default.ivy.pattern}" /><br class="xooki-br"/> <artifact pattern="${ivy.local.default.root}/${ivy.local.default.artifact.pattern}" /><br class="xooki-br"/> </filesystem><br class="xooki-br"/> </resolvers><br class="xooki-br"/></ivysettings>
+</pre>
+<strong>ivysettings-main-chain.xml</strong>
+<pre>
+<ivysettings><br class="xooki-br"/> <resolvers><br class="xooki-br"/> <chain name="main" dual="true"><br class="xooki-br"/> <resolver ref="shared"/><br class="xooki-br"/> <resolver ref="public"/><br class="xooki-br"/> </chain><br class="xooki-br"/> </resolvers><br class="xooki-br"/></ivysettings>
+</pre>
+<strong>ivysettings-default-chain.xml</strong>
+<pre>
+<ivysettings><br class="xooki-br"/> <resolvers><br class="xooki-br"/> <chain name="default" returnFirst="true"><br class="xooki-br"/> <resolver ref="local"/><br class="xooki-br"/> <resolver ref="main"/><br class="xooki-br"/> </chain><br class="xooki-br"/> </resolvers><br class="xooki-br"/></ivysettings>
+</pre>
+
+There you go, you should have enough clues to configure Ivy the way you want. Check the <a href="settings.html">settings documentation</a> to see if what you want to do is possible, and go ahead!<br class="xooki-br"/> <hr/><div class='toc-title toc-title-3'>Multiple Resolvers</div><br class="xooki-br"/>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:
+<ul>
+<li>separating integration builds from releases</li>
+<li>using a public repository for third party modules and a private one for internal modules</li>
+<li>use a repository for storing modules which are not accurate in an unmanaged public repository</li>
+<li>use a local repository to expose builds made on one developer's station</li>
+</ul>
+
+In Ivy, the use of multiple resolvers is supported by a compound resolver called the chain resolver.<br class="xooki-br"/><br class="xooki-br"/>In our example, we will simply show you how to use two resolvers, one on a local repository and one using the maven2 repository.<br class="xooki-br"/><br class="xooki-br"/><h1>project description</h1>
+<h2>the project: chained-resolvers</h2>
+The project is very simple and contains only one simple class: example.Hello.<br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/>Here is the content of the project:
+<ul>
+ <li>build.xml: the ant build file for the project</li>
+ <li>ivy.xml: the Ivy project file</li>
+ <li>src\example\Hello.java: the only class of the project</li>
+</ul>
+Let's have a look at the <b>ivy.xml</b> file:
+<pre>
+<ivy-module version="1.0"><br class="xooki-br"/> <info organisation="org.apache" module="chained-resolvers"/><br class="xooki-br"/> <dependencies><br class="xooki-br"/> <dependency org="commons-lang" name="commons-lang" rev="2.0"/><br class="xooki-br"/> <dependency name="test" rev="1.0"/><br class="xooki-br"/> </dependencies><br class="xooki-br"/></ivy-module>
+</pre>
+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').<br class="xooki-br"/><br class="xooki-br"/><h2>the <b>ivy settings</b></h2>
+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.<br class="xooki-br"/>
+<pre>
+<ivysettings><br class="xooki-br"/> <settings defaultResolver="chain-example"/><br class="xooki-br"/> <resolvers><br class="xooki-br"/> <chain name="chain-example"><br class="xooki-br"/> <filesystem name="libraries"><br class="xooki-br"/> <artifact pattern="${ivy.settings.dir}/repository/[artifact]-[revision].[ext]" /><br class="xooki-br"/> </filesystem><br class="xooki-br"/> <ibiblio name="ibiblio" m2compatible="true" /><br class="xooki-br"/> </chain><br class="xooki-br"/> </resolvers><br class="xooki-br"/></ivysettings>
+</pre>
+<h2>the <b>settings</b> tag</h2>
+This tag initializes Ivy with some parameters. Here only one parameter is set, the name of the resolver to use by default.<br class="xooki-br"/><br class="xooki-br"/><h2>the <b>resolvers</b> tag</h2>
+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.<br class="xooki-br"/>The resolvers in this chain are:
+<ul>
+ <li>libraries : It is a filesystem resolver, so looks at a directory structure to retrieve the artifacts. This one is configured to look in the <tt>repository</tt> sub directory of the directory that contains the <tt>ivysettings.xml</tt> file.</li>
+ <li>ibiblio : It looks in the ibiblio maven repository to retrieve the artifacts.</li>
+</ul>
+
+That's it, we have just configured a chain of resolvers!<br class="xooki-br"/><br class="xooki-br"/><h1>walkthrough</h1>
+<div class="step">
+<h2>step 1: preparation</h2>
+Open a DOS or shell window, and go to the "chained-resolvers" directory.
+</div>
+<div class="step">
+<h2>step 2: clean directory tree</h2>
+On the prompt type: ant<br>
+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.<br class="xooki-br"/>
+<div class="tip">
+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. <br class="xooki-br"/><br class="xooki-br"/>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.
+</div>
+</div>
+<div class="step">
+<h2>step 3: run the project</h2>
+Go to <tt>chained-resolvers</tt> project directory. And simply run <tt>ant</tt>.<br class="xooki-br"/>
+<div class="shell"><pre>
+
+</pre></div></div>
+
+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). <br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/><h1>Going further</h1>
+This very simple example helps us see how to set up two resolvers in a chain. The <a href="resolver/chain.html">chain resolver's reference documentation</a> is available for those who would like to know all the features offered by this resolver.<br class="xooki-br"/><br class="xooki-br"/>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!
+<ul>
+<li>a chain is not limited to two nested resolvers, you can use as many as you want</li>
+<li>by setting <tt>returnFirst="true"</tt>, you can have a chain which stops as soon as it has found a result for a given module</li>
+<li>by setting <tt>dual="true"</tt>, the full chain will be used both for module descriptors and artifacts, while setting <tt>dual="false"</tt>, the resolver in the chain which found the module descriptor (if any) is also used for artifacts</li>
+</ul>
+
+ <hr/><div class='toc-title toc-title-3'>Dual Resolver</div><br class="xooki-br"/>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?<br class="xooki-br"/><br class="xooki-br"/>Use a Dual resolver! And this tutorial will show you how.<br class="xooki-br"/><br class="xooki-br"/><h1>project description</h1>
+Let's have a look at the <tt>src/example/dual</tt> directory in your Ivy distribution.<br class="xooki-br"/>It contains a build file and 3 directories:
+<ul>
+<li>settings: contains the ivy settings file</li>
+<li>repository: a sample repository of ivy files</li>
+<li>project: the project making use of Ivy with dual resolver</li>
+</ul>
+
+<h2>the dual project</h2>
+The project is very simple and contains only one simple class: <tt>example.Hello</tt>
+It depends on two libraries: Apache commons-lang and Apache commons-httpclient.<br class="xooki-br"/><br class="xooki-br"/>Here is the content of the project:
+<ul>
+ <li>build.xml: the ant build file for the project</li>
+ <li>ivy.xml: the ivy project file</li>
+ <li>src\example\Hello.java: the only class of the project</li>
+</ul>
+
+Let's have a look at the <tt>ivy.xml</tt> file:
+<pre>
+<ivy-module version="1.0"><br class="xooki-br"/> <info organisation="org.apache" module="hello-ivy"/><br class="xooki-br"/> <dependencies><br class="xooki-br"/> <dependency org="commons-httpclient" name="commons-httpclient" rev="2.0.2"/><br class="xooki-br"/> <dependency org="commons-lang" name="commons-lang" rev="2.0"/><br class="xooki-br"/> </dependencies><br class="xooki-br"/></ivy-module>
+</pre>
+
+As you can see, nothing special here... Indeed, Ivy's philosophy is to keep ivy files independent of the way dependencies are resolved.<br class="xooki-br"/><br class="xooki-br"/><h2>the <b>ivy</b> settings</h2>
+The ivy settings are defined in the <tt>ivysettings.xml</tt> file located in the <tt>settings</tt> directory. Here is what it contains, followed by an explanation.<br class="xooki-br"/>
+<pre>
+<ivysettings><br class="xooki-br"/> <settings defaultResolver="dual-example"/><br class="xooki-br"/> <resolvers><br class="xooki-br"/> <dual name="dual-example"><br class="xooki-br"/> <filesystem name="ivys"><br class="xooki-br"/> <ivy pattern="${ivy.settings.dir}/../repository/[module]-ivy-[revision].xml" /><br class="xooki-br"/> </filesystem><br class="xooki-br"/> <ibiblio name="ibiblio" m2compatible="true" usepoms="false" /><br class="xooki-br"/> </dual><br class="xooki-br"/> </resolvers><br class="xooki-br"/></ivysettings>
+</pre>
+
+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.<br class="xooki-br"/><br class="xooki-br"/>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 <tt>repository</tt> directory, named with the pattern: <tt>[module]-ivy-[revision].xml</tt>. If we check the <tt>repository</tt> directory, we can confirm that it contains a file named <tt>commons-httpclient-ivy-2.0.2.xml</tt>. This file matches the pattern, so it will be found by the resolver.<br class="xooki-br"/><br class="xooki-br"/>The artifact resolver is simply an ibiblio one, configured in m2compatible mode to use t
he maven 2 repository, with <tt>usepoms="false"</tt> 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.<br class="xooki-br"/><br class="xooki-br"/><h1>walkthrough</h1>
+<div class="step">
+<h2>step 1 : preparation</h2>
+Open a DOS or shell window, and go to the <tt>dual</tt> directory.
+</div>
+<div class="step">
+<h2>step 2 : clean up</h2>
+On the prompt type : <tt>ant</tt><br>
+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.
+</div>
+<div class="step">
+<h2>step 3 : run the project</h2>
+Go to the project directory. And simply run <tt>ant</tt>.
+<div class="shell"><pre>
+
+</pre></div></div>
+<br/>
+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 <tt>repository</tt> directory:
+<pre>
+<ivy-module version="1.0"><br class="xooki-br"/> <info <br class="xooki-br"/> organisation="commons-httpclient"<br class="xooki-br"/> module="commons-httpclient"<br class="xooki-br"/> revision="2.0.2"<br class="xooki-br"/> status="release"<br class="xooki-br"/> publication="20041010174300"/><br class="xooki-br"/> <dependencies><br class="xooki-br"/> <dependency org="commons-logging" name="commons-logging" rev="1.0.4" conf="default"/><br class="xooki-br"/> </dependencies><br class="xooki-br"/></ivy-module>
+</pre>
+<br/>
+So everything seemed to work. The ivy file was found in the <tt>repository</tt> directory and the artifacts have been downloaded from ibiblio. <br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/>For full details about the dual resolver, have a look at the corresponding <a href="resolver/dual.html">reference documentation</a>.<br class="xooki-br"/> <hr/><div class='toc-title toc-title-3'>Project dependencies</div><br class="xooki-br"/>This tutorial will show you how to use Ivy when one of your projects depends on another.<br class="xooki-br"/><br class="xooki-br"/>For our example, we will have two projects, depender and dependee, where the depender project uses/requires the dep
endee project. This example will help illustrate two things about Ivy:
+<ul>
+ <li>that dependencies defined by parent projects (dependee) will automatically be retrieved for use by child projects (depender)</li>
+ <li>that child projects can retrieve the "latest" version of the dependee project</li>
+</ul>
+<h1>projects used</h1>
+<h2>dependee</h2>
+The dependee project is very simple. It depends on the apache library commons-lang and contains only one class: <tt>standalone.Main</tt> which provides two services:
+<ul>
+ <li>return the version of the project</li>
+ <li>capitalize a string using <tt>org.apache.commons.lang.WordUtils.capitalizeFully</tt></li>
+</ul>
+Here is the content of the project:
+<ul>
+ <li>build.xml: the ant build file for the project</li>
+ <li>ivy.xml: the project ivy file</li>
+ <li>src\standalone\Main.java: the only class of the project</li>
+</ul>
+Take a look at the <b>ivy.xml</b> file:
+<pre>
+<ivy-module version="1.0"><br class="xooki-br"/> <info organisation="org.apache" module="dependee"/><br class="xooki-br"/> <dependencies><br class="xooki-br"/> <dependency org="commons-lang" name="commons-lang" rev="2.0"/><br class="xooki-br"/> </dependencies><br class="xooki-br"/></ivy-module>
+</pre>
+
+The ivy file declares only one dependency, that being the apache commons-lang library.<br class="xooki-br"/><h2>depender</h2>
+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, <tt>depending.Main</tt>, which does 2 things:
+<ul>
+ <li>gets the version of the standalone project by calling <tt>standalone.Main.getVersion()</tt></li>
+ <li>transforms a string by calling <tt>standalone.Main.capitalizeWords(str)</tt></li>
+</ul>
+Take a look at the <tt>ivy.xml</tt> file:
+<pre>
+<ivy-module version="1.0"><br class="xooki-br"/> <info organisation="org.apache" module="depender"/><br class="xooki-br"/> <dependencies><br class="xooki-br"/> <dependency name="dependee" rev="latest.integration" /><br class="xooki-br"/> </dependencies><br class="xooki-br"/></ivy-module>
+</pre>
+
+<h1>settings</h1>
+The Ivy settings are defined in two files located in the settings directory:
+<ul>
+ <li><tt>ivysettings.properties</tt>: a property file</li>
+ <li><tt>ivysettings.xml</tt>: the file containing the settings</li>
+</ul>
+
+Let's have a look at the <tt>ivysettings.xml</tt> file:
+<pre>
+<ivysettings><br class="xooki-br"/> <properties file="${ivy.settings.dir}/ivysettings.properties"/><br class="xooki-br"/> <settings defaultResolver="libraries" /><br class="xooki-br"/> <caches defaultCacheDir="${ivy.settings.dir}/ivy-cache" /><br class="xooki-br"/> <resolvers><br class="xooki-br"/> <filesystem name="projects"><br class="xooki-br"/> <artifact pattern="${repository.dir}/[artifact]-[revision].[ext]" /><br class="xooki-br"/> <ivy pattern="${repository.dir}/[module]-[revision].xml" /><br class="xooki-br"/> </filesystem><br class="xooki-br"/> <ibiblio name="libraries" m2compatible="true" usepoms="false" /><br class="xooki-br"/> </resolvers><br class="xooki-br"/> <modules><br class="xooki-br"/> <module organisation="org.apache" name="dependee" resolver="projects"/><br class="xooki-br"/> </modules><br class="xooki-br"/></ivysettings>
+</pre>
+The file contains four main tags: properties, settings, resolvers and modules.<br class="xooki-br"/><h2>properties</h2>
+This tag loads some properties for the Ivy process, just like Ant does.<br class="xooki-br"/><h2>settings</h2>
+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 <tt>ivysettings.xml</tt> file itself. <br class="xooki-br"/>The second parameter, tells Ivy to use a resolver named "libraries" as its default resolver. More information can be found in the <a href="settings.html">settings reference documentation</a>.<br class="xooki-br"/><h2>resolvers</h2>
+This tag defines the resolvers to use. Here we have two resolvers defined: "projects" and "libraries".<br class="xooki-br"/>The filesystem resolver called "projects" is able to resolve the internal dependencies by locating them on the local filesystem. <br class="xooki-br"/>The ibiblio resolver called "libraries" is able to find dependencies on the maven 2 repository, but doesn't use maven poms.<br class="xooki-br"/><h2>modules</h2>
+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 <tt>org.apache</tt> and module name of <tt>dependee</tt>. This actually corresponds to only one module, but a regular expression could be used, or many other types of expressions (like glob expressions).<br class="xooki-br"/><br class="xooki-br"/>All other modules (i.e. all modules but org.apache#dependee), will use the default resolver ("libraries").<br class="xooki-br"/><h1>walkthrough</h1>
+<div class="step">
+<h2>step 1: preparation</h2>
+Open a DOS or shell window, and go to the <tt>src/example/dependence</tt> directory.
+</div>
+<div class="step">
+<h2>step 2: clean directory tree</h2>
+On the prompt type: <tt>ant</tt>
+This will clean up the entire project directory tree. You can do this each time you want to clean up this example.
+</div>
+<div class="step">
+<h2>step 3: publication of dependee project</h2>
+Go to <tt>dependee</tt> directory and publish the project
+<div class="shell"><pre>
+
+</pre></div>
+What we see here:
+<ul>
+ <li>the project depends on 1 library (1 artifact)</li>
+ <li>the library was not in the Ivy cache and so was downloaded (1 downloaded)</li>
+ <li>the project has been released under version number 1</li>
+</ul>
+</div>
+As you can see, the call to the publish task has resulted in two main things:
+<ul>
+<li>the delivery of a resolved ivy file to <tt>build/ivy.xml</tt>.</li>
+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: <tt>${build.dir}/[artifact].[ext]</tt>. For an ivy file, this resolves to <tt>build/ivy.xml</tt>. Because this file does not exist, it automatically makes a call to the deliver task which delivers a resolved ivy file to this destination.<br class="xooki-br"/>
+<li>the publication of artifact 'dependee' and its resolved ivy file to the repository.</li>
+Both are just copies of the files found in the current project, or more precisely, those in the <tt>build</tt> directory. This is because the artifactspattern has been set to <tt>${build.dir}/[artifact].[ext]</tt>, so the dependee artifact is found at <tt>build/dependee.jar</tt> and the ivy file in <tt>build/ivy.xml</tt>. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to <tt>repository\dependee-1.jar</tt> and to <tt>repository\dependee-1.xml</tt>, respecting the artifact and ivy patterns of our settings (see above).
+</ul>
+
+<div class="step">
+<h2>step 4: running the depender project</h2>
+Go to directory depender and run <tt>ant</tt>
+<div class="shell"><pre>
+
+</pre></div>
+What we see here:
+<ul>
+ <li>the project depends on 2 libraries (2 artifacts)</li>
+ <li>one of the libraries was in the cache because there was only 1 download (1 downloaded)</li>
+ <li>Ivy retrieved version 1 of the project "dependee". The call to <tt>standalone.Main.getVersion()</tt> has returned 1. If you look in the <tt>depender/lib</tt> directory, you should see <tt>dependee-1.jar</tt> which is the version 1 artifact of the project "dependee"</li>
+ <li>the call to <tt>standalone.Main.capitalizeWords(str)</tt> succeed, which means that the required library was in the classpath. If you look at the <tt>lib</tt> directory, you will see that the library <tt>commons-lang-2.0.jar</tt> was also retrieved. This library was declared as a dependency of the "dependee" project, so Ivy retrieves it (transitively) along with the dependee artifact.</li>
+</ul>
+</div>
+<div class="step">
+<h2>step 5: new version of dependee project</h2>
+Like we did before in step 3, publish the dependee project again. This will result in a new version of the project being published.
+<div class="shell"><pre>
+
+</pre></div>
+Now if you look in your repository folder, you will find 2 versions of the dependee project.<br class="xooki-br"/>Let's look at it:
+<div class="shell"><pre>I:\dependee>dir ..\settings\repository /w<br class="xooki-br"/><br class="xooki-br"/>[.] [..] dependee-1.jar dependee-1.xml dependee-2.jar dependee-2.xml<br class="xooki-br"/><br class="xooki-br"/>I:\dependee></pre></div>
+</div>
+OK, now our repository contains two versions of the project <b>dependee</b>, so other projects can refer to either version.
+<div class="step">
+<h2>step 6: get the new version in <em>depender</em> project</h2>
+What should we expect if we run the depender project again? It should:
+<ul>
+ <li>retrieve version 2 as the latest.integration version of the dependee project</li>
+ <li>display version 2 of dependee project</li>
+</ul>
+Let's try it!!
+<div class="shell"><pre>
+
+</pre></div>
+OK, we got what we expected as the <tt>run</tt> 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.
+</div>
+
+ <hr/><div class='toc-title toc-title-3'>Using Ivy in multiple projects environment</div><br class="xooki-br"/>In the previous tutorial, you saw how to deal with dependencies between two simple projects.<br class="xooki-br"/><br class="xooki-br"/>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 <tt>src/example/multi-project</tt> directory of the Ivy distribution.<br class="xooki-br"/><br class="xooki-br"/><h1>Context</h1>
+Here is a 10000ft overview of the projects involved in this tutorial:
+<ul>
+<li>version</li> helps to identify module by a version
+<li>list</li> gives a list of files in a directory (recursively)
+<li>size</li> gives the total size of all files in a directory, or of a collection of files
+<li>find</li> find files in a given dir or among a list of files which match a given name
+<li>sizewhere</li> gives the total size of files matching a name in a directory
+<li>console</li> give access to all other modules features through a simple console app
+</ul>
+For sure this is not aimed to demonstrate how to develop a complex app or give indication of advanced algorithm :-)<br class="xooki-br"/><br class="xooki-br"/>But this gives a simple understanding of how Ant+Ivy can be used to develop an application divided in multiple modules.<br class="xooki-br"/><br class="xooki-br"/>Now, here is how these modules relate to each other:<br class="xooki-br"/><center><a href="../samples/projects-dependencies-graph.jpg"><img src="samples/projects-dependencies-graph-small.jpg" alt="dependencies graph"/><br/><i>click to enlarge</i></a></center>
+
+Modules in yellow are the modules described in this tutorial, and modules in blue are external dependencies (we will see how to generate this graph later in this tutorial).<br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/><h1>The example files</h1>
+The sources for this tutorial can be found in <tt>src/example/multi-project</tt> in the Ivy distribution. In this directory, you will find the following files:
+<ul>
+<li><a href="https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/example/multi-project/build.xml">build.xml</a></li>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)
+<li>common
+<ul>
+<li><a href="https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/example/multi-project/common/common.xml">common.xml</a></li> 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.
+<li><a href="https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/example/multi-project/common/build.properties">build.properties</a></li>some properties common to all projects
+</ul>
+</li>
+<li>projects</li>
+contains a directory per module, with each containing:
+<ul>
+<li>ivy.xml</li>Ivy file of the module, describing its dependencies upon other modules and/or external modules.<br class="xooki-br"/>Example:
+<pre>
+<ivy-module version="1.0"><br class="xooki-br"/> <info <br class="xooki-br"/> organisation="org.apache.ivy.example"<br class="xooki-br"/> module="find"<br class="xooki-br"/> status="integration"/><br class="xooki-br"/> <configurations><br class="xooki-br"/> <conf name="core"/><br class="xooki-br"/> <conf name="standalone" extends="core"/><br class="xooki-br"/> </configurations><br class="xooki-br"/> <publications><br class="xooki-br"/> <artifact name="find" type="jar" conf="core" /><br class="xooki-br"/> </publications><br class="xooki-br"/> <dependencies><br class="xooki-br"/> <dependency name="version" rev="latest.integration" conf="core->default" /><br class="xooki-br"/> <dependency name="list" rev="latest.integration" conf="core" /><br class="xooki-br"/> <dependency org="commons-collections" name="commons-collections" rev="3.1" conf="
core->default" /><br class="xooki-br"/> <dependency org="commons-cli" name="commons-cli" rev="1.0" conf="standalone->default" /><br class="xooki-br"/> </dependencies><br class="xooki-br"/></ivy-module>
+</pre>
+<li>build.xml</li>The build file of the project, which consists mainly of an import of the common build file and of a module specific properties file:
+<pre>
+<project name="find" default="compile"><br class="xooki-br"/> <property file="build.properties"/><br class="xooki-br"/> <br class="xooki-br"/> <import file="${common.dir}/common.xml"/><br class="xooki-br"/></project>
+</pre>
+<li>build.properties</li>Module specific properties + properties to find the common build file
+<pre>
+projects.dir = ${basedir}/..<br class="xooki-br"/>wkspace.dir = ${projects.dir}/..<br class="xooki-br"/>common.dir = ${wkspace.dir}/common
+</pre>
+<li>src</li> the source directory with all java sources
+</ul>
+</ul>
+
+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.<br class="xooki-br"/><br class="xooki-br"/>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).<br class="xooki-br"/><br class="xooki-br"/>So, here are some aspects of this common build file:<br class="xooki-br"/><h2>ivy settings</h2>
+<pre>
+<!-- setup ivy default configuration with some custom info --><br class="xooki-br"/><property name="ivy.local.default.root" value="${repository.dir}/local"/><br class="xooki-br"/><property name="ivy.shared.default.root" value="${repository.dir}/shared"/><br class="xooki-br"/><br class="xooki-br"/><!-- here is how we would have configured ivy if we had our own ivysettings file<br class="xooki-br"/><ivy:settings file="${common.dir}/ivysettings.xml" id="ivy.instance" /><br class="xooki-br"/>-->
+</pre>
+
+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 <a href="tutorial/defaultconf.html">default settings tutorial</a> 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).<br class="xooki-br"/>Commented out you can see how the settings would have been done if the default setting wasn't OK for our purpose.<br class="xooki-br"/><br class="xooki-br"/><h2>resolve dependencies</h2>
+<pre>
+<target name="resolve" depends="clean-lib, load-ivy" description="--> resolve and retrieve dependencies with ivy"><br class="xooki-br"/> <mkdir dir="${lib.dir}"/> <!-- not usually necessary, ivy creates the directory IF there are dependencies --><br class="xooki-br"/> <br class="xooki-br"/> <!-- the call to resolve is not mandatory, retrieve makes an implicit call if we don't --><br class="xooki-br"/> <ivy:resolve file="${ivy.file}"/><br class="xooki-br"/> <ivy:retrieve pattern="${lib.dir}/[artifact].[ext]" /><br class="xooki-br"/></target>
+</pre>
+You should begin to be familiar with using Ivy this way. We call <i>resolve</i> explicitly to use the ivy file configured (the default would have been fine), and then call <i>retrieve</i> 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.<br class="xooki-br"/><br class="xooki-br"/><h2>ivy-new-version</h2>
+<pre>
+<target name="ivy-new-version" depends="load-ivy" unless="ivy.new.revision"><br class="xooki-br"/> <!-- default module version prefix value --><br class="xooki-br"/> <property name="module.version.prefix" value="${module.version.target}-dev-b" /><br class="xooki-br"/> <br class="xooki-br"/> <!-- asks Ivy for an available version number --><br class="xooki-br"/> <ivy:info file="${ivy.file}" /><br class="xooki-br"/> <ivy:buildnumber <br class="xooki-br"/> organisation="${ivy.organisation}" module="${ivy.module}" <br class="xooki-br"/> revision="${module.version.prefix}" defaultBuildNumber="1" revSep=""/><br class="xooki-br"/></target>
+</pre>
+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 <a href="use/buildnumber.html">buildnumber</a> 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 <tt>module.version.target</tt> in the <tt>common/build.properties</tt> file). Each module built by this common build file could easily override this by either setting a different <tt>module.version.target</tt> in its module specific <tt>build.properties</tt>, or even overriding <tt>module.version.prefix</tt>. 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.<br class="xooki-br"/><br class="xooki-br"/><h2>publish</h2>
+<pre>
+<target name="publish" depends="clean-build, jar" description="--> publish this project in the ivy repository"><br class="xooki-br"/> <ivy:publish artifactspattern="${build.dir}/[artifact].[ext]" <br class="xooki-br"/> resolver="shared"<br class="xooki-br"/> pubrevision="${version}" <br class="xooki-br"/> status="release"<br class="xooki-br"/> /><br class="xooki-br"/> <echo message="project ${ant.project.name} released with version ${version}" /><br class="xooki-br"/></target>
+</pre>
+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.<br class="xooki-br"/><h2>publish-local</h2>
+<pre>
+<target name="publish-local" depends="local-version, jar" description="--> publish this project in the local ivy repository"><br class="xooki-br"/> <ivy:publish artifactspattern="${build.dir}/[artifact].[ext]" <br class="xooki-br"/> resolver="local"<br class="xooki-br"/> pubrevision="${version}"<br class="xooki-br"/> pubdate="${now}"<br class="xooki-br"/> status="integration"<br class="xooki-br"/> forcedeliver="true"<br class="xooki-br"/> /><br class="xooki-br"/> <echo message="project ${ant.project.name} published locally with version ${version}" /><br class="xooki-br"/></target>
+</pre>
+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 <tt>publish-local</tt> in this module, and then your next build of the other module will automatically get this local version.<br class="xooki-br"/><h2>clean-local</h2>
+<pre>
+<target name="clean-local" description="--> cleans the local repository for the current module"><br class="xooki-br"/> <delete dir="${ivy.local.default.root}/${ant.project.name}"/><br class="xooki-br"/></target>
+</pre>
+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.<br class="xooki-br"/><h2>report</h2>
+<pre>
+<target name="report" depends="resolve" description="--> generates a report of dependencies"><br class="xooki-br"/> <ivy:report todir="${build.dir}"/><br class="xooki-br"/></target>
+</pre>
+Generates both an html report and a graphml report.<br class="xooki-br"/><br class="xooki-br"/>For example, to generate a graph like the one shown at the beginning of this tutorial, you just have to follow the instructions given <a href="yed.html">here</a> with the graphml file you will find in <pre>projects/console/build/</pre> after having called report in the console project, and that's it, you have a clear overview of all your app dependencies!<br class="xooki-br"/><br class="xooki-br"/><h1>Playing with the projects</h1>
+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:
+<div class="shell"><pre>
+
+</pre></div>
+
+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 <tt>ant publish-all</tt> (example log <a href="log/multi-project-general-publishall.txt">here</a>).<br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/>Then you can go in one of the example project directories (like projects/find for instance), and run <tt>ant -p</tt>:
+<div class="shell"><pre>
+
+</pre></div>
+
+You can see the targets available, thanks to the import of the <tt>common.xml</tt> 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 <tt>latest.integration</tt> 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!<br class="xooki-br"/><br class="xooki-br"/>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 <a href="reference.html">reference documentation</a> 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!<hr/><div class='toc-title toc-title-3'>Using Ivy Module Configurations</div><br class="xooki-br"/>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 :-)<br class="xooki-br"/><br class="xooki-br"/>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.<br class="xooki-br"/><br class="xooki-br"/>Reference documentation on configurations can be found <a href="../terminology.html">here</a> and <a href="../ivyfile/configurations.html">here</a>.<br class="xooki-br"/><h1>Introduction</h1>
+Source code is available in <tt>src/example/configurations/multi-projects</tt>.<br class="xooki-br"/>We have two projects :<br class="xooki-br"/> - filter-framework is a library that defines an api to filter String arrays and two implementations of this api.<br class="xooki-br"/> - myapp is a very small app that uses filter-framework.<br class="xooki-br"/> <br class="xooki-br"/>The filter-framework library project produces 3 artifacts:<br class="xooki-br"/> - the api jar,<br class="xooki-br"/> - an implementation jar with no external dependencies,<br class="xooki-br"/> - a second implementation jar that needs commons-collections to perform.<br class="xooki-br"/><br class="xooki-br"/>The application only needs the api jar to compile and can use either of the two implementations at runtime.<br class="xooki-br"/><br class="xooki-br"/><h1>The library project</h1>
+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.<br class="xooki-br"/><h2>The ivy.xml file</h2>
+
+<div class="ivy-file">
+<pre>
+<ivy-module version="1.0"><br class="xooki-br"/> <info organisation="org.apache" module="filter-framework"/><br class="xooki-br"/> <configurations><br class="xooki-br"/> <conf name="api" description="only provide filter framework API"/><br class="xooki-br"/> <conf name="homemade-impl" extends="api" description="provide a home made implementation of our api"/><br class="xooki-br"/> <conf name="cc-impl" extends="api" description="provide an implementation that use apache common collection framework"/><br class="xooki-br"/> <conf name="test" extends="cc-impl" visibility="private" description="for testing our framework"/><br class="xooki-br"/> </configurations><br class="xooki-br"/> <publications><br class="xooki-br"/> <artifact name="filter-api" type="jar" conf="api" ext="jar"/><br class="xooki-br"/> <artifact name="filter-hmimpl" type="jar" conf="homemade-impl" ext="jar"/><br class
="xooki-br"/> <artifact name="filter-ccimpl" type="jar" conf="cc-impl" ext="jar"/> <br class="xooki-br"/> </publications><br class="xooki-br"/> <dependencies><br class="xooki-br"/> <dependency org="commons-collections" name="commons-collections" rev="3.1" conf="cc-impl->default"/><br class="xooki-br"/> <dependency org="junit" name="junit" rev="3.8" conf="test->default"/><br class="xooki-br"/> </dependencies><br class="xooki-br"/></ivy-module>
+</pre>
+</div>
+<h2>Explanation</h2>
[... 5347 lines stripped ...]