You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by xa...@apache.org on 2008/01/03 17:21:07 UTC
svn commit: r608545 [2/5] - in /ant/ivy/site/target:
history/latest-milestone/book.html history/latest-milestone/index.html
history/trunk/book.html history/trunk/index.html style/color.css
style/print-style.css style/shell.css style/style.css
Added: ant/ivy/site/target/history/latest-milestone/book.html
URL: http://svn.apache.org/viewvc/ant/ivy/site/target/history/latest-milestone/book.html?rev=608545&view=auto
==============================================================================
--- ant/ivy/site/target/history/latest-milestone/book.html (added)
+++ ant/ivy/site/target/history/latest-milestone/book.html Thu Jan 3 08:21:05 2008
@@ -0,0 +1,4803 @@
+<!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.0.0-beta1) | Ivy</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://incubator.apache.org/"
+ title="Home"><img src="../../images/apache-incubator-logo.png" alt="Apache Incubator"
+ 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.0.0-beta1)</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 <a href="../../license.html">Apache License</a>.<br class="xooki-br"/><br class="xooki-br"/>Ivy has a lot of powerful <a href="../../features.html">Features</a>, 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 let you get dependencies of your dependencies, transitively. In order to address this problematic ivy needs to find metadata about your modules, usually in an <a href="ivyfile.html">ivy file</a>. To find these 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 <a href="../../mailing-lists.html">Mailing lists</a>.<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 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 svn. This documentation uses <a href="http://xooki.sourceforge.net/">xooki</a> as documentation engine, so you can very easily <a href="../../get-involved.html">edit it and submit patches</a> when you browse it from source.<br class="xooki-br"/><br class="xooki-br"/>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.<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 Ivy <a href="../../features.html">features</a>. <br class="xooki-br"/>Read our <a href="../../faq.html">FAQ</a>.<br class="xooki-br"/>Ask for help on our <a href="../../mailing-lists.html">mailing lists</a>.<br class="xooki-br"/>Report bug or feature request in our <a href="../../issues.html">issue tracking system</a>.<br class="xooki-br"/>Check <a href="../../links.html">external tools and resources</a>.<br class="xooki-br"/><br class="xooki-br"/><h1>Overview</h1>
+This documentation is decomposed in 3 main parts:
+<ul>
+ <li><a href="../../history/latest-milestone/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="../../history/latest-milestone/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 give an overview on 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 configuration, ivy files, and ivy use (especially with ant).<br class="xooki-br"/> <li><a href="../../history/latest-milestone/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"/><h2>Announcement</h2>
+<pre>
+Dec 13 2007 - The Apache Ivy project is please to announce its<br class="xooki-br"/>2.0.0 beta 1 release, a new step on the road toward 2.0 final.<br class="xooki-br"/><br class="xooki-br"/>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"/>Apache Ivy has recently graduated from the Apache Incubator as a<br class="xooki-br"/>subproject of Apache Ant, as such this is its first release as an<br class="xooki-br"/>official Apache project.<br class="xooki-br"/><br class="xooki-br"/>The status of this version is a beta, meaning that we encourage<br class="xooki-br"/>users to try it out. This version is already providing a good stability and<br class="xooki-br"/>robustness. API and features are still subject to change though.<br class="xooki-br"/><br class="xooki-br"/>K
ey features of the 2.0.0-beta1 release are<br class="xooki-br"/>* enhanced Maven2 compatibility<br class="xooki-br"/>* improved concurrency support with cache locking and atomic publish<br class="xooki-br"/>* all tutorials have been reviewed to be in sync with 2.0 changes<br class="xooki-br"/>* numerous bug fixes as documented in Jira and in the release notes<br class="xooki-br"/><br class="xooki-br"/>Issues should be reported to:<br class="xooki-br"/><a href="https://issues.apache.org/jira/browse/IVY">https://issues.apache.org/jira/browse/IVY</a><br class="xooki-br"/><br class="xooki-br"/>Download the 2.0.0-beta1 release files 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"/>More information can be found on the Ivy website:<br class="xooki-br"/><a href="http://ant.apache.org/ivy/">http://ant.apache.org/ivy/</a><br class="xooki-br"/><br class="xooki-br"/>Regards,<br
class="xooki-br"/>Xavier Hanin (2.0.0-beta1 release mgr)
+</pre>
+
+<h2>Release Notes</h2>
+CONTENTS<br class="xooki-br"/>1. What is Apache Ivy?<br class="xooki-br"/>2. Status of this release<br class="xooki-br"/>3. Major Changes in this Release<br class="xooki-br"/>4. Migrating from Jayasoft Ivy to Apache Ivy<br class="xooki-br"/>5. How to Get Involved<br class="xooki-br"/>6. How to Report Issues<br class="xooki-br"/>7. Committers and Contributors for this release<br class="xooki-br"/>8. List of Changes in this Release <br class="xooki-br"/> <br class="xooki-br"/> <br class="xooki-br"/><h3>1. What is Apache Ivy?</h3>
+
+Apache Ivy is a tool for managing (recording, tracking, resolving and reporting) <br class="xooki-br"/>project dependencies. <br class="xooki-br"/>It is characterized by the following:<br class="xooki-br"/><br class="xooki-br"/> 1. flexibility and configurability <br class="xooki-br"/> Apache Ivy is essentially process agnostic and is not tied to any <br class="xooki-br"/> methodology or structure. <br class="xooki-br"/> Instead it provides the necessary flexibility and configurability <br class="xooki-br"/> to be adapted to a broad range of dependency management and build <br class="xooki-br"/> processes.<br class="xooki-br"/> 2. tight integration with Apache Ant<br class="xooki-br"/> while available as a standalone tool, Apache Ivy works particularly well <br class="xooki-br"/> with Apache Ant providing a number of powerful Ant tasks ranging <br class="xooki-br"/> from dependency resolution to dependency reporting and publication.<br cla
ss="xooki-br"/><br class="xooki-br"/><h3>2. Status of this release </h3>
+
+This is the first release of Ivy since it has graduated as a sub project of Apache Ant. <br class="xooki-br"/>As a beta version, we encourage the use of this version for testing and validation.<br class="xooki-br"/>Still API and features are still likely to change until final 2.0.0 version. <br class="xooki-br"/><br class="xooki-br"/>The current production quality version is still 1.4.1, which has not been produced <br class="xooki-br"/>within the Apache Software Foundation.<br class="xooki-br"/><br class="xooki-br"/><h3>3. Major Changes in this Release</h3>
+
+This section describes what has changed between version 1.4.1 and this version of Apache Ivy.<br class="xooki-br"/><br class="xooki-br"/>This new version of Apache Ivy is almost fully compatible with previous versions as long as you do not use custom plugins: Ivy API has changed, but not its behavior.<br class="xooki-br"/><br class="xooki-br"/>Some tasks and configuration elements have been renamed, but the old versions<br class="xooki-br"/>are still available, they are only deprecated (you will see deprecated warnings). <br class="xooki-br"/><br class="xooki-br"/><h4>3.1. Java Package Name Changes</h4>
+
+All of the Ivy Java package names have changed in Apache Ivy. They now start <br class="xooki-br"/>with org.apache rather than fr.jayasoft. There have been other changes as well. <br class="xooki-br"/>Important refactorings have done on the source code to ease the understanding<br class="xooki-br"/>of Ivy internal architecture by new developers.<br class="xooki-br"/><br class="xooki-br"/>A class named org.apache.ivy.Ivy14 is provided with an API compatible with the<br class="xooki-br"/>fr.jayasoft.Ivy class of Ivy 1.4.1, to ease migration to this new version.<br class="xooki-br"/><br class="xooki-br"/><h4>3.2. Configuration replaced by Settings</h4>
+
+Configuration used to have two meanings in prior Ivy versions, causing some confusion with new users.<br class="xooki-br"/>To avoid this confusion, Apache Ivy calls settings instead of configuration the files used to customize Ivy. Configuration is still used for module configurations.<br class="xooki-br"/><br class="xooki-br"/>Besides the changes in the documentation, this renaming also imply a modification in settings files, which now use ivysettings as root element instead of ivyconf, and settings instead of conf element to define top level defaults (such as defaultCache, ...).<br class="xooki-br"/>Previous names have been deprecated, so previous settings files can still be used, but you will see a deprecation warning.<br class="xooki-br"/><br class="xooki-br"/><h4>3.3. Review of settings loading</h4>
+
+This new Ivy version experience with a new way of loading the settings. The configure task is deprecated, and replaced by a settings datatype. By using the settings datatype, you can easily use several settings inside one Ant build script, and use a scope to tell Ivy which settings to use when calling a task which requires some settings.<br class="xooki-br"/><br class="xooki-br"/>This is still an experiment though, so feedback is very welcome in the mailing lists.<br class="xooki-br"/><br class="xooki-br"/><h4>3.4. Public resolver in default settings is now ibiblio in m2 compatible mode</h4>
+
+In previous versions Ivy used to use the ivyrep resolver as default public resolver, but ivyrep is no longer maintained, while maven 2 repository on ibiblio is growing rapidly.<br class="xooki-br"/><br class="xooki-br"/>Since Ivy is compatible with maven 2 repository, defaulting to the ibiblio maven 2 repository makes more sense.<br class="xooki-br"/><br class="xooki-br"/>If you have any issue of backward compatibility with these new settings, you can simply set the following ant property before loading the settings (implicitly or explicitly):<br class="xooki-br"/>ivy.14.compatible=true<br class="xooki-br"/><br class="xooki-br"/><h4>3.5. Relative paths resolution</h4>
+
+Relative paths resolution in Ivy used to be resolved against the current directory. <br class="xooki-br"/>Some work is in progress in this area, currently relative path resolution for the inclusion of configuration files in Ivy files has been modified to work relative to the Ivy file in which the configurations are included.<br class="xooki-br"/><br class="xooki-br"/>This may break your dependency resolution if you used to use relative paths for configuration file inclusion.<br class="xooki-br"/><br class="xooki-br"/><h4>3.6 Ivyrep ivyroot attribute is now mandatory</h4>
+
+If you still use the ivyrep resolver, you will need to provide an ivyroot.<br class="xooki-br"/>To restore the previous behavior, use ivyroot="<a href="http://ivyrep.jayasoft.org/">http://ivyrep.jayasoft.org/</a>".<br class="xooki-br"/><br class="xooki-br"/>Since Ivyrep is not maintained anymore, we recommend moving away from this repository anyway.<br class="xooki-br"/><br class="xooki-br"/><h3>4. Migrating from Jayasoft Ivy to Apache Ivy</h3>
+
+Apache Ivy is fully compatible with Jayasoft Ivy as long as you do not use <br class="xooki-br"/>custom plugins.<br class="xooki-br"/>This means that you can use Apache Ivy as a drop in replacement of Jayasoft Ivy.<br class="xooki-br"/><br class="xooki-br"/>However due to the the renaming of configuration files to settings files, we<br class="xooki-br"/>strongly suggest to update your configuration files:<br class="xooki-br"/>- rename the files called ivyconf*.xml in ivysettings*.xml<br class="xooki-br"/>- rename 'ivyconf' element in 'ivysettings'<br class="xooki-br"/>- rename 'conf' element of those settings file in 'settings'<br class="xooki-br"/><br class="xooki-br"/>We also suggest using the new org.apache.ivy.ant package name for the antlib declaration.<br class="xooki-br"/><br class="xooki-br"/>Migrating custom plugins can be done by using the org.apache.ivy.Ivy14 class<br class="xooki-br"/>instead of fr.jayasoft.ivy.Ivy, and reorganizing your imports to reflect the <b
r class="xooki-br"/>changes in the package names.<br class="xooki-br"/><br class="xooki-br"/><h3>5. How to Get Involved</h3>
+
+The Apache Ivy project really needs and appreciates any contributions, <br class="xooki-br"/>including documentation help, source code and feedback. If you are interested<br class="xooki-br"/>in contributing, please visit <a href="http://ant.apache.org/ivy/get-involved.html">http://ant.apache.org/ivy/get-involved.html</a>.<br class="xooki-br"/><br class="xooki-br"/><h3>6. How to Report Issues</h3>
+
+The Apache Ivy project uses JIRA for issue tracking. Please report any <br class="xooki-br"/>issues you find at <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"/><h3>7. Committers and Contributors for this Release</h3>
+
+Here is the list of people who have contributed source code and documentation<br class="xooki-br"/>to this release. Many thanks to all of them, and also to the whole Ivy community<br class="xooki-br"/>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!<br class="xooki-br"/><h4>Committers</h4>
+ Maarten Coene<br class="xooki-br"/> Xavier Hanin<br class="xooki-br"/> Gilles Scokart<br class="xooki-br"/><h4>Contributors</h4>
+ Jim Bonanno<br class="xooki-br"/> Jacob Grydholt Jensen<br class="xooki-br"/> Matthias Kilian<br class="xooki-br"/> Nicolas Lalevée<br class="xooki-br"/> Geoff Reedy<br class="xooki-br"/> Jason Trump<br class="xooki-br"/> Tjeerd Verhagen<br class="xooki-br"/> John Williams<br class="xooki-br"/> Jing Xue<br class="xooki-br"/><br class="xooki-br"/>Since this is our first release as a subproject of Ant, we'd also like to take this opportunity to thank the Apache Ant project for accepting Ivy as a subproject, the Apache Incubator community for their guidance to behave the "Apache way", and our mentors Antoine Levy-Lambert, Stephane Bailliez, Steve Loughran and Stefan Bodewig for their precious time and help during the incubation process.<br class="xooki-br"/> <br class="xooki-br"/><h3>8. List of Changes in this Release</h3>
+
+For a full release history of Ivy see the file CHANGES.txt<br class="xooki-br"/><br class="xooki-br"/>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.0.0-alpha-2-incubating:<br class="xooki-br"/>- NEW: Share cache with locking (<a href="http://issues.apache.org/jira/browse/IVY-654">IVY-654</a>)<br class="xooki-br"/>- NEW: support atomic publish operation (<a href="http://issues.apache.org/jira/browse/IVY-492">IVY-492</a>) (with contribution from Geoff Reedy)<br class="xooki-br"/>- NEW: latest compatible conflict manager (<a href="http://issues.apache.org/jira/browse/IVY-648">IVY-648</a>)<br class="xooki-br"/>- NEW: Add a task/code to create M2 POM files from Ivy configurations (<a href="http://issues.apache.org/jira/browse/IVY-416">IVY-416</a>)<br class="xooki-br"/>- NEW
: [Build] Publish the ivy sources (<a href="http://issues.apache.org/jira/browse/IVY-646">IVY-646</a>) (thanks to Nicolas Lalevée)<br class="xooki-br"/><br class="xooki-br"/>- IMPROVEMENT: Ease performance auditing (<a href="http://issues.apache.org/jira/browse/IVY-655">IVY-655</a>)<br class="xooki-br"/>- IMPROVEMENT: Maven Dependency Management is not used to determine artifact version (<a href="http://issues.apache.org/jira/browse/IVY-616">IVY-616</a>) (thanks to Jim Bonanno)<br class="xooki-br"/>- IMPROVEMENT: split the cache into an downloaded artifacts cache and a metadata cache (<a href="http://issues.apache.org/jira/browse/IVY-628">IVY-628</a>)<br class="xooki-br"/>- IMPROVEMENT: add publish triggers to event system (<a href="http://issues.apache.org/jira/browse/IVY-650">IVY-650</a>) (thanks to Jason Trump)<br class="xooki-br"/>- IMPROVEMENT: Only display unique circular dependencies during Resolve (<a href="http://issues.apache.org/jira/browse/IVY-653">IVY-653</a> <
a href="http://issues.apache.org/jira/browse/IVY-514">IVY-514</a>) (with contribution from John Williams)<br class="xooki-br"/>- IMPROVEMENT: Adding option 'cp', which makes it possible for main to be loaded from file (<a href="http://issues.apache.org/jira/browse/IVY-543">IVY-543</a>) (thanks to Tjeerd Verhagen)<br class="xooki-br"/>- IMPROVEMENT: BasicURLHandler should use method=head for getURLInfo (<a href="http://issues.apache.org/jira/browse/IVY-611">IVY-611</a>) (thanks to Jim Bonanno)<br class="xooki-br"/>- IMPROVEMENT: artifactproperty should not overwrite the existing properties (<a href="http://issues.apache.org/jira/browse/IVY-587">IVY-587</a>)<br class="xooki-br"/>- IMPROVEMENT: Support *(private) and *(public) in the confs parameter of the resolve (<a href="http://issues.apache.org/jira/browse/IVY-588">IVY-588</a>)<br class="xooki-br"/>- IMPROVEMENT: replace * by *(public) when resolving inline (<a href="http://issues.apache.org/jira/browse/IVY-589">IVY-589</a>
)<br class="xooki-br"/>- IMPROVEMENT: ivy html reports now refers <a href="http://ant.apache.org">http://ant.apache.org</a> (partial <a href="http://issues.apache.org/jira/browse/IVY-414">IVY-414</a>)<br class="xooki-br"/>- IMPROVEMENT: Improvements on hello ivy example (<a href="http://issues.apache.org/jira/browse/IVY-626">IVY-626</a>) (with contribution from Jacob Grydholt Jensen)<br class="xooki-br"/>- IMPROVEMENT: Make the root attribute in the ivyrep resolver mandatory (<a href="http://issues.apache.org/jira/browse/IVY-625">IVY-625</a>)<br class="xooki-br"/>- IMPROVEMENT: New text representation for main module metadata concepts (<a href="http://issues.apache.org/jira/browse/IVY-649">IVY-649</a>)<br class="xooki-br"/><br class="xooki-br"/>- FIX: m2 incompatibility - IVY does not recognize property section (<a href="http://issues.apache.org/jira/browse/IVY-637">IVY-637</a>)<br class="xooki-br"/>- FIX: m2 incompatibility - IVY does not recognize parent pom (<a href="http
://issues.apache.org/jira/browse/IVY-636">IVY-636</a>)<br class="xooki-br"/>- FIX: Attempt to download a file with & in its name causes SAXParseException in Ivy (<a href="http://issues.apache.org/jira/browse/IVY-635">IVY-635</a>)<br class="xooki-br"/>- FIX: Bad IvyContext scope causing memory leak and bad handling of subproject builds (<a href="http://issues.apache.org/jira/browse/IVY-639">IVY-639</a>)<br class="xooki-br"/>- FIX: Resolution failure when no ivy.xml file present (<a href="http://issues.apache.org/jira/browse/IVY-630">IVY-630</a>)<br class="xooki-br"/>- FIX: ${parent.version} property is not recognized in maven2 pom (<a href="http://issues.apache.org/jira/browse/IVY-620">IVY-620</a>)<br class="xooki-br"/>- FIX: Handle relocation tag in maven 2 pom (<a href="http://issues.apache.org/jira/browse/IVY-586">IVY-586</a>)<br class="xooki-br"/>- FIX: Ivy doesn't work with Ant 1.6.2 (<a href="http://issues.apache.org/jira/browse/IVY-614">IVY-614</a>)<br class="xooki-br"
/>- FIX: EmptyStackException when upgrading from 1.4 to 2.0 (<a href="http://issues.apache.org/jira/browse/IVY-610">IVY-610</a>)<br class="xooki-br"/>- FIX: Ivy:retrieve fails through proxy server (<a href="http://issues.apache.org/jira/browse/IVY-529">IVY-529</a>)<br class="xooki-br"/>- FIX: java.lang.IllegalArgumentException: Invalid uri when working with version ranges (<a href="http://issues.apache.org/jira/browse/IVY-390">IVY-390</a>)<br class="xooki-br"/>- FIX: Ivy settings include -tag url attribute does not work correctly (<a href="http://issues.apache.org/jira/browse/IVY-601">IVY-601</a>)<br class="xooki-br"/>- FIX: Static revision replacement is not working when a dynamic revision is evicted by a transitive dependency (<a href="http://issues.apache.org/jira/browse/IVY-603">IVY-603</a>) (with contribution from Matthias Kilian)<br class="xooki-br"/>- FIX: NullPointerException whilst resolving transitive dependencies (<a href="http://issues.apache.org/jira/browse/IVY-
590">IVY-590</a>)<br class="xooki-br"/>- FIX: cachepath based on a resolve done in a previous build broken (<a href="http://issues.apache.org/jira/browse/IVY-583">IVY-583</a>)<br class="xooki-br"/>- FIX: Resolving dynamic version fails when using multiple patterns if only one pattern find a revision and others don't (<a href="http://issues.apache.org/jira/browse/IVY-602">IVY-602</a>)<br class="xooki-br"/>- FIX: Invalid character in IvyRetrieveTest causing most tests to fail (<a href="http://issues.apache.org/jira/browse/IVY-604">IVY-604</a>)<br class="xooki-br"/>- FIX: ivy:settings and ivy:retrieve with explicit id causes unwarranted DEPRECATED warning (thanks to Jacob Grydholt Jensen)<br class="xooki-br"/><br class="xooki-br"/>- REFACTORING: Extract a settings interface for the different engines<br class="xooki-br"/><br class="xooki-br"/>- TASK: Review all tutorials to make sure they are in sync with 2.0 (<a href="http://issues.apache.org/jira/browse/IVY-591">IVY-591</a>) (
with contribution from Jing Xue)<br class="xooki-br"/>- TASK: Satisfy the US export control laws for software "specially designed" to use cryptography. (<a href="http://issues.apache.org/jira/browse/IVY-593">IVY-593</a>)<br class="xooki-br"/> <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 <a href="../../features.html">features</a>.<br class="xooki-br"/><br class="xooki-br"/>Here is the very first tutorial, it doesn't even require to install Ivy, and should not take more than 30 seconds if you already have ant and a jdk properly installed:
+<ul>
+<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>
+</ul>
+If you have any trouble, check the <a href="../../faq.html">FAQ</a>, it may be related to your internet connection (proxy anyone?).<br class="xooki-br"/><br class="xooki-br"/>OK, you've seen how easy it is to make your first step with ivy? Go ahead with the other tutorials, but before make sure you have properly <a href="install.html">installed</a> ivy and downloaded the tutorials sources (included in all ivy distributions, in the <a href="https://svn.apache.org/repos/asf/ant/ivy/core/trunk/src/example">src/example</a> 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>
+guide you through your very first steps with ivy.
+<li><a href="../../history/latest-milestone/tutorial/defaultconf.html">Adjusting default settings</a></li>
+give you a better understanding of the default settings and show you how to customize them to your needs.
+<li><a href="tutorial/multiple.html">Multiple Resolvers</a></li>
+teach you how to configure Ivy to find its dependencies in multiple places.
+<li><a href="tutorial/dual.html">Dual Resolver</a></li>
+help you configure ivy to find ivy files in one place and artifacts in another.
+<li><a href="../../history/latest-milestone/tutorial/dependence.html">Project dependencies</a>Project Dependencies</a></li>
+a very first step toward using Ivy in a multi project environment.
+<li><a href="../../history/latest-milestone/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 Configurations</a></li>
+show how to use configurations in ivy file to define set of artifacts.
+<li><a href="tutorial/build-repository.html">Building a repository</a></li>
+show 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 example, we will see one of the easiest way 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="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 use. <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.<br class="xooki-br"/><br class="xooki-br"/>Finally, the dependencies section let 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 attribute to define the organization and module name of the dependencies we need. The rev attribute is used to specify the revision of the module you depend on. <br class="xooki-br"/><br class="xooki-br"/>To know what to put in these attri
butes, you need to know the exact information for the libraries you depend on. Ivy uses the maven 2 repository by default. 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="../../history/latest-milestone/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="../../history/latest-milestone/ivyfile.html">I
vy files reference documentation</a>.<br class="xooki-br"/><h1>The build.xml file</h1>
+The corresponding build file contains a set of targets, allowing 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="../../history/latest-milestone/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="../../history/latest-milestone/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="../../history/latest-milestone/use/retrieve.html">retrieve</a> task. With no attributes, it will use default settings and look for a file named ivy.xml for dependency definition. 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 "resolve" target and call the <a href="../../history/latest-milestone/use/retrieve.html">retrieve</a> task. This may sound confusing, actually the retrieve task performs a <a href="../../history/lat
est-milestone/use/resolve.html">resolve</a> (which resolves dependencies and downloads them to a cache) followed by a retrieve (a copy of those file in a local project directory). Check the <a href="../../history/latest-milestone/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 hello-ivy example directory.<br class="xooki-br"/>Then, at the command prompt, run 'ant':
+<div class="shell"><pre>
+I:\hello-ivy>ant<br class="xooki-br"/>Buildfile: src\example\hello-ivy\build.xml
+
+resolve:
+[ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071104204849 - 20071104204849 :: http://ant.apache.org/ivy/ ::
+[ivy:retrieve] No ivy:settings found for the default reference 'ivy.instance'. A default instance will be used
+[ivy:retrieve] no settings file found, using default...
+[ivy:retrieve] :: loading settings :: url = jar:file:/c:/dev/data/opensource_workspace/ivy/build/artifact/ivy-core.jar!/org/apache/ivy/core/settings/ivysettings.xml
+[ivy:retrieve] :: resolving dependencies :: [ org.apache | hello-ivy | working@BEN-ScokartG ]
+[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.jar ...
+[ivy:retrieve] .......................................................................................
+[ivy:retrieve] .............................. (165kB)
+[ivy:retrieve] .. (0kB)
+[ivy:retrieve] [SUCCESSFUL ] [ commons-lang | commons-lang | 2.0 ]/commons-lang.jar[jar] (3335ms)
+[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[jar] (2053ms)
+[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[jar] (1933ms)
+[ivy:retrieve] :: resolution report ::
+[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 | 0 | 1 || 3 | 3 |
+ ---------------------------------------------------------------------
+[ivy:retrieve] :: retrieving :: [ org.apache | hello-ivy ]
+[ivy:retrieve] confs: [default]
+[ivy:retrieve] 3 artifacts copied, 0 already retrieved
+
+run:
+ [java] standard message : hello ivy !
+ [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !
+
+BUILD SUCCESSFUL
+Total time: 14 seconds
+
+</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="../../history/latest-milestone/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>I:\hello-ivy>ant<br class="xooki-br"/>Buildfile: src\example\hello-ivy\build.xml
+
+resolve:
+[ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071104204849 - 20071104204849 :: http://ant.apache.org/ivy/ ::
+[ivy:retrieve] No ivy:settings found for the default reference 'ivy.instance'. A default instance will be used
+[ivy:retrieve] no settings file found, using default...
+[ivy:retrieve] :: loading settings :: url = jar:file:/c:/dev/data/opensource_workspace/ivy/build/artifact/ivy-core.jar!/org/apache/ivy/core/settings/ivysettings.xml
+[ivy:retrieve] :: resolving dependencies :: [ org.apache | hello-ivy | working@BEN-ScokartG ]
+[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 ::
+[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 || 3 | 0 |
+ ---------------------------------------------------------------------
+[ivy:retrieve] :: retrieving :: [ org.apache | hello-ivy ]
+[ivy:retrieve] confs: [default]
+[ivy:retrieve] 0 artifacts copied, 3 already retrieved
+
+run:
+ [java] standard message : hello ivy !
+ [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !
+
+BUILD SUCCESSFUL
+Total time: 3 seconds
+
+</pre></div>
+Great! the cache was used, 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="../../history/latest-milestone/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="../../history/latest-milestone/reference.html
">reference documentation</a>, and especially the introduction material which gives a good overview of Ivy. The <a href="../../history/latest-milestone/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 common environment. This tutorial, which is close to a reference documentation, explains what are those default settings 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 tutorial related to settings (like <a href="../../history/latest-milestone/tutorial/multiple.html">Multiple Resolvers</a> and <a href="../../history/latest-milestone/tutorial/dual.html">Dual Resolver</a
>) or the <a href="../configuration.html">settings</a> reference documentation.<br class="xooki-br"/><br class="xooki-br"/><h1>Concept</h1>
+This default settings mainly consist of 3 kind 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 member 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 local and shared repository is not very important, but there are some things to know to distinguish them.<br class="xooki-br"/><br class="xooki-br"/>Now let's describe each of these repositories concept in more details. We will describe how they are setup 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 of 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 foo in revision latest.integration, then if a revision of foo 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 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 someo
ne else publish a new revision of foo 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 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 private modules for instance, and it's also a place where you can put modules not available in the public repository (sun jars, for instance), or simply not accurate (bad or incomplete module descriptors for instance).<br class="xooki-br"/><br class="xooki-br"/>Note that modules can be split across the shared repository and the public one: you can have the module descriptor in the shared repository and the artifacts in the public one, for instance.<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 uses the same root in your filesystem. Referenced as ${ivy.default.ivy.user.dir}, this is by default the directory .ivy2 in your user home.<br class="xooki-br"/><br class="xooki-br"/>Note that several things can be done by setting ivy variable. To set them without defining your own ivysettings.xml 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 instance:
+<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>
+
+Now we will show how to override default values for the different kind of repositories, note that you can find what are these default values below in the detail of the default settings.<br class="xooki-br"/><h2>Local</h2>
+By default, the local repository lies in ${ivy.default.ivy.user.dir}/local. This is usually a good place, but you may want to modify it however. No problem, you just have to set the following ivy variable to the directory you want to use: <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 ${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 <pre>ivy.shared.default.root</pre> variable to specify in a new directory. Moreover, you can also configure the layout with variables similar to the one 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="../../history/latest-milestone/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 has 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="xo
oki-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 public repository? What if ... <br class="xooki-br"/><br class="xooki-br"/>No problem, Ivy is very flexible and be configured with very 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 ivysettings.xml 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 benefit of the rest easily. For example, if you want to define your own public resolver, you will just have to configure ivy with an ivysettings like that:
+<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 ivysettings-public inclusion has changed to include a home made public resolver. Note also that this can be used like that thanks to the fact that ${ivy.default.settings.dir} is a variable which is always set to the place where ivy 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>
+
+Here you are, you have enough clues to configure that the way you want... check the <a href="../configuration.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 example is an illustration of how modules can be retrieved by multiple resolvers. Using multiple resolvers can be useful in many contexts, here are some examples:
+<ul>
+<li>separate integration builds from releases</li>
+<li>use 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 one compound resolver called a chain resolver.<br class="xooki-br"/><br class="xooki-br"/>In our example, we will simply show how to use two resolvers, one on a local repository and one using 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 commons-lang and a little test library (sources are included in jar file). The test library is used by the project to uppercase a string, and commons-lang is used to capitalize the same string.<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 expect, the ivy file declares to be dependent on the two libraries that the project use: commons-lang and test. Note that we don't specify the organisation for the dependency test, in this case Ivy assumes the same org as the declaring module, ie org.apache in this case.<br class="xooki-br"/><br class="xooki-br"/><h2>the <b>ivy settings</b></h2>
+The ivy settings is made in the settings directory it contains only one file: ivysettings.xml.<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 is used, the name of the resolver to use by default.<br class="xooki-br"/><br class="xooki-br"/><h2>the <b>resolvers</b> tag</h2>
+Under this tag, we can find the description of the resolvers that ivy will use. In our example, we have only one resolver, called "chain-example", which is quite special as it defines a list (a chain) of resolvers.<br class="xooki-br"/>The resolvers put in the chain are :
+<ul>
+ <li>libraries : it is a file resolver. This one is configured to look for artifacts in the "repository" sub directory of the directory that contains the ivysettings.xml file.</li>
+ <li>ibiblio : this resolver is a special one. It looks in the ibiblio maven repository to retrieve the libraries.</li>
+</ul>
+
+That's it, we have 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 it 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 Ivy cache is something you can do with no fear (except performance): it's only a cache, everything can be (and should be) obtained again from repositories. For those coming from maven 2 land, this may sounds strange, but remember that in Ivy, the cache is not a local repository, things are kept cleanly isolated.
+</div>
+</div>
+<div class="step">
+<h2>step 3: run the project</h2>
+Go to chainedresolvers-project directory. And simply run <b>ant</b>.<br class="xooki-br"/>
+<div class="shell"><pre>I:\chained-resolvers\chainedresolvers-project>ant<br class="xooki-br"/>Buildfile: src\example\chained-resolvers\chainedresolvers-project\build.xml
+
+resolve:
+[ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071104204849 - 20071104204849 :: http://ant.apache.org/ivy/ ::
+[ivy:retrieve] :: loading settings :: file = C:\dev\data\opensource_workspace\ivy\src\example\chained-resolvers\config\ivysettings.xml
+[ivy:retrieve] :: resolving dependencies :: [ org.apache | chained-resolvers | working@BEN-ScokartG ]
+[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://www.ibiblio.org/maven/commons-lang/jars/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[jar] (5928ms)
+[ivy:retrieve] downloading C:\dev\data\opensource_workspace\ivy\src\example\chained-resolvers\config\repository\test-1.0.jar ...
+[ivy:retrieve] .. (1kB)
+[ivy:retrieve] [SUCCESSFUL ] [ org.apache | test | 1.0 ]/test.jar[jar] (10ms)
+[ivy:retrieve] :: resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | default | 2 | 2 | 0 | 0 || 2 | 2 |
+ ---------------------------------------------------------------------
+[ivy:retrieve] :: retrieving :: [ org.apache | chained-resolvers ]
+[ivy:retrieve] confs: [default]
+[ivy:retrieve] 2 artifacts copied, 0 already retrieved
+
+run:
+ [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\chained-resolvers\chainedresolvers-project\build
+ [javac] Compiling 1 source file to C:\dev\data\opensource_workspace\ivy\src\example\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: 12 seconds
+
+</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"/>The run target succeed in using both commons-lang.jar comming from 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 to see how to make a basic setting of two resolvers in a chain. The <a href="../../history/latest-milestone/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"/>The most interesting things to know that you can try out from this basic example are:
+<ul>
+<li>a chain is not limited to two nested resolvers, you can use the number you want</li>
+<li>by setting returnFirst="true", you can have a chain which stops as soon as it has found a result for a given module</li>
+<li>by setting dual="true", the full chain will be used both for module descriptors and artifacts, while with dual="false", 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 it may happen that your module descriptors (Ivy files, maven pom, ...) are located at one place and module artifacts (jars, ...) at another place.<br class="xooki-br"/><br class="xooki-br"/>Dual Resolver is used to address this kind of need, and this tutorial will show how to use it. <br class="xooki-br"/><br class="xooki-br"/><h1>project description</h1>
+Let's have a look at the src/example/dual 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: example.Hello<br class="xooki-br"/>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 <b>ivy.xml</b> 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, it's the philosophy of ivy 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 is made in the settings directory; it contains only one file: ivysettings.xml.<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 configure one resolver, the default one, which is a dual resolver. This dual resolver has two sub resolvers: the first is what is called the "ivy" 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 exactly has two sub resolvers in this given order.<br class="xooki-br"/>The metadata resolver, here a filesystem one, is used only to find module descriptors, in this case Ivy files. The settings given in this resolver says that all ivy files are in the same directory, named like that: [module]-ivy-[revision].xml. If we check the repository directory, we can confirm that it contains a file named commons-httpclient-ivy-2.0.2.xml. It fulfills the given pattern and will thus be found by this resolver.<br class="xooki-br"/>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 strictly 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 "dual" directory.
+</div>
+<div class="step">
+<h2>step 2 : clean up</h2>
+On the prompt type : ant<br>
+This will clean up the entire project directory tree (compiled classes and retrieved libs) and ivy cache. <br class="xooki-br"/>You can do it each time you want to clean up this example.
+</div>
+<div class="step">
+<h2>step 3 : run the project</h2>
+Goto project directory. And simply run <b>ant</b>.
+<div class="shell"><pre>
+I:\dual\project>ant<br class="xooki-br"/>Buildfile: src\example\dual\project\build.xml
+
+resolve:
+[ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071104204849 - 20071104204849 :: http://ant.apache.org/ivy/ ::
+[ivy:retrieve] :: loading settings :: file = C:\dev\data\opensource_workspace\ivy\src\example\dual\config\ivysettings.xml
+[ivy:retrieve] :: resolving dependencies :: [ org.apache | hello-ivy | working@BEN-ScokartG ]
+[ivy:retrieve] confs: [default]
+[ivy:retrieve] found [ commons-httpclient | commons-httpclient | 2.0.2 ] in ivys
+[ivy:retrieve] found [ commons-httpclient | commons-logging | 1.0.4 ] in ibiblio
+[ivy:retrieve] found [ commons-lang | commons-lang | 2.0 ] in ibiblio
+[ivy:retrieve] downloading http://www.ibiblio.org/maven/commons-httpclient/jars/commons-httpclient-2.0.2.jar ...
+[ivy:retrieve] ...........................................
+[ivy:retrieve] .................................................................................................
+[ivy:retrieve] ................ (220kB)
+[ivy:retrieve] .. (0kB)
+[ivy:retrieve] [SUCCESSFUL ] [ commons-httpclient | commons-httpclient | 2.0.2 ]/commons-httpclient.jar[jar] (11676ms)
+[ivy:retrieve] downloading http://www.ibiblio.org/maven/commons-lang/jars/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[jar] (7651ms)
+[ivy:retrieve] downloading http://www.ibiblio.org/maven/commons-logging/jars/commons-logging-1.0.4.jar ...
+[ivy:retrieve] ........................... (37kB)
+[ivy:retrieve] .. (0kB)
+[ivy:retrieve] [SUCCESSFUL ] [ commons-httpclient | commons-logging | 1.0.4 ]/commons-logging.jar[jar] (9724ms)
+[ivy:retrieve] :: resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | default | 3 | 3 | 0 | 0 || 3 | 3 |
+ ---------------------------------------------------------------------
+[ivy:retrieve] :: retrieving :: [ org.apache | hello-ivy ]
+[ivy:retrieve] confs: [default]
+[ivy:retrieve] 3 artifacts copied, 0 already retrieved
+
+run:
+ [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\dual\project\build
+ [javac] Compiling 1 source file to C:\dev\data\opensource_workspace\ivy\src\example\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: 37 seconds
+
+</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 repository 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 worked well, ivy file has been found in the repository directory and 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 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 can lead to very flexible settings addressing most needs.<br class="xooki-br"/><br class="xooki-br"/>For full details about the dual resolver, have a look at the corresponding <a href="../../history/latest-milestone/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 example is an illustration of dependency between two projects.<br class="xooki-br"/><br class="xooki-br"/>The depender project declares that it uses the dependee one. We will illustrate two things:
+<ul>
+ <li>public libraries declared by standalone project will automatically be retrieved by the dependant project</li>
+ <li>the depender project will 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: standalone.Main which provides two services:
+<ul>
+ <li>return the version of the project</li>
+ <li>capitalize a string using org.apache.commons.lang.WordUtils.capitalizeFully</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 dependency file declares only one dependency on apache commons-lang library.<br class="xooki-br"/><h2>depender</h2>
+The project depender is very simple too. It declares only one dependency on the latest version of the dependee project and it contains only one class depending.Main which make 2 things:
+<ul>
+ <li>getting the version of the standalone project throw a call to standalone.Main.getVersion()</li>
+ <li>transform a string throw a call to standalone.Main.capitalizeWords(str)</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="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 is made in the settings directory which contains 2 files:
+<ul>
+ <li>ivysettings.properties: a property file</li>
+ <li>ivysettings.xml: the file containing the settings</li>
+</ul>
+
+Let's have a look at the ivysettings.xml file:
+<pre>
+<ivysettings><br class="xooki-br"/> <properties file="${ivy.settings.dir}/ivysettings.properties"/><br class="xooki-br"/> <settings defaultCache="${ivy.settings.dir}/ivy-cache" defaultResolver="libraries"/><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 only load some properties for the ivy process in the same manner as ant would do it.<br class="xooki-br"/><h2>settings</h2>
+This tag is in charge of initializing some parameters for ivy process. 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. <br class="xooki-br"/>The second parameter, tells ivy to use a resolver called "libraries" as its default resolver. More information can be found in the <a href="../../history/latest-milestone/configuration.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 maven 2 repository, but doesn't use maven poms.<br class="xooki-br"/><h2>modules</h2>
+The modules tag allows to configure which resolver should be used for which module. Here the settings only tells to use the "projects" resolver for all modules having for organisation "org.apache" and for module name "dependee". This actually corresponds to only one module, but a regular expression could be used, or many other kind of expressions (like glob expressions).<br class="xooki-br"/><br class="xooki-br"/>For other modules (i.e. all modules but org.apache#dependee), since there is no special settings, the default resolver will be used: "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 "src/example/dependence" directory.
+</div>
+<div class="step">
+<h2>step 2: clean directory tree</h2>
+On the prompt type: ant<br class="xooki-br"/>This will clean up the entire project directory tree. You can do it each time you want to clean up this example.
+</div>
+<div class="step">
+<h2>step 3: publication of dependee project</h2>
+Go to dependee directory and publish the project
+<div class="shell"><pre>I:\dependee>ant publish<br class="xooki-br"/>Buildfile: src\example\dependence\standalone\build.xml
+
+resolve:
+[ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071104204849 - 20071104204849 :: http://ant.apache.org/ivy/ ::
+[ivy:retrieve] :: loading settings :: file = C:\dev\data\opensource_workspace\ivy\src\example\dependence\config\ivysettings.xml
+[ivy:retrieve] :: resolving dependencies :: [ org.apache | standalone | working@BEN-ScokartG ]
+[ivy:retrieve] confs: [default]
+[ivy:retrieve] found [ commons-lang | commons-lang | 2.0 ] in libraries
+[ivy:retrieve] downloading http://www.ibiblio.org/maven/commons-lang/jars/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[jar] (5388ms)
+[ivy:retrieve] :: resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | default | 1 | 1 | 0 | 0 || 1 | 1 |
+ ---------------------------------------------------------------------
+[ivy:retrieve] :: retrieving :: [ org.apache | standalone ]
+[ivy:retrieve] confs: [default]
+[ivy:retrieve] 1 artifacts copied, 0 already retrieved
+
+compile:
+ [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\dependence\standalone\build\classes
+ [javac] Compiling 1 source file to C:\dev\data\opensource_workspace\ivy\src\example\dependence\standalone\build\classes
+
+jar:
+[propertyfile] Creating new property file: C:\dev\data\opensource_workspace\ivy\src\example\dependence\standalone\build\classes\version.properties
+ [jar] Building jar: C:\dev\data\opensource_workspace\ivy\src\example\dependence\standalone\build\standalone.jar
+
+publish:
+[ivy:publish] :: delivering :: [ org.apache | standalone | working@BEN-ScokartG ] :: 1 :: release :: Sun Nov 04 20:50:24 CET 2007
+[ivy:publish] delivering ivy file to C:\dev\data\opensource_workspace\ivy\src\example\dependence\standalone/build/ivy.xml
+[ivy:publish] :: publishing :: [ org.apache | standalone ]
+[ivy:publish] published standalone to C:\dev\data\opensource_workspace\ivy\src\example\dependence\config/repository/standalone-1.jar
+[ivy:publish] published ivy to C:\dev\data\opensource_workspace\ivy\src\example\dependence\config/repository/standalone-1.xml
+ [echo] project standalone released with version 1
+
+BUILD SUCCESSFUL
+Total time: 11 seconds
+
+</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>
+To give more details on the publish, 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 build/ivy.xml.</li>
+This has been done because by default the publish task not only publishes artifacts but also ivy file. So it has looked to the path where the ivy file to publish should be, using the artifactspattern: ${build.dir}/[artifact].[ext].<br class="xooki-br"/>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.
+<li>the publication of artifact dependee and resolved ivy file to the repository.</li>
+Both are mere copy of files found in the current project, more precisely in the build dir. This is because the artifactspattern has been set to ${build.dir}/[artifact].[ext], so dependee artifact is found in build/dependee.jar and ivy file in build/ivy.xml. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to repository\dependee-1.jar and to repository\dependee-1.xml, 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 ant
+<div class="shell"><pre>I:\depender>ant<br class="xooki-br"/>Buildfile: src\example\dependence\depending\build.xml
+
+clean:
+
+resolve:
+[ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071104204849 - 20071104204849 :: http://ant.apache.org/ivy/ ::
+[ivy:retrieve] :: loading settings :: file = C:\dev\data\opensource_workspace\ivy\src\example\dependence\config\ivysettings.xml
+[ivy:retrieve] :: resolving dependencies :: [ org.apache | depending | working@BEN-ScokartG ]
+[ivy:retrieve] confs: [default]
+[ivy:retrieve] found [ org.apache | standalone | 1 ] in projects
+[ivy:retrieve] [1] [ org.apache | standalone | latest.integration ]
+[ivy:retrieve] found [ commons-lang | commons-lang | 2.0 ] in libraries
+[ivy:retrieve] downloading C:\dev\data\opensource_workspace\ivy\src\example\dependence\config\repository\standalone-1.jar ...
+[ivy:retrieve] .. (1kB)
+[ivy:retrieve] .. (0kB)
+[ivy:retrieve] [SUCCESSFUL ] [ org.apache | standalone | 1 ]/standalone.jar[jar] (20ms)
+[ivy:retrieve] :: resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | default | 2 | 1 | 0 | 0 || 2 | 1 |
+ ---------------------------------------------------------------------
+[ivy:retrieve] :: retrieving :: [ org.apache | depending ]
+[ivy:retrieve] confs: [default]
+[ivy:retrieve] 2 artifacts copied, 0 already retrieved
+
+compile:
+ [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\dependence\depending\build\classes
+ [javac] Compiling 1 source file to C:\dev\data\opensource_workspace\ivy\src\example\dependence\depending\build\classes
+
+run:
+ [java] you are using version 1 of class standalone.Main
+ [java] standard message : i am depending.Main and standalone.Main will do the job for me
+ [java] [standalone.Main] capitalizing string "i am depending.Main and standalone.Main will do the job for me" using org.apache.commons.lang.WordUtils
+ [java] capitalized message : I Am Depending.main And Standalone.main Will Do The Job For Me
+
+BUILD SUCCESSFUL
+Total time: 3 seconds
+
+</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 the 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 artifact version 1 of the project dependee</li>
+ <li>the call to standalone.Main.capitalizeWords(str) succeed, which means that the required library were in the classpath. If you look at the lib directory, you will see that the library commons-lang-2.0.jar was retrieved. This library was declared to be used by the project "dependee", so ivy get it too for the depender project.</li>
+</ul>
+</div>
+<div class="step">
+<h2>step 5: new version of dependee project</h2>
[... 4137 lines stripped ...]