Added: ant/site/ivy/production/history/master/book.html URL: http://svn.apache.org/viewvc/ant/site/ivy/production/history/master/book.html?rev=1829791&view=auto ============================================================================== --- ant/site/ivy/production/history/master/book.html (added) +++ ant/site/ivy/production/history/master/book.html Sun Apr 22 17:19:39 2018 @@ -0,0 +1,20651 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.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 L icense.--><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><meta name="generator" content="Asciidoctor 1.5.4" /><title>Apache Ivy™ Documentation 2.5.0-rc2-local-20180419193918</title><link rel="stylesheet" type="text/css" href="./style/style.css" /><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css" /><script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js" type="text/javascript"></script><script>hljs.initHighlightingOnLoad();</script></head><body id="book"><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-project-logo.svg" alt="Apache Ant" border="0" height="80px" /></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="title">Documentation (2.5.0-rc2-local-20180419193918)</div><div id="main"><div id="content"><div class="sect1"> +<h2 id="_table_of_contents">Table of Contents</h2> +<div class="sectionbody"> +<div class="ulist"> +<ul> +<li> +<p><a href="#release-notes">Release Notes</a></p> +</li> +<li> +<p><a href="#tutorial">Tutorials</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#tutorial_start">Quick Start</a></p> +</li> +<li> +<p><a href="#tutorial_defaultconf">Adjusting default settings</a></p> +</li> +<li> +<p><a href="#tutorial_multiple">Multiple Resolvers</a></p> +</li> +<li> +<p><a href="#tutorial_dual">Dual Resolver</a></p> +</li> +<li> +<p><a href="#tutorial_dependence">Project dependencies</a></p> +</li> +<li> +<p><a href="#tutorial_multiproject">Using Ivy in multiple projects environment</a></p> +</li> +<li> +<p><a href="#tutorial_conf">Using Ivy Module Configurations</a></p> +</li> +<li> +<p><a href="#tutorial_build-repository">Building a repository</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#tutorial_build-repository_basic">Basic repository copy</a></p> +</li> +<li> +<p><a href="#tutorial_build-repository_advanced">Using namespaces</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#moreexamples">More examples</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#reference">Reference</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#intro">Introduction</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#terminology">Terminology</a></p> +</li> +<li> +<p><a href="#concept">Main Concepts</a></p> +</li> +<li> +<p><a href="#textual">Text Conventions</a></p> +</li> +<li> +<p><a href="#principle">How does it work ?</a></p> +</li> +<li> +<p><a href="#bestpractices">Best practices</a></p> +</li> +<li> +<p><a href="#compatibility">Compatibility</a></p> +</li> +<li> +<p><a href="#install">Installation</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#settings">Settings Files</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#settings_property">property</a></p> +</li> +<li> +<p><a href="#settings_properties">properties</a></p> +</li> +<li> +<p><a href="#settings_settings">settings</a></p> +</li> +<li> +<p><a href="#settings_include">include</a></p> +</li> +<li> +<p><a href="#settings_classpath">classpath</a></p> +</li> +<li> +<p><a href="#settings_typedef">typedef</a></p> +</li> +<li> +<p><a href="#settings_credentials">credentials</a></p> +</li> +<li> +<p><a href="#settings_signers">signers</a></p> +</li> +<li> +<p><a href="#settings_lock-strategies">lock-strategies</a></p> +</li> +<li> +<p><a href="#settings_caches">caches</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#settings_caches_cache">cache</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#settings_caches_ttl">ttl</a></p> +</li> +</ul> +</div> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#settings_latest-strategies">latest-strategies</a></p> +</li> +<li> +<p><a href="#settings_parsers">parsers</a></p> +</li> +<li> +<p><a href="#settings_namespaces">namespaces</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#settings_namespace">namespace</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#settings_namespace_rule">rule</a> +<strong><strong></strong></strong> <a href="#settings_namespace_fromtosystem">fromsystem / tosystem</a> +<strong><strong></strong><strong> <a href="#settings_namespace_src">src</a> +</strong><strong></strong></strong> <a href="#settings_namespace_dest">dest</a></p> +</li> +</ul> +</div> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#settings_macrodef">macrodef</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#settings_macrodef_attribute">attribute</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#settings_resolvers">resolvers</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#resolver_ivyrep">IvyRep Resolver</a></p> +</li> +<li> +<p><a href="#resolver_ibiblio">IBiblio Resolver</a></p> +</li> +<li> +<p><a href="#resolver_packager">Packager Resolver</a></p> +</li> +<li> +<p><a href="#resolver_filesystem">File System Resolver</a></p> +</li> +<li> +<p><a href="#resolver_url">URL Resolver</a></p> +</li> +<li> +<p><a href="#resolver_chain">Chain Resolver</a></p> +</li> +<li> +<p><a href="#resolver_dual">Dual Resolver</a></p> +</li> +<li> +<p><a href="#resolver_sftp">SFTP Resolver</a></p> +</li> +<li> +<p><a href="#resolver_ssh">SSH Resolver</a></p> +</li> +<li> +<p><a href="#resolver_vfs">VFS Resolver</a></p> +</li> +<li> +<p><a href="#resolver_jar">Jar Resolver</a></p> +</li> +<li> +<p><a href="#resolver_obr">OSGi Bundle Repository</a></p> +</li> +<li> +<p><a href="#resolver_osgiagg">Aggregated OSGi Repository</a></p> +</li> +<li> +<p><a href="#resolver_updatesite">Eclipse updatesite</a></p> +</li> +<li> +<p><a href="#resolver_mirrored">Mirrored Resolver</a></p> +</li> +<li> +<p><a href="#resolver_bintray">Bintray Resolver</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#settings_conflict-managers">conflict-managers</a></p> +</li> +<li> +<p><a href="#settings_modules">modules</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#settings_module">module</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#settings_outputters">outputters</a></p> +</li> +<li> +<p><a href="#settings_statuses">statuses</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#settings_status">status</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#settings_triggers">triggers</a></p> +</li> +<li> +<p><a href="#settings_version-matchers">version-matchers</a></p> +</li> +<li> +<p><a href="#settings_timeout-constraints">timeout-constraints</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#settings_timeout-constraint">timeout-constraint</a></p> +</li> +</ul> +</div> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#ivyfile">Ivy Files</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#ivyfile_info">info</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#ivyfile_extends">extends</a></p> +</li> +<li> +<p><a href="#ivyfile_license">license</a></p> +</li> +<li> +<p><a href="#ivyfile_ivyauthor">ivyauthor</a></p> +</li> +<li> +<p><a href="#ivyfile_repository">repository</a></p> +</li> +<li> +<p><a href="#ivyfile_description">description</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#ivyfile_configurations">configurations</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#ivyfile_conf">conf</a></p> +</li> +<li> +<p><a href="#ivyfile_include">include</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#ivyfile_publications">publications</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#ivyfile_artifact">artifact</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#ivyfile_artifact-conf">conf</a></p> +</li> +</ul> +</div> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#ivyfile_dependencies">dependencies</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#ivyfile_dependency">dependency</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#ivyfile_dependency-conf">conf</a> +<strong><strong></strong></strong> <a href="#ivyfile_mapped">mapped</a></p> +</li> +<li> +<p><a href="#ivyfile_dependency-artifact">artifact</a> +<strong><strong></strong></strong> <a href="#ivyfile_dependency-artifact-conf">conf</a></p> +</li> +<li> +<p><a href="#ivyfile_artifact-exclude">exclude</a> +<strong><strong></strong></strong> <a href="#ivyfile_artifact-exclude-conf">conf</a></p> +</li> +<li> +<p><a href="#ivyfile_dependency-include">include</a> +<strong><strong></strong></strong> <a href="#ivyfile_dependency-include-conf">conf</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#ivyfile_exclude">exclude</a></p> +</li> +<li> +<p><a href="#ivyfile_override">override</a></p> +</li> +<li> +<p><a href="#ivyfile_conflict">conflict</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#ivyfile_conflicts">conflicts</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#ivyfile_manager">manager</a></p> +</li> +</ul> +</div> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#ant">Ant Tasks</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#use_artifactproperty">artifactproperty</a></p> +</li> +<li> +<p><a href="#use_artifactreport">artifactreport</a></p> +</li> +<li> +<p><a href="#use_buildlist">buildlist</a></p> +</li> +<li> +<p><a href="#use_buildnumber">buildnumber</a></p> +</li> +<li> +<p><a href="#use_buildobr">buildobr</a></p> +</li> +<li> +<p><a href="#use_cachefileset">cachefileset</a></p> +</li> +<li> +<p><a href="#use_cachepath">cachepath</a></p> +</li> +<li> +<p><a href="#use_checkdepsupdate">checkdepsupdate</a></p> +</li> +<li> +<p><a href="#use_cleancache">cleancache</a></p> +</li> +<li> +<p><a href="#use_configure">configure</a></p> +</li> +<li> +<p><a href="#use_convertmanifest">convertmanifest</a></p> +</li> +<li> +<p><a href="#use_convertpom">convertpom</a></p> +</li> +<li> +<p><a href="#use_deliver">deliver</a></p> +</li> +<li> +<p><a href="#use_dependencytree">dependencytree</a></p> +</li> +<li> +<p><a href="#use_findrevision">findrevision</a></p> +</li> +<li> +<p><a href="#use_fixdeps">fixdeps</a></p> +</li> +<li> +<p><a href="#use_info">info</a></p> +</li> +<li> +<p><a href="#use_install">install</a></p> +</li> +<li> +<p><a href="#use_listmodules">listmodules</a></p> +</li> +<li> +<p><a href="#use_makepom">makepom</a></p> +</li> +<li> +<p><a href="#use_postresolvetask">post resolve tasks</a></p> +</li> +<li> +<p><a href="#use_publish">publish</a></p> +</li> +<li> +<p><a href="#use_report">report</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#yed">Using yEd to layout report graphs</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#use_repreport">repreport</a></p> +</li> +<li> +<p><a href="#use_resolve">resolve</a></p> +</li> +<li> +<p><a href="#use_resources">resources</a></p> +</li> +<li> +<p><a href="#use_retrieve">retrieve</a></p> +</li> +<li> +<p><a href="#use_settings">settings</a></p> +</li> +<li> +<p><a href="#use_var">var</a></p> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#standalone">Using standalone</a></p> +</li> +<li> +<p><a href="#osgi">OSGi</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#osgi_osgi-mapping">OSGi mapping</a></p> +</li> +<li> +<p><a href="#osgi_eclipse-plugin">Building an Eclipse plugin</a></p> +</li> +<li> +<p><a href="#osgi_standard-osgi">Building a standard OSGi bundle</a></p> +</li> +<li> +<p><a href="#osgi_target-platform">Managing a target platform</a></p> +</li> +<li> +<p><a href="#osgi_sigil">Apache Felix Sigil</a></p> +</li> +</ul> +</div> +</li> +</ul> +</div> +</li> +<li> +<p><a href="#dev">Developer doc</a></p> +<div class="ulist"> +<ul> +<li> +<p><a href="#extend">Extending Ivy</a></p> +</li> +<li> +<p><a href="#dev_makerelease">Making a release</a></p> +</li> +</ul> +</div> +</li> +</ul> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="__a_id_release_notes_a_release_notes"><a id="release-notes"></a>Release Notes</h2> +<div class="sectionbody"> + +</div> +</div> +<h1 id="_ivy_release_announcement" class="sect0">Ivy Release Announcement</h1> +<div class="openblock partintro"> +<div class="content"> +XXXX DATE XXXXXX - The Apache Ivy project is pleased to announce its 2.5.0 release. +</div> +</div> +<div class="sect1"> +<h2 id="_what_is_ivy">What is Ivy?</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Apache Ivy is a tool for managing (recording, tracking, resolving and reporting) project dependencies, characterized by flexibility, +configurability, and tight integration with <a href="https://ant.apache.org/";>Apache Ant</a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_download">Download</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>You can download this release at <a href="https://ant.apache.org/ivy/download.cgi"; class="bare">https://ant.apache.org/ivy/download.cgi</a></p> +</div> +<div class="paragraph"> +<p>Issues should either be discussed in the <a href="https://ant.apache.org/ivy/mailing-lists.html";>Ivy user mailing list</a> or reported at <a href="https://issues.apache.org/jira/browse/IVY"; class="bare">https://issues.apache.org/jira/browse/IVY</a></p> +</div> +<div class="paragraph"> +<p>More information about the project can be found on the website <a href="https://ant.apache.org/ivy/"; class="bare">https://ant.apache.org/ivy/</a></p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_key_features_in_this_release">Key features in this release</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Key features of this 2.5.0 release are:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>The minimum runtime Java version required is now Java 7</p> +</li> +<li> +<p>Ivy now uses BouncyCastle OpenPGP API 1.59. Due to the non backward compatibility of that library, earlier versions are not supported.</p> +</li> +<li> +<p>Ivy now uses HttpComponents HttpClient 4.5.x version with HTTP backed resolvers. Users are expected to have this version of the library (and its dependencies) in their runtime classpath if they want to use such resolvers. The previous (similarly named but not the same) commons-httpclient library is no longer used or supported. (<a href="https://issues.apache.org/jira/browse/IVY-1563";>IVY-1563</a>)</p> +</li> +</ul> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_list_of_changes_in_this_release">List of Changes in this Release</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>For details about the following changes, check our JIRA install at <a href="https://issues.apache.org/jira/browse/IVY"; class="bare">https://issues.apache.org/jira/browse/IVY</a></p> +</div> +<div class="paragraph"> +<p><strong>List of changes since Ivy 2.4.0:</strong></p> +</div> +<div class="ulist"> +<ul> +<li> +<p>FIX: Local conflict manager didn’t handle deeper conflicts in transitive dependencies (<a href="https://issues.apache.org/jira/browse/IVY-1404";>IVY-1404</a>)</p> +</li> +<li> +<p>FIX: Made the Maven 'test' configuration public so we can use the test-jar as dependency (<a href="https://issues.apache.org/jira/browse/IVY-1444";>IVY-1444</a>)</p> +</li> +<li> +<p>FIX: NullPointerException in dependencytree with no dependencies (<a href="https://issues.apache.org/jira/browse/IVY-1539";>IVY-1539</a>)</p> +</li> +<li> +<p>FIX: checkIfChanged is not settable attribute for checkdepsupdate ant task (<a href="https://issues.apache.org/jira/browse/IVY-1549";>IVY-1549</a>)</p> +</li> +<li> +<p>FIX: ArrayIndexOutOfBoundsException when using a p2 repository for dependencies (<a href="https://issues.apache.org/jira/browse/IVY-1504";>IVY-1504</a>)</p> +</li> +<li> +<p>FIX: fixdeps remove transitive 'kept' dependencies</p> +</li> +<li> +<p>FIX: PomModuleDescriptorParser should parse licenses from parent POM (<a href="https://issues.apache.org/jira/browse/IVY-1526";>IVY-1526</a>) (Thanks to Jaikiran Pai)</p> +</li> +<li> +<p>FIX: dynamic revisions are not cached per resolver (<a href="https://issues.apache.org/jira/browse/IVY-1430";>IVY-1430</a>) (Thanks to Stephen Haberman)</p> +</li> +<li> +<p>FIX: Dependencies failed using branch attribute (and extra attributes) (<a href="https://issues.apache.org/jira/browse/IVY-1141";>IVY-1141</a>) (Thanks to Stephen Haberman)</p> +</li> +<li> +<p>FIX: useCacheOnly should allow lookup of changing dependencies in cache (<a href="https://issues.apache.org/jira/browse/IVY-1515";>IVY-1515</a>) (Thanks to Ilya)</p> +</li> +<li> +<p>FIX: Translation of POM to Ivy XML with * exclusion is removing main artifact (<a href="https://issues.apache.org/jira/browse/IVY-1531";>IVY-1531</a>) (Thanks to Jaikiran Pai)</p> +</li> +<li> +<p>FIX: Have makepom task take description from ivy-module > info > description element (<a href="https://issues.apache.org/jira/browse/IVY-1520";>IVY-1520</a>)</p> +</li> +<li> +<p>FIX: Fix RetrieveEngine to take into account the correct extension while dealing with unpacked artifacts (<a href="https://issues.apache.org/jira/browse/IVY-1478";>IVY-1478</a>) (Thanks to Jaikiran Pai)</p> +</li> +<li> +<p>FIX: ParseException "Unsupported repository, resources names are not uris" for ivy.xml with parent on Windows (<a href="https://issues.apache.org/jira/browse/IVY-1448";>IVY-1448</a>) (Thanks to Riccardo Foschia and Jaikiran Pai)</p> +</li> +<li> +<p>FIX: Ivy 2.4.0 improperly handles modules with colon (:) in version (<a href="https://issues.apache.org/jira/browse/IVY-1522";>IVY-1522</a>) (Thanks to Jaikiran Pai)</p> +</li> +<li> +<p>FIX: Delay the processing of configured cache ttls, until the IvySettings object is usable (<a href="https://issues.apache.org/jira/browse/IVY-1495";>IVY-1495</a>) (Thanks to Jaikiran Pai)</p> +</li> +<li> +<p>FIX: Including optional ivysettings of type 'file' doesn’t work when file doesn’t exist (<a href="https://issues.apache.org/jira/browse/IVY-1555";>IVY-1555</a>) (Thanks to Jaikiran Pai)</p> +</li> +<li> +<p>FIX: Makepom ignores dependency classifiers (<a href="https://issues.apache.org/jira/browse/IVY-1528";>IVY-1528</a>) (Thanks to Jaikiran Pai)</p> +</li> +<li> +<p>FIX: Infinite loop in dependency tree (<a href="https://issues.apache.org/jira/browse/IVY-1540";>IVY-1540</a>) (Thanks to Jaikiran Pai)</p> +</li> +<li> +<p>FIX: HTTP issue: Basic authentication is stuck in 401 loop (<a href="https://issues.apache.org/jira/browse/IVY-1336";>IVY-1336</a>)</p> +</li> +<li> +<p>FIX: command line: -types seems to not accept comma [<a href="https://issues.apache.org/jira/browse/IVY-1355";>IVY-1355</a>]</p> +</li> +<li> +<p>FIX: Mixed use of symlinks leads to cache corruption [<a href="https://issues.apache.org/jira/browse/IVY-1498";>IVY-1498</a>] (Thanks to Stephen Haberman)</p> +</li> +<li> +<p>FIX: Some cached locations are stored incorrectly resulting in MalformedURLException [<a href="https://issues.apache.org/jira/browse/IVY-1566";>IVY-1566</a>] (Thanks to Aurélien Pupier)</p> +</li> +<li> +<p>FIX: defaultconf/mapping attributes ignored when extended/included from parent file [<a href="https://issues.apache.org/jira/browse/IVY-1315";>IVY-1315</a>] [<a href="https://issues.apache.org/jira/browse/IVY-1419";>IVY-1419</a>] [<a href="https://issues.apache.org/jira/browse/IVY-1420";>IVY-1420</a>] [<a href="https://issues.apache.org/jira/browse/IVY-1437";>IVY-1437</a>] (Thanks to Willem Verstraeten)</p> +</li> +<li> +<p>FIX: ApacheURLLister skips versions with URL encoded characters [<a href="https://issues.apache.org/jira/browse/IVY-1442";>IVY-1442</a>] [<a href="https://issues.apache.org/jira/browse/IVY-1573";>IVY-1573</a>]</p> +</li> +<li> +<p>FIX: Configuration lists are sensitive to whitespace; multiple split/merge methods [<a href="https://issues.apache.org/jira/browse/IVY-309";>IVY-309</a>] [<a href="https://issues.apache.org/jira/browse/IVY-1282";>IVY-1282</a>]</p> +</li> +<li> +<p>FIX: Warnings about illegal reflection access due to lack of methods to retrieve default authenticator in Java 5 to 8 [<a href="https://issues.apache.org/jira/browse/IVY-1569";>IVY-1569</a>]</p> +</li> +<li> +<p>FIX: Cycle in parent POM ancestry yields StackOverflowError in PomModuleDescriptorParser (<a href="https://issues.apache.org/jira/browse/IVY-1545";>IVY-1545</a>) (Thanks to Brett Randall)</p> +</li> +<li> +<p>FIX: The method hasIvyListener in org.apache.ivy.core.event.EventManager always returned false</p> +</li> +<li> +<p>FIX: Allow conditionally activated properties through Maven profiles, to be referenced in the <code>pom.xml</code> (<a href="https://issues.apache.org/jira/browse/IVY-1577";>IVY-1577</a>)</p> +</li> +<li> +<p>FIX: Fix Maven dependency resolution for dependencies with multiple different classifiers (<a href="https://issues.apache.org/jira/browse/IVY-1576";>IVY-1576</a>)</p> +</li> +<li> +<p>FIX: Correct parent classloader when lauching resolved artifacts from CLI (<a href="https://issues.apache.org/jira/browse/IVY-1483";>IVY-1483</a>) (Thanks to Stephan Feder)</p> +</li> +<li> +<p>FIX: Make Main.run() public (usable with REPL) (<a href="https://issues.apache.org/jira/browse/IVY-1321";>IVY-1321</a> <a href="https://issues.apache.org/jira/browse/IVY-1578";>IVY-1578</a>) (Thanks to Greg Perry)</p> +</li> +<li> +<p>IMPROVEMENT: Throw an IllegalStateException when retrieving the resolutionCacheRoot on the DefaultResolutionCacheManager if the basedir (or IvySettings) is not set (<a href="https://issues.apache.org/jira/browse/IVY-1482";>IVY-1482</a>)</p> +</li> +<li> +<p>IMPROVEMENT: Optimization: limit the revision numbers scanned if revision prefix is specified (Thanks to Ernestas Vaiciukevičius)</p> +</li> +<li> +<p>IMPROVEMENT: Update BouncyCastle to 1.59 (<a href="https://issues.apache.org/jira/browse/IVY-1521";>IVY-1521</a>) (Thanks to Michal Srb)</p> +</li> +<li> +<p>IMPROVEMENT: <code>symlinkmass</code> option of retrieve task has been deprecated in this release and will no longer be supported since, starting this version of Ivy, Ivy uses Java standard API(s) for symlink management and as such doesn’t spawn a process to execute symlink creation shell commands, like it used to do earlier. The <code>symlinkmass</code> option was previously there to launch just one single process instead of multiple processes for symlink creation. Now with the usage of the Java standard API(s), this option no longer is relevant.</p> +</li> +<li> +<p>IMPROVEMENT: Ivy command line now supports passing <code>overwriteMode</code> option to <code>retrieve</code> task (<a href="https://issues.apache.org/jira/browse/IVY-1447";>IVY-1447</a>)</p> +</li> +<li> +<p>IMPROVEMENT: Support timestamped SNAPSHOT versions from Maven repository (<a href="https://issues.apache.org/jira/browse/IVY-1153";>IVY-1153</a>) and (<a href="https://issues.apache.org/jira/browse/IVY-1476";>IVY-1476</a>)</p> +</li> +<li> +<p>IMPROVEMENT: Update Commons VFS to 2.2</p> +</li> +<li> +<p>IMPROVEMENT: Ivy now supports activating of Maven profiles, in <code>pom.xml</code>, by <code>jdk</code>, <code>os</code>, <code>property</code> and <code>file</code> (<a href="https://issues.apache.org/jira/browse/IVY-1558";>IVY-1558</a>) and (<a href="https://issues.apache.org/jira/browse/IVY-1577";>IVY-1577</a>)</p> +</li> +<li> +<p>NEW: Lets SSH-based resolvers use an <code>~/.ssh/config</code> file to find username/hostname/keyfile options (Thanks to Colin Stanfill)</p> +</li> +<li> +<p>NEW: Add ivy.maven.lookup.sources and ivy.maven.lookup.javadoc variables to control the lookup of the additional artifacts. Defaults to true, for backward compatibility (<a href="https://issues.apache.org/jira/browse/IVY-1529";>IVY-1529</a>)</p> +</li> +<li> +<p>NEW: Add (conditional) support for SHA-256, SHA-512 and SHA-384 checksum algorithms (<a href="https://issues.apache.org/jira/browse/IVY-1554";>IVY-1554</a>) (Thanks to Jaikiran Pai)</p> +</li> +<li> +<p>NEW: The standalone Ivy jar can now be used to generate a pom file for the resolved module, using the <code>makepom</code> option (Thanks to <a href="https://github.com/aanno";>Thomas Pasch</a>)</p> +</li> +</ul> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_committers_and_contributors">Committers and Contributors</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>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 !</p> +</div> +<div class="paragraph"> +<p><strong>Committers:</strong></p> +</div> +<div class="ulist"> +<ul> +<li> +<p>Matt Benson</p> +</li> +<li> +<p>Jean-Louis Boudart</p> +</li> +<li> +<p>Maarten Coene</p> +</li> +<li> +<p>Charles Duffy</p> +</li> +<li> +<p>Gintautas Grigelionis</p> +</li> +<li> +<p>Xavier Hanin</p> +</li> +<li> +<p>Nicolas Lalevée</p> +</li> +<li> +<p>Jaikiran Pai</p> +</li> +<li> +<p>Jon Schneider</p> +</li> +<li> +<p>Gilles Scokart</p> +</li> +</ul> +</div> +<div class="paragraph"> +<p><strong>Contributors:</strong></p> +</div> +<div class="ulist"> +<ul> +<li> +<p>Ingo Adler</p> +</li> +<li> +<p>alex322</p> +</li> +<li> +<p>Mathieu Anquetin</p> +</li> +<li> +<p>Andreas Axelsson</p> +</li> +<li> +<p>Stéphane Bailliez</p> +</li> +<li> +<p>Karl Baum</p> +</li> +<li> +<p>Andrew Bernhagen</p> +</li> +<li> +<p>Mikkel Bjerg</p> +</li> +<li> +<p>Per Arnold Blaasmo</p> +</li> +<li> +<p>Jeffrey Blattman</p> +</li> +<li> +<p>Jasper Blues</p> +</li> +<li> +<p>Jim Bonanno</p> +</li> +<li> +<p>Joseph Boyd</p> +</li> +<li> +<p>Dave Brosius</p> +</li> +<li> +<p>Matthieu Brouillard</p> +</li> +<li> +<p>Carlton Brown</p> +</li> +<li> +<p>Mirko Bulovic</p> +</li> +<li> +<p>Ed Burcher</p> +</li> +<li> +<p>Jamie Burns</p> +</li> +<li> +<p>Wei Chen</p> +</li> +<li> +<p>Chris Chilvers</p> +</li> +<li> +<p>Kristian Cibulskis</p> +</li> +<li> +<p>Andrea Bernardo Ciddio</p> +</li> +<li> +<p>Archie Cobbs</p> +</li> +<li> +<p>Flavio Coutinho da Costa</p> +</li> +<li> +<p>Stefan De Boey</p> +</li> +<li> +<p>Mykhailo Delegan</p> +</li> +<li> +<p>Charles Duffy</p> +</li> +<li> +<p>Martin Eigenbrodt</p> +</li> +<li> +<p>Stephen Evanchik</p> +</li> +<li> +<p>Stephan Feder</p> +</li> +<li> +<p>Robin Fernandes</p> +</li> +<li> +<p>Gregory Fernandez</p> +</li> +<li> +<p>Danno Ferrin</p> +</li> +<li> +<p>Riccardo Foschia</p> +</li> +<li> +<p>Benjamin Francisoud</p> +</li> +<li> +<p>Wolfgang Frank</p> +</li> +<li> +<p>Jacob Grydholt Jensen</p> +</li> +<li> +<p>John Gibson</p> +</li> +<li> +<p>Mitch Gitman</p> +</li> +<li> +<p>Evgeny Goldin</p> +</li> +<li> +<p>Scott Goldstein</p> +</li> +<li> +<p>Stephen Haberman</p> +</li> +<li> +<p>Aaron Hachez</p> +</li> +<li> +<p>Ben Hale</p> +</li> +<li> +<p>Peter Hayes</p> +</li> +<li> +<p>Scott Hebert</p> +</li> +<li> +<p>Payam Hekmat</p> +</li> +<li> +<p>Tobias Himstedt</p> +</li> +<li> +<p>Achim Huegen</p> +</li> +<li> +<p>Pierre Hägnestrand</p> +</li> +<li> +<p>Ilya</p> +</li> +<li> +<p>Matt Inger</p> +</li> +<li> +<p>Anders Jacobsson</p> +</li> +<li> +<p>Anders Janmyr</p> +</li> +<li> +<p>Steve Jones</p> +</li> +<li> +<p>Christer Jonsson</p> +</li> +<li> +<p>Michael Kebe</p> +</li> +<li> +<p>Matthias Kilian</p> +</li> +<li> +<p>Alexey Kiselev</p> +</li> +<li> +<p>Gregory Kisling</p> +</li> +<li> +<p>Stepan Koltsov</p> +</li> +<li> +<p>Heschi Kreinick</p> +</li> +<li> +<p>Sebastian Krueger</p> +</li> +<li> +<p>Thomas Kurpick</p> +</li> +<li> +<p>Costin Leau</p> +</li> +<li> +<p>Tat Leung</p> +</li> +<li> +<p>Antoine Levy-Lambert</p> +</li> +<li> +<p>Tony Likhite</p> +</li> +<li> +<p>Andrey Lomakin</p> +</li> +<li> +<p>William Lyvers</p> +</li> +<li> +<p>Sakari Maaranen</p> +</li> +<li> +<p>Jan Materne</p> +</li> +<li> +<p>Markus M. May</p> +</li> +<li> +<p>Abel Muino</p> +</li> +<li> +<p>J. Lewis Muir</p> +</li> +<li> +<p>Stephen Nesbitt</p> +</li> +<li> +<p>Joshua Nichols</p> +</li> +<li> +<p>Bernard Niset</p> +</li> +<li> +<p>Ales Nosek</p> +</li> +<li> +<p>David Maplesden</p> +</li> +<li> +<p>Glen Marchesani</p> +</li> +<li> +<p>Phil Messenger</p> +</li> +<li> +<p>Steve Miller</p> +</li> +<li> +<p>Mathias Muller</p> +</li> +<li> +<p>Randy Nott</p> +</li> +<li> +<p>Peter Oxenham</p> +</li> +<li> +<p>Douglas Palmer</p> +</li> +<li> +<p>Thomas Pasch</p> +</li> +<li> +<p>Jesper Pedersen</p> +</li> +<li> +<p>Emmanuel Pellereau</p> +</li> +<li> +<p>Greg Perry</p> +</li> +<li> +<p>Carsten Pfeiffer</p> +</li> +<li> +<p>Yanus Poluektovich</p> +</li> +<li> +<p>Roshan Punnoose</p> +</li> +<li> +<p>Aurélien Pupier</p> +</li> +<li> +<p>Jean-Baptiste Quenot</p> +</li> +<li> +<p>Carl Quinn</p> +</li> +<li> +<p>Damon Rand</p> +</li> +<li> +<p>Geoff Reedy</p> +</li> +<li> +<p>Torkild U. Resheim</p> +</li> +<li> +<p>Christian Riege</p> +</li> +<li> +<p>Frederic Riviere</p> +</li> +<li> +<p>Jens Rohloff</p> +</li> +<li> +<p>Andreas Sahlbach</p> +</li> +<li> +<p>Brian Sanders</p> +</li> +<li> +<p>Adrian Sandor</p> +</li> +<li> +<p>Michael Scheetz</p> +</li> +<li> +<p>Ben Schmidt</p> +</li> +<li> +<p>Ruslan Shevchenko</p> +</li> +<li> +<p>John Shields</p> +</li> +<li> +<p>Nihal Sinha</p> +</li> +<li> +<p>Gene Smith</p> +</li> +<li> +<p>Michal Srb</p> +</li> +<li> +<p>Colin Stanfill</p> +</li> +<li> +<p>Simon Steiner</p> +</li> +<li> +<p>Johan Stuyts</p> +</li> +<li> +<p>John Tinetti</p> +</li> +<li> +<p>Erwin Tratar</p> +</li> +<li> +<p>Jason Trump</p> +</li> +<li> +<p>David Turner</p> +</li> +<li> +<p>Ernestas Vaiciukevičius</p> +</li> +<li> +<p>Tjeerd Verhagen</p> +</li> +<li> +<p>Willem Verstraeten</p> +</li> +<li> +<p>Richard Vowles</p> +</li> +<li> +<p>Sven Walter</p> +</li> +<li> +<p>Zhong Wang</p> +</li> +<li> +<p>James P. White</p> +</li> +<li> +<p>Tom Widmer</p> +</li> +<li> +<p>John Williams</p> +</li> +<li> +<p>Chris Wood</p> +</li> +<li> +<p>Patrick Woodworth</p> +</li> +<li> +<p>Jaroslaw Wypychowski</p> +</li> +<li> +<p>Sven Zethelius</p> +</li> +<li> +<p>Aleksey Zhukov</p> +</li> +</ul> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="__a_id_tutorial_a_tutorials"><a id="tutorial"></a>Tutorials</h2> +<div class="sectionbody"> + +</div> +</div> +<h1 id="_ivy_tutorials" class="sect0">Ivy Tutorials</h1> +<div class="openblock partintro"> +<div class="content"> +<div class="paragraph"> +<p>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="https://ant.apache.org/ivy/features.html";>features</a>.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_first_tutorial">First Tutorial</h2> +<div class="sectionbody"> +<div class="ulist"> +<ul> +<li> +<p>Make sure you have <a href="https://ant.apache.org/";>Ant</a> 1.9.9 or greater and a <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html";>Java JDK</a> properly installed<br/></p> +</li> +<li> +<p>Copy <a href="samples/build.xml">this build file</a> to an empty directory on your local filesystem (and make sure you name it <code>build.xml</code>)<br/></p> +</li> +<li> +<p>Open a console in that directory and run the command: <code>ant</code>. That’s it!<br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>If you have any trouble, check our <a href="https://ant.apache.org/ivy/faq.html";>FAQ</a>.</p> +</div> +<div class="paragraph"> +<p>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 <a href="https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=tree;f=src/example";>src/example</a> directory).</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_list_of_available_tutorials">List of available tutorials</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The following tutorials are available:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><a href="tutorial/start.html">Quick Start</a><br/> +Guides you through your very first steps with Ivy.</p> +</li> +<li> +<p><a href="tutorial/defaultconf.html">Adjusting default settings</a><br/> +Gives you a better understanding of the default settings and shows you how to customize them to your needs.</p> +</li> +<li> +<p><a href="tutorial/multiple.html">Multiple Resolvers</a><br/> +Teaches you how to configure Ivy to find its dependencies in multiple places.</p> +</li> +<li> +<p><a href="tutorial/dual.html">Dual Resolver</a><br/> +Helps you configure Ivy to find Ivy files in one place and artifacts in another.</p> +</li> +<li> +<p><a href="tutorial/dependence.html">Project dependencies</a><br/> +A starting point for using Ivy in a multi-project environment.</p> +</li> +<li> +<p><a href="tutorial/multiproject.html">Using Ivy in multiple projects environment</a><br/> +A more complex example demonstrating the use of Ant+Ivy in a multi-project environment.</p> +</li> +<li> +<p><a href="tutorial/conf.html">Using Ivy Module Configurations</a><br/> +Shows you how to use configurations in an Ivy file to define sets of artifacts.</p> +</li> +<li> +<p><a href="tutorial/build-repository.html">Building a repository</a><br/> +Shows you how to build your own enterprise repository.</p> +</li> +</ul> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="__a_id_tutorial_start_a_quick_start"><a id="tutorial_start"></a>Quick Start</h2> +<div class="sectionbody"> + +</div> +</div> +<h1 id="_ivy_quickstart" class="sect0">Ivy Quickstart</h1> +<div class="openblock partintro"> +<div class="content"> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p><em>You’ll find this tutorial’s sources in the Ivy distribution in the src/example/hello-ivy directory.</em></p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_ivy_xml_file">The ivy.xml file</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This file describes the dependencies of the project on other libraries. Here is the sample:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ivy-module version="2.0"> + <info organisation="org.apache" module="hello-ivy"/> + <dependencies> + <dependency org="commons-lang" name="commons-lang" rev="2.0"/> + <dependency org="commons-cli" name="commons-cli" rev="1.0"/> + </dependencies> +</ivy-module></code></pre> +</div> +</div> +<div class="paragraph"> +<p>The format of this file should be pretty easy to understand, but let’s discuss some details about what is declared here. First, the root element is <code>ivy-module</code>, with the <code>version</code> attribute telling Ivy which lowest version of Ivy this file is compatible with.</p> +</div> +<div class="paragraph"> +<p>Then there is an <code>info</code> tag, which provides information about the module for which we are defining dependencies. Here we define only the <code>organization</code> and <code>module</code> names. You are free to choose whatever you want for them, but we recommend avoiding spaces for both.</p> +</div> +<div class="paragraph"> +<p>Finally, the <code>dependencies</code> section lets you define dependencies. In this example, this module depends on two libraries: <code>commons-lang</code> and <code>commons-cli</code>. As you can see, we use the <code>org</code> and <code>name</code> attributes to define the organization and module name of the dependencies we need. The <code>rev</code> attribute is used to specify the version of the module you depend on.</p> +</div> +<div class="paragraph"> +<p>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 central repository by default, so we recommend you use <a href="https://mvnrepository.com";>mvnrepository.com</a> to look for the module you want. Once you find it, you will have the details of that module in the <code>pom.xml</code> file of that module. For instance:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"> <project ....> + <groupId>commons-lang</groupId> + <artifactId>commons-lang</artifactId> + <version>2.0</version> + ...</code></pre> +</div> +</div> +<div class="paragraph"> +<p>To convert this into an Ivy dependency declaration, all you have to do is use the <code>groupId</code> as organization, the <code>artifactId</code> as module name, and the version as revision. That’s what we did for the dependencies in this tutorial, that is <code>commons-lang</code> and <code>commons-cli</code>. Note that having <code>commons-lang</code> and <code>commons-cli</code> as <code>organization</code> is not the best example of what the organization should be. It would be better to use <code>org.apache</code>, <code>org.apache.commons</code> or <code>org.apache.commons.lang</code>. However, this is how these specific modules were 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).</p> +</div> +<div class="paragraph"> +<p>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>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_build_xml_file">The build.xml file</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The corresponding build file contains a set of targets, allowing you to resolve dependencies declared in the Ivy file, to compile and run the sample code, produce a report of dependency resolution, and clean the cache or the project. +You can use the standard <code>ant -p</code> command 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:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><project xmlns:ivy="antlib:org.apache.ivy.ant" name="hello-ivy" default="run"> + + ... + + <!-- ================================= + target: resolve + ================================= --> + <target name="resolve" description="--> retrieve dependencies with Ivy"> + <ivy:retrieve/> + </target> +</project></code></pre> +</div> +</div> +<div class="paragraph"> +<p>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 (<code>xmlns:ivy="antlib:org.apache.ivy.ant"</code>). Then all the <a href="../ant.html">Ivy Ant tasks</a> will be available in this namespace.</p> +</div> +<div class="paragraph"> +<p>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 <code>ivy.xml</code> for the dependency definitions. That’s exactly what we want, so we need nothing more than that.</p> +</div> +<div class="paragraph"> +<p>Note that in this case we define a <code>resolve</code> target and call the <code><a href="../use/retrieve.html">retrieve</a></code> 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 copy of those file to a local project directory). Check the <a href="../principle.html">How does it work ?</a> page for details about that.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_the_project">Running the project</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>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 go into the <code>hello-ivy</code> example directory. +Then, at the command prompt, run <code>ant</code>:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-shell" data-lang="shell">Unresolved directive in asciidoc/tutorial/start.adoc - include::asciidoc/tutorial/log/hello-ivy-1.txt[]</code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_what_happened">What happened ?</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Without any settings, Ivy retrieves files from the Maven 2 repository. That’s what happened here. +The resolve task has found the <code>commons-lang</code> and <code>commons-cli</code> modules in the Maven 2 central repository, identified that <code>commons-cli</code> depends on <code>commons-logging</code> 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 <code>.ivy2/cache</code> directory). Finally, the retrieve task copies the resolved jars from the Ivy cache to the default library directory of the project: the <code>lib</code> dir (you can change this easily by setting the pattern attribute on the <a href="../use/retrieve.html">retrieve</a> task).</p> +</div> +<div class="paragraph"> +<p>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:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-shell" data-lang="shell">Unresolved directive in asciidoc/tutorial/start.adoc - include::asciidoc/tutorial/log/hello-ivy-2.txt[]</code></pre> +</div> +</div> +<div class="paragraph"> +<p>Great! The cache was used, so no download was needed and the build was instantaneous.</p> +</div> +<div class="paragraph"> +<p>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>.</p> +</div> +<div class="paragraph"> +<p>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 other tutorials to learn more about <a href="../tutorial/conf.html">how to use module configurations</a> which is a very powerful Ivy specific feature. More 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 material 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.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="__a_id_tutorial_defaultconf_a_adjusting_default_settings"><a id="tutorial_defaultconf"></a>Adjusting default settings</h2> +<div class="sectionbody"> + +</div> +</div> +<h1 id="_adjusting_default_ivy_configurations" class="sect0">Adjusting default Ivy configurations</h1> +<div class="openblock partintro"> +<div class="content"> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_concept">Concept</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The default settings include 3 types of repositories:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>local<br/> +A repository which is private to the user.</p> +</li> +<li> +<p>shared<br/> +A repository which is shared between all the members of a team</p> +</li> +<li> +<p>public<br/> +A public repository in which most modules, and especially third party modules, can be found</p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>Now let’s describe each of these repository concepts in more detail. We will describe how they are set up physically later.</p> +</div> +<div class="sect2"> +<h3 id="_local">Local</h3> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>For instance, if you have a module declaring a dependency on the module <code>foo</code> with a revision of <code>latest.integration</code>, then if a revision of <code>foo</code> is found in the local repository, it will be used, <em>even if a more recent revision is available in other repositories</em>.</p> +</div> +<div class="paragraph"> +<p>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 <code>foo</code> and exploit this new method in module <code>bar</code>. Then if you publish the module <code>foo</code> to your local repository, you will be sure to get it in your <code>bar</code> module, even if someone else publishes a new revision of <code>foo</code> in the shared repository (this revision not having the new method you are currently adding).</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_shared">Shared</h3> +<div class="paragraph"> +<p>As its name suggest, the shared repository is aimed to be shared among the 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. You can also put modules here that are simply inaccurate in a public repository (bad or incomplete module descriptors, for instance).</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_public">Public</h3> +<div class="paragraph"> +<p>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.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_setting_up_the_repositories">Setting up the repositories</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Now that we have seen the objective of each of the three repositories, let’s see how they are set up and how to configure them to fit your needs.</p> +</div> +<div class="paragraph"> +<p>First, several repositories use the same root in your filesystem. Referenced as <code>${ivy.default.ivy.user.dir}</code>, this is by default the directory <code>.ivy2</code> in your user home.</p> +</div> +<div class="paragraph"> +<p>Note that several things can be done by setting Ivy variables. To set them without defining your own <code>ivysettings.xml</code> file, you can:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>set an Ant property before any call to Ivy in your build file if you use Ivy from Ant<br/></p> +</li> +<li> +<p>set an environment variable if you use Ivy from the command line<br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>For example:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><target name="resolve"> + <property name="ivy.default.ivy.user.dir" value="/path/to/ivy/user/dir"/> + <ivy:resolve/> +</target></code></pre> +</div> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="sect2"> +<h3 id="_local_2">Local</h3> +<div class="paragraph"> +<p>By default, the local repository lies in <code>${ivy.default.ivy.user.dir}/local</code>. This is usually a good place, but you may want to modify it. No problem, you just have to set the <code>ivy.local.default.root</code> Ivy variable to the directory you want to use:</p> +</div> +<div class="paragraph"> +<p>For example:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code>ivy.local.default.root=/opt/ivy/repository/local</code></pre> +</div> +</div> +<div class="paragraph"> +<p>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:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><code>ivy.local.default.ivy.pattern</code> which gives the pattern to find Ivy module descriptor files</p> +</li> +<li> +<p><code>ivy.local.default.artifact.pattern</code> which gives the pattern to find the artifacts</p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>For example:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code>ivy.local.default.root=/opt/ivy/repository/local +ivy.local.default.ivy.pattern=[module]/[revision]/ivy.xml +ivy.local.default.artifact.pattern=[module]/[revision]/[artifact].[ext]</code></pre> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_shared_2">Shared</h3> +<div class="paragraph"> +<p>By default, the shared repository lies in <code>${ivy.default.ivy.user.dir}/shared</code>. 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 <code>ivy.shared.default.root</code> variable to specify a different directory. Moreover, you can also configure the layout with variables similar to the ones used for the local repository:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><code>ivy.shared.default.ivy.pattern</code> which gives the pattern to find Ivy module descriptor files</p> +</li> +<li> +<p><code>ivy.shared.default.artifact.pattern</code> which gives the pattern to find the artifacts</p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>For example:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code>ivy.shared.default.root=/opt/ivy/repository/shared +ivy.shared.default.ivy.pattern=[organisation]/[module]/[revision]/ivy.xml +ivy.shared.default.artifact.pattern=[organisation]/[module]/[revision]/[artifact].[ext]</code></pre> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_public_2">Public</h3> +<div class="paragraph"> +<p>By default, the public repository is ibiblio in m2 compatible mode (in other words, the Maven 2 public repository).</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +In <code>1.4</code> version, Ivy was using <code>ivyrep</code> as the default resolver, if you want to restore this, set <code>ivy.14.compatible=true</code> as an Ant property +</td> +</tr> +</table> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_going_further">Going further</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>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 …​</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>But before explaining how, you will need to have a quick overview of how Ivy is configured by default.</p> +</div> +<div class="paragraph"> +<p>By default, Ivy is configured using an <code>ivysettings.xml</code> which is packaged in the Ivy jar. Here is this settings file:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ivysettings> + <settings defaultResolver="default"/> + <include url="${ivy.default.settings.dir}/ivysettings-public.xml"/> + <include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/> + <include url="${ivy.default.settings.dir}/ivysettings-local.xml"/> + <include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/> + <include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/> +</ivysettings></code></pre> +</div> +</div> +<div class="paragraph"> +<p>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 Ivy settings 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 the settings like the following:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ivysettings> + <settings defaultResolver="default"/> + <include url="http://myserver/ivy/myivysettings-public.xml"/> + <include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/> + <include url="${ivy.default.settings.dir}/ivysettings-local.xml"/> + <include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/> + <include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/> +</ivysettings></code></pre> +</div> +</div> +<div class="paragraph"> +<p>Note that only the <code>ivysettings-public.xml</code> inclusion has changed to include a homemade public resolver. Note also that this can be used like that thanks to the fact that <code>${ivy.default.settings.dir}</code> is a variable which is always set to the place where Ivy’s default settings files are (i.e. packaged in the jar).</p> +</div> +<div class="paragraph"> +<p>To finish this example, you have to write your own Ivy settings file (that you will make available at <code><a href="http://myserver/ivy/myivysettings-public.xml"; class="bare">http://myserver/ivy/myivysettings-public.xml</a></code> in this example) for defining your own public resolver. For instance, the contents of such a file could be:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ivysettings> + <resolvers> + <filesystem name="public"> + <ivy pattern="/path/to/my/public/rep/[organisation]/[module]/ivy-[revision].xml"/> + <artifact pattern="/path/to/my/public/rep/[organisation]/[module]/[artifact]-[revision].[ext]"/> + </filesystem> + </resolvers> +</ivysettings></code></pre> +</div> +</div> +<div class="paragraph"> +<p>Now the last thing you will need in order to properly take advantage of the default settings is the content of each included Ivy settings file:</p> +</div> +<div class="listingblock"> +<div class="title"><strong>ivysettings-public.xml</strong></div> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ivysettings> + <resolvers> + <ibiblio name="public" m2compatible="true"/> + </resolvers> +</ivysettings></code></pre> +</div> +</div> +<div class="listingblock"> +<div class="title"><strong>ivysettings-shared.xml</strong></div> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ivysettings> + <property name="ivy.shared.default.root" value="${ivy.default.ivy.user.dir}/shared" override="false"/> + <property name="ivy.shared.default.ivy.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/> + <property name="ivy.shared.default.artifact.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/> + <resolvers> + <filesystem name="shared"> + <ivy pattern="${ivy.shared.default.root}/${ivy.shared.default.ivy.pattern}"/> + <artifact pattern="${ivy.shared.default.root}/${ivy.shared.default.artifact.pattern}"/> + </filesystem> + </resolvers> +</ivysettings></code></pre> +</div> +</div> +<div class="listingblock"> +<div class="title"><strong>ivysettings-local.xml</strong></div> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ivysettings> + <property name="ivy.local.default.root" value="${ivy.default.ivy.user.dir}/local" override="false"/> + <property name="ivy.local.default.ivy.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/> + <property name="ivy.local.default.artifact.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/> + <resolvers> + <filesystem name="local"> + <ivy pattern="${ivy.local.default.root}/${ivy.local.default.ivy.pattern}"/> + <artifact pattern="${ivy.local.default.root}/${ivy.local.default.artifact.pattern}"/> + </filesystem> + </resolvers> +</ivysettings></code></pre> +</div> +</div> +<div class="listingblock"> +<div class="title"><strong>ivysettings-main-chain.xml</strong></div> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ivysettings> + <resolvers> + <chain name="main" dual="true"> + <resolver ref="shared"/> + <resolver ref="public"/> + </chain> + </resolvers> +</ivysettings></code></pre> +</div> +</div> +<div class="listingblock"> +<div class="title"><strong>ivysettings-default-chain.xml</strong></div> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ivysettings> + <resolvers> + <chain name="default" returnFirst="true"> + <resolver ref="local"/> + <resolver ref="main"/> + </chain> + </resolvers> +</ivysettings></code></pre> +</div> +</div> +<div class="paragraph"> +<p>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!</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="__a_id_tutorial_multiple_a_multiple_resolvers"><a id="tutorial_multiple"></a>Multiple Resolvers</h2> +<div class="sectionbody"> + +</div> +</div> +<h1 id="_multiple_resolvers" class="sect0">Multiple Resolvers</h1> +<div class="openblock partintro"> +<div class="content"> +<div class="paragraph"> +<p>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:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>separating integration builds from releases<br/></p> +</li> +<li> +<p>using a public repository for third party modules and a private one for internal modules<br/></p> +</li> +<li> +<p>use a repository for storing modules which are not accurate in an unmanaged public repository<br/></p> +</li> +<li> +<p>use a local repository to expose builds made on one developer’s station<br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>In Ivy, the use of multiple resolvers is supported by a compound resolver called the chain resolver.</p> +</div> +<div class="paragraph"> +<p>In our example, we will simply show you how to use two resolvers, one for a local repository and one using the Maven 2 repository.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_project_description">Project Description</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_the_project_chained_resolvers">The project: chained-resolvers</h3> +<div class="paragraph"> +<p>The project is very simple and contains only one simple class: <code>example.Hello</code>.</p> +</div> +<div class="paragraph"> +<p>It depends on two libraries: Apache’s <code>commons-lang</code> and a custom library named <code>test</code> (sources are included in <code>test-1.0.jar</code> file). The test library is used by the project to uppercase a string, and <code>commons-lang</code> is used to capitalize the same string.</p> +</div> +<div class="paragraph"> +<p>Here is the content of the project:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>build.xml: the Ant build file for the project<br/></p> +</li> +<li> +<p>ivy.xml: the Ivy project file<br/></p> +</li> +<li> +<p>src/example/Hello.java: the only class of the project<br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>Let’s have a look at the <strong>ivy.xml</strong> file:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml">Unresolved directive in asciidoc/tutorial/multiple.adoc - include::src/example/chained-resolvers/chainedresolvers-project/ivy.xml[]</code></pre> +</div> +</div> +<div class="paragraph"> +<p>As we’d expect, the Ivy file declares this module to be dependent on the two libraries it uses: <code>commons-lang</code> and <code>test</code>. Note that we didn’t specify the <code>org</code> for the dependency <code>test</code>. When we exclude <code>org</code>, Ivy assumes it is in the same <code>org</code> as the declaring module. (in this example, it’s <code>org.apache</code>).</p> +</div> +</div> +<div class="sect2"> +<h3 id="_the_ivy_settings">The Ivy Settings</h3> +<div class="paragraph"> +<p>The settings are defined in the <code>ivysettings.xml</code> file located in the <code>settings</code> directory of the project. Below are its contents, followed by an explanation of what it’s doing.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code>Unresolved directive in asciidoc/tutorial/multiple.adoc - include::src/example/chained-resolvers/settings/ivysettings.xml[]</code></pre> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_the_strong_settings_strong_tag">The <strong>settings</strong> tag</h3> +<div class="paragraph"> +<p>This tag initializes Ivy with some parameters. Here only one parameter is set, the name of the resolver to use by default.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_the_strong_resolvers_strong_tag">The <strong>resolvers</strong> tag</h3> +<div class="paragraph"> +<p>The resolvers section defines the list of resolvers that Ivy will use to locate artifacts. In our example, we have only one resolver named <code>chain-example</code>, which is unique in that it defines a list (hence a chain) of resolvers.</p> +</div> +<div class="paragraph"> +<p>The resolvers in this chain are:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><code>libraries</code> : It is a filesystem resolver, so looks at a directory structure to retrieve the artifacts. This one is configured to look in the <code>repository</code> sub directory of the directory that contains the <code>ivysettings.xml</code> file.<br/></p> +</li> +<li> +<p><code>ibiblio</code> : It looks in the ibiblio Maven repository to retrieve the artifacts.<br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>That’s it, we have just configured a chain of resolvers!</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_walkthrough">Walkthrough</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_step_1_preparation">Step 1: Preparation</h3> +<div class="paragraph"> +<p>Open a shell (or command line) window, and go to the <code>src/example/chained-resolvers</code> directory.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_step_2_clean_directory_tree">Step 2: clean directory tree</h3> +<div class="paragraph"> +<p>On the prompt type: <code>ant</code></p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +<div class="paragraph"> +<p>In almost all examples, we provide a <code>clean</code> target, as the default target. Since most examples use the same Ivy cache, you will clean the whole Ivy cache each time you call this target.</p> +</div> +<div class="paragraph"> +<p>Cleaning the Ivy cache is something you can do without fear (except for 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.</p> +</div> +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_step_3_run_the_project">Step 3: run the project</h3> +<div class="paragraph"> +<p>Go to <code>chained-resolvers</code> project directory. And simply run <code>ant</code>.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-shell" data-lang="shell">Unresolved directive in asciidoc/tutorial/multiple.adoc - include::asciidoc/tutorial/log/chained-resolvers.txt[]</code></pre> +</div> +</div> +<div class="paragraph"> +<p>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).</p> +</div> +<div class="paragraph"> +<p>Also notice that the <code>run</code> Ant target succeeded in using both <code>commons-lang.jar</code> coming from the ibiblio repository and <code>test.jar</code> coming from the local repository.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_going_further_2">Going further</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>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!</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>a chain is not limited to two nested resolvers, you can use as many as you want<br/></p> +</li> +<li> +<p>by setting <code>returnFirst="true"</code>, you can have a chain which stops as soon as it has found a result for a given module<br/></p> +</li> +<li> +<p>by setting <code>dual="true"</code>, the full chain will be used both for module descriptors and artifacts, while setting <code>dual="false"</code>, the resolver in the chain which found the module descriptor (if any) is also used for artifacts<br/></p> +</li> +</ul> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="__a_id_tutorial_dual_a_dual_resolver"><a id="tutorial_dual"></a>Dual Resolver</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>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?</p> +</div> +<div class="paragraph"> +<p>Use a Dual resolver! And this tutorial will show you how.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_project_description_2">Project description</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Let’s have a look at the <code>src/example/dual</code> directory in your Ivy distribution. +It contains a build file and 3 directories:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>settings: contains the Ivy settings file<br/></p> +</li> +<li> +<p>repository: a sample repository of Ivy files<br/></p> +</li> +<li> +<p>project: the project making use of Ivy with dual resolver<br/></p> +</li> +</ul> +</div> +<div class="sect2"> +<h3 id="_the_dual_project">The dual project</h3> +<div class="paragraph"> +<p>The project is very simple and contains only one simple class: <code>example.HelloIvy</code> +It depends on two libraries: Apache commons-lang and Apache commons-httpclient.</p> +</div> +<div class="paragraph"> +<p>Here is the content of the project:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>build.xml: the Ant build file for the project<br/></p> +</li> +<li> +<p>ivy.xml: the Ivy project file<br/></p> +</li> +<li> +<p>src/example/HelloIvy.java: the only class of the project<br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>Let’s have a look at the <code>ivy.xml</code> file:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code><ivy-module version="1.0"> + <info organisation="org.apache" module="hello-ivy"/> + <dependencies> + <dependency org="commons-httpclient" name="commons-httpclient" rev="2.0.2"/> + <dependency org="commons-lang" name="commons-lang" rev="2.6"/> + </dependencies> +</ivy-module></code></pre> +</div> +</div> +<div class="paragraph"> +<p>As you can see, nothing special here…​ Indeed, Ivy’s philosophy is to keep Ivy files independent of the way dependencies are resolved.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_the_strong_ivy_strong_settings">The <strong>Ivy</strong> settings</h3> +<div class="paragraph"> +<p>The Ivy settings are defined in the <code>ivysettings.xml</code> file located in the <code>settings</code> directory. Here is what it contains, followed by an explanation.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code><ivysettings> + <settings defaultResolver="dual-example"/> + <resolvers> + <dual name="dual-example"> + <filesystem name="ivys"> + <ivy pattern="${ivy.settings.dir}/../repository/[module]-ivy-[revision].xml"/> + </filesystem> + <ibiblio name="ibiblio" m2compatible="true" usepoms="false"/> + </dual> + </resolvers> +</ivysettings></code></pre> +</div> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>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 <code>repository</code> directory, named according to the pattern: <code>[module]-ivy-[revision].xml</code>. If we check the <code>repository</code> directory, we can confirm that it contains a file named <code>commons-httpclient-ivy-2.0.2.xml</code>. This file matches the pattern, so it will be found by the resolver.</p> +</div> +<div class="paragraph"> +<p>The artifact resolver is simply an ibiblio one, configured in m2compatible mode to use the Maven 2 repository, with <code>usepoms="false"</code> 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.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_walkthrough_2">Walkthrough</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_step_1_preparation_2">Step 1 : Preparation</h3> +<div class="paragraph"> +<p>Open a shell (or command line) window, and go to the <code>dual</code> directory.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_step_2_clean_up">Step 2 : Clean up</h3> +<div class="paragraph"> +<p>On the prompt type : <code>ant</code></p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_step_3_run_the_project_2">Step 3 : Run the project</h3> +<div class="paragraph"> +<p>Go to the project directory. And simply run <code>ant</code>.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-shell" data-lang="shell">Unresolved directive in asciidoc/tutorial/dual.adoc - include::asciidoc/tutorial/log/dual.txt[]</code></pre> +</div> +</div> +<div class="paragraph"> +<p>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 <code>repository</code> directory:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code><ivy-module version="1.0"> + <info + organisation="commons-httpclient" + module="commons-httpclient" + revision="2.0.2" + status="release" + publication="20041010174300"/> + <dependencies> + <dependency org="commons-logging" name="commons-logging" rev="1.0.4" conf="default"/> + </dependencies> +</ivy-module></code></pre> +</div> +</div> +<div class="paragraph"> +<p>So everything seemed to work. The Ivy file was found in the <code>repository</code> directory and the artifacts have been downloaded from ibiblio.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>For full details about the dual resolver, have a look at the corresponding <a href="../resolver/dual.html">reference documentation</a>.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="__a_id_tutorial_dependence_a_project_dependencies"><a id="tutorial_dependence"></a>Project dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This tutorial will show you how to use Ivy when one of your projects depends on another.</p> +</div> +<div class="paragraph"> +<p>For our example, we will have two projects, depender and dependee, where the depender project uses/requires the dependee project. This example will help illustrate two things about Ivy:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>that dependencies defined by parent projects (dependee) will automatically be retrieved for use by child projects (depender)<br/></p> +</li> +<li> +<p>that child projects can retrieve the "latest" version of the dependee project<br/></p> +</li> +</ul> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_projects_used">Projects used</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_dependee">dependee</h3> +<div class="paragraph"> +<p>The dependee project is very simple. It depends on the Apache library commons-lang and contains only one class: <code>standalone.Main</code> which provides two services:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>return the version of the project<br/></p> +</li> +<li> +<p>capitalize a string using <code>org.apache.commons.lang.WordUtils.capitalizeFully</code><br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>Here is the content of the project:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>build.xml: the Ant build file for the project<br/></p> +</li> +<li> +<p>ivy.xml: the project Ivy file<br/></p> +</li> +<li> +<p>src/standalone/Main.java: the only class of the project<br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>Take a look at the <strong>ivy.xml</strong> file:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code><ivy-module version="1.0"> + <info organisation="org.apache" module="dependee"/> + <dependencies> + <dependency org="commons-lang" name="commons-lang" rev="2.0"/> + </dependencies> +</ivy-module></code></pre> +</div> +</div> +<div class="paragraph"> +<p>The Ivy file declares only one dependency, that being the Apache commons-lang library.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_depender">depender</h3> +<div class="paragraph"> +<p>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, <code>depending.Main</code>, which does 2 things:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>gets the version of the standalone project by calling <code>standalone.Main.getVersion()</code><br/></p> +</li> +<li> +<p>transforms a string by calling <code>standalone.Main.capitalizeWords(str)</code><br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>Take a look at the <code>ivy.xml</code> file:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code><ivy-module version="1.0"> + <info organisation="org.apache" module="depender"/> + <dependencies> + <dependency name="dependee" rev="latest.integration"/> + </dependencies> +</ivy-module></code></pre> +</div> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_settings">Settings</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The Ivy settings are defined in two files located in the settings directory:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><code>ivysettings.properties</code>: a property file<br/></p> +</li> +<li> +<p><code>ivysettings.xml</code>: the file containing the settings<br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>Let’s have a look at the <code>ivysettings.xml</code> file:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code><ivysettings> + <properties file="${ivy.settings.dir}/ivysettings.properties"/> + <settings defaultResolver="libraries"/> + <caches defaultCacheDir="${ivy.settings.dir}/ivy-cache"/> + <resolvers> + <filesystem name="projects"> + <artifact pattern="${repository.dir}/[artifact]-[revision].[ext]"/> + <ivy pattern="${repository.dir}/[module]-[revision].xml"/> + </filesystem> + <ibiblio name="libraries" m2compatible="true" usepoms="false"/> + </resolvers> + <modules> + <module organisation="org.apache" name="dependee" resolver="projects"/> + </modules> +</ivysettings></code></pre> +</div> +</div> +<div class="paragraph"> +<p>The file contains four main tags: properties, settings, resolvers and modules.</p> +</div> +<div class="sect2"> +<h3 id="_properties">properties</h3> +<div class="paragraph"> +<p>This tag loads some properties for the Ivy process, just like Ant does.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_settings_2">settings</h3> +<div class="paragraph"> +<p>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 <code>ivysettings.xml</code> file itself. +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>.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_resolvers">resolvers</h3> +<div class="paragraph"> +<p>This tag defines the resolvers to use. Here we have two resolvers defined: "projects" and "libraries". +The filesystem resolver called "projects" is able to resolve the internal dependencies by locating them on the local filesystem. +The ibiblio resolver called "libraries" is able to find dependencies on the Maven 2 repository, but doesn’t use Maven POMs.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_modules">modules</h3> +<div class="paragraph"> +<p>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 <code>org.apache</code> and module name of <code>dependee</code>. This actually corresponds to only one module, but a regular expression could be used, or many other types of expressions (like glob expressions).</p> +</div> +<div class="paragraph"> +<p>All other modules (i.e. all modules but org.apache#dependee), will use the default resolver ("libraries").</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_walkthrough_3">Walkthrough</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_step_1_preparation_3">Step 1: Preparation</h3> +<div class="paragraph"> +<p>Open a shell (or command line) window, and go to the <code>src/example/dependence</code> directory.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_step_2_clean_directory_tree_2">Step 2: Clean directory tree</h3> +<div class="paragraph"> +<p>At the prompt, type: <code>ant</code> +This will clean up the entire project directory tree. You can do this each time you want to clean up this example.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_step_3_publication_of_dependee_project">Step 3: Publication of dependee project</h3> +<div class="paragraph"> +<p>Go to <code>dependee</code> directory and publish the project</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-shell" data-lang="shell">Unresolved directive in asciidoc/tutorial/dependence.adoc - include::asciidoc/tutorial/log/dependence-standalone.txt[]</code></pre> +</div> +</div> +<div class="paragraph"> +<p>What we see here:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>the project depends on 1 library (1 artifact)<br/></p> +</li> +<li> +<p>the library was not in the Ivy cache and so was downloaded (1 downloaded)<br/></p> +</li> +<li> +<p>the project has been released under version number 1<br/></p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>As you can see, the call to the publish task has resulted in two main things:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>the delivery of a resolved Ivy file to <code>build/ivy.xml</code>.<br/> +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: <code>${build.dir}/[artifact].[ext]</code>. For an Ivy file, this resolves to <code>build/ivy.xml</code>. Because this file does not exist, it automatically makes a call to the deliver task which delivers a resolved Ivy file to this destination.</p> +</li> +<li> +<p>the publication of artifact 'dependee' and its resolved Ivy file to the repository.<br/> +Both are just copies of the files found in the current project, or more precisely, those in the <code>build</code> directory. This is because the artifactspattern has been set to <code>${build.dir}/[artifact].[ext]</code>, so the dependee artifact is found at <code>build/dependee.jar</code> and the Ivy file in <code>build/ivy.xml</code>. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to <code>repository/dependee-1.jar</code> and to <code>repository/dependee-1.xml</code>, respecting the artifact and Ivy file patterns of our settings (see above).</p> +</li> +</ul> +</div> +</div> +<div class="sect2"> +<h3 id="_step_4_running_the_depender_project">Step 4: Running the depender project</h3> +<div class="paragraph"> +<p>Go to directory depender and run <code>ant</code></p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlightjs highlight"><code class="language-shell" data-lang="shell">Unresolved directive in asciidoc/tutorial/dependence.adoc - include::asciidoc/tutorial/log/dependence-depending.txt[]</code></pre> +</div> +</div> +<div class="paragraph"> +<p>What we see here:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>the project depends on 2 libraries (2 artifacts)<br/></p> +</li> +<li> +<p>one of the libraries was in the cache because there was only 1 download (1 downloaded)<br/></p> +</li> +<li> +<p>Ivy retrieved version 1 of the project "dependee". The call to <code>standalone.Main.getVersion()</code> has returned 1. If you look in the <code>depender/lib</code> directory, you should see <code>dependee-1.jar</code> which is the version 1 artifact of the project "dependee"<br/></p> +</li> +<li> +<p>the call to <code>standalone.Main.capitalizeWords(str)</code> succeed, which means that the required library was in the classpath. If you look at the <code>lib</code> directory, you will see that the library <code>commons-lang-2.0.jar</code> was also retrieved. This library was declared as a dependency of the "dependee" project, so Ivy retrieves it (transitively) along with the dependee artifact.<br/></p> +</li> +</ul> +</div> +</div> +<div class="sect2">
[... 18286 lines stripped ...]
