You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ivy-commits@incubator.apache.org by xa...@apache.org on 2006/12/18 17:06:13 UTC
svn commit: r488342 [5/9] - in /incubator/ivy/trunk/src/doc/xooki: ./ doc/
doc/conf/ doc/configuration/ doc/configuration/macrodef/
doc/configuration/namespace/ doc/ivyfile/ doc/releasenotes/ doc/resolver/
doc/tutorial/ doc/tutorial/build-repository/ d...
Added: incubator/ivy/trunk/src/doc/xooki/doc/resolver/url.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/resolver/url.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/resolver/url.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/resolver/url.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,55 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 2};</script>
+ <script type="text/javascript" src="../../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+<table class="resolver">
+<tr><td class="title">Tag</td><td class="value">url</td></tr>
+<tr><td class="title">Handle latest</td><td class="value">yes with http urls (and apache server) and with file urls, no with other urls</td></tr>
+<tr><td class="title">Handle publish</td><td class="value">no</td></tr>
+</table>
+
+<br/>
+This resolver is one of the most generic, in fact most of the previous resolvers can be obtained by a particular configuration of this one. Indeed it uses urls to find ivy files and artifacts. The urls it uses are defined through ivy and artifact children, each giving a pattern to find ivy files or artifacts.
+
+<h1>Attributes</h1>
+This resolver shares the <a href="../../doc/configuration/resolvers#common.html">common attributes</a> of standard resolvers.
+<table class="ivy-attributes">
+<thead>
+ <tr><th class="ivy-att">Attribute</th><th class="ivy-att-desc">Description</th><th class="ivy-att-req">Required</th></tr>
+</thead>
+<tbody>
+ <tr><td>m2compatible</td><td>True if this resolver should be maven2 compatible, false otherwise <span class="since">since 1.3</span></td>
+ <td>No, defaults to false</td></tr>
+</tbody>
+</table>
+<h1>Child elements</h1>
+<table class="ivy-children">
+<thead>
+ <tr><th class="ivy-chld">Element</th><th class="ivy-chld-desc">Description</th><th class="ivy-chld-card">Cardinality</th></tr>
+</thead>
+<tbody>
+ <tr><td>ivy</td><td>defines a pattern for ivy files, using the pattern attribute</td>
+ <td>0..n</td></tr>
+ <tr><td>artifact</td><td>defines a pattern for artifacts, using the pattern attribute</td>
+ <td>1..n</td></tr>
+</tbody>
+</table>
+
+<h1>Example</h1>
+<code type="xml">
+<url name="two-patterns-example">
+ <ivy pattern="http://ivyrep.mycompany.com/[module]/[revision]/ivy-[revision].xml" />
+ <artifact pattern="http://ivyrep.mycompany.com/[module]/[revision]/[artifact]-[revision].[ext]" />
+ <artifact pattern="http://ivyrep.mycompany.com/[module]/[revision]/[artifact].[ext]" />
+</url>
+</code>
+Looks for ivy files in one place and for artifacts in two places: with or without revision in name (revision being already in the directory structure).
+
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/resolver/vfs.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/resolver/vfs.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/resolver/vfs.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/resolver/vfs.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,46 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 2};</script>
+ <script type="text/javascript" src="../../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+<table class="resolver">
+<tr><td class="title">Tag</td><td class="value">vfs</td></tr>
+<tr><td class="title">Handle latest</td><td class="value">depend on vfs capacity, usually yes</td></tr>
+<tr><td class="title">Handle publish</td><td class="value">depend on vfs capacity, usually yes</td></tr>
+</table>
+<br/>
+This resolver is certainly the most capable, since it relies on <a href="http://jakarta.apache.org/commons/vfs/">Apache commons VFS</a>, which gives an uniform access to <a href="http://jakarta.apache.org/commons/vfs/filesystems.html">a good number of file systems</a>, including ftp, webdav, zip, ... <span class="since">since 1.4</span>
+
+<i>Note: commons vfs has not released a stable version yet, hence Ivy relies on a nightly build. Stability should thus be considered carefully before using this resolver in a production environment</i>
+
+<h1>Attributes</h1>
+This resolver shares the <a href="../../doc/configuration/resolvers#common.html">common attributes</a> of standard resolvers.
+<h1>Child elements</h1>
+<table class="ivy-children">
+<thead>
+ <tr><th class="ivy-chld">Element</th><th class="ivy-chld-desc">Description</th><th class="ivy-chld-card">Cardinality</th></tr>
+</thead>
+<tbody>
+ <tr><td>ivy</td><td>defines a pattern for ivy files, using the pattern attribute</td>
+ <td>0..n</td></tr>
+ <tr><td>artifact</td><td>defines a pattern for artifacts, using the pattern attribute</td>
+ <td>1..n</td></tr>
+</tbody>
+</table>
+
+<h1>Example</h1>
+<code type="xml">
+<vfs name="vfs-resolver">
+ <ivy pattern="sftp://username:password@host/[organisation]/[module]/[revision]/ivy.xml" />
+ <artifact pattern="sftp://username:password@host/[organisation]/[module]/[revision]/[artifact].[ext]" />
+</vfs>
+</code>
+Access ivy and artifacts files using sftp.
+
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/standalone.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/standalone.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/standalone.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/standalone.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,75 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 1};</script>
+ <script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+In the case you want to call ivy as a standalone program (outside from ant), you have to put commons-cli 1.0 and its dependencies in your classpath.
+
+Then here is how to call it:
+<code>
+java fr.jayasoft.ivy.Main -?
+</code>
+It will indicate you what can be given as argument.
+
+
+<span class="since">since 1.3</span> System properties are included as ivy variables, so you can easily define an ivy variable like this:
+<code>
+java -Dmyivyvar=myvalue fr.jayasoft.ivy.Main [parameters]
+</code>
+
+
+<h1>Examples</h1>
+<code>
+java fr.jayasoft.ivy.Main
+</code>
+calls ivy with default configuration using ivy.xml in the current dir
+<hr/>
+<code>
+java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -ivy path/to/myivy.xml
+</code>
+calls ivy with given ivyconf file using given ivy file
+<hr/>
+<span class="since">since 1.3</span>
+<code>
+java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -dependency apache commons-lang 2.0
+</code>
+calls ivy with given ivyconf file and resolve apache commons-lang 2.0.
+
+This is equivalent to:
+<code>
+java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -ivy ivy.xml
+</code>
+with ivy.xml like this:
+<code type="xml">
+<ivy-module version="1.0">
+ <info organisation="org"
+ module="standalone"
+ revision="working"
+ />
+ <dependencies>
+ <dependency org="apache" name="commons-lang" rev="2.0" conf="default->*"/>
+ </dependencies>
+</ivy-module>
+</code>
+<hr/>
+<span class="since">since 1.3</span>
+<code>
+java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -ivy path/to/myivy.xml -cachepath mycachefile.txt
+</code>
+calls ivy with given ivyconf file and resolve the dependencies found in the given ivy file, and then output the classpath of resolved artifacts in cache in a file. This file can then be used to define a classpath corresponding to all the resolved dependencies for any java program.
+
+<hr/>
+<span class="since">since 1.4</span>
+<code>
+java fr.jayasoft.ivy.Main -conf path/to/myivyconf.xml -dependency bar foo 2.0 -main org.bar.foo.FooMain
+</code>
+calls ivy with given ivyconf file and resolve bar foo 2.0, and then run org.foo.FooMain class with the resolved artifacts as classpath
+
+
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/terminology.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/terminology.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/terminology.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/terminology.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,63 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 1};</script>
+ <script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+Here are some terms used in Ivy, with their definitions in Ivy:<br/>
+<h2>Ivy file</h2>
+An ivy file is an xml file which is used to describe dependencies of a module (see below). It is usually named ivy.xml.
+<h2>Configuration file</h2>
+Ivy configuration files are xml files used to configure ivy to indicate where the dependencies can be found. This should not be confused with a module configuration (see below).
+<h2>Organisation</h2>
+An organisation is either a company or a simple group of person
+which produce software. Ivy handle only one level of organisation, so you cannot
+describe a company hierarchy with this concept. But it is used to group sofware
+produced by a same team, just to help find and classify them.<br/>
+<i>Examples: apache, ibm, jayasoft</i>
+<h2>Module</h2>
+A module in ivy is a piece of software that is reusable, and that
+follow a unique cycle of revision. <br/>
+<i>Examples: hibernate, ant, ...</i>
+<h2>Artifact</h2>
+An artifact is a single file produced by a company when releasing a module. In
+the java world, common artifacts are jars. In many cases, each revision of a
+module publish only one artifact (like log4j, for instance), but some of them
+publish many artifacts dependending on the use of the module (like ant, for instance).
+<h2>Revision</h2>
+A revision corresponds to one delivery of a module. It can either be a delivery
+of a release, a milestone, a beta version, a nightly build, or even a continuous
+build. All of them are considered revisions in ivy.
+<h2><a name="branch">Branch</a></h2>
+A branch corresponds to the standard meaning of a branch (or sometimes stream) in source control management tools.
+The head, or trunk, or main stream, is also considered as a branch in Ivy.
+<h2>Configuration</h2>
+A module configuration is a way to use or construct a module. Some modules may be
+used in different ways (think about hibernate which can be used inside or outside
+an application server), and this way may alter the artifacts you need (in the case
+of hibernate, jta.jar is needed only if it is used outside an application server).
+Moreover, a module may need some other modules and artifacts only at build time,
+and some others at runtime. All those differents ways to use or build a module
+are called in ivy configurations. <br/><br/>
+
+For more details on configurations and how they are used in ivy, please refer to the <a href="../doc/concept.html">main concepts page</a>.
+<h2>Status</h2>
+A module status indicates how stable a module revision can be considered. It can
+be used to consolidate the status of all the dependencies of a module, to prevent
+the use of an integration revision of a dependency in the release of your module.
+Three statuses are defined by default in ivy:
+<ul>
+<li>integration: revisions builded by a continuous build, a nightly build, and so on, fall in this category</li>
+<li>milestone: revisions delivered to the public but not actually finished fall in this category</li>
+<li>release: revision fully tested and labelled fall in this category</li>
+</ul>
+<span class="since">since 1.4</span> This list is <a href="../doc/configuration/statuses.html">configurable</a> in your configuration file.
+<h2>Repository</h2>
+What is called a repository in Ivy is a location where Ivy is able to find your modules artifacts and metadata (i.e. ivy files in most cases).
+Ivy can be used with complex repositories configured very finely. You can use <a href="../doc/concept.html">Dependency Resolvers</a> to do so.
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/tutorial.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/tutorial.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/tutorial.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/tutorial.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,43 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 1};</script>
+ <script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+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>.
+
+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.2 or greater and a <a href="http://java.sun.com">jdk</a> properly installed</li>
+<li>copy <a href="http://svn.jayasoft.org/projects/tools/ivy/src/example/go-ivy/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?).
+
+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="../doc/install.html">installed</a> ivy and downloaded the tutorials sources (included in all ivy distributions, in the src/example directory).
+
+The following tutorials are available:
+<ul>
+<li><a href="../doc/tutorial/start.html">Quick Start</a></li>
+guide you through your very first steps with ivy.
+<li><a href="../doc/tutorial/ivyrep.html">Using IvyRep</a></li>
+show you the out of the box power of ivy + ivyrep.
+<li><a href="../doc/tutorial/defaultconf.html">Configuring default resolver</a></li>
+give you a better understanding of the default configuration and show you how to customize it to your needs.
+<li><a href="../doc/tutorial/multiple.html">Multiple Resolvers</a></li>
+teach you how to configure Ivy to find its dependencies in multiple places.
+<li><a href="../doc/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="../doc/tutorial/multi-project.html">Project Dependencies</a></li>
+makes you touch the interest of using ivy in multi project environment.
+<li><a href="../doc/tutorial/conf.html">Using Ivy Configurations</a></li>
+show how to use configurations in ivy file to define set of artifacts.
+<li><a href="../doc/tutorial/build-repository.html">Building a repository</a></li>
+show how to build your own enterprise repository.
+</ul>
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,42 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 2};</script>
+ <script type="text/javascript" src="../../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+With the <a href="../../doc/use/install.html">install</a> ant task you are given the possibility to copy ivy descriptors and artifacts found from a resolver and publish them into another resolver.<br/>
+
+This tutorial will show you how to build your own clean enterprise repository of ivy descriptors and modules artifacts.
+We will first use some basic ivy configuration files to show how it works, and then we will use advanced features like <a href="../../doc/configuration/namespaces.html">namespaces</a> to build a real enterprise repository.
+
+<h1>The project used</h1>
+The project that we will use is quite simple.
+It is compouned of an ant build file, and some ivy conf files.
+
+Here are the accessible target that we will use :
+<div class="shell"><pre>
+Z:\ivy-repository>ant -p
+Buildfile: build.xml
+
+Main targets:
+
+ advanced --> retrieve files from public repositories (ivyrep, ibiblio, ...) using namespaces
+ basic --> retrieve files from well formatted ivy repositories
+ basic-deps --> retrieve files from well formatted ivy repositories with dependencies
+ clean-cache --> clean the cache
+ clean-repo --> clean the destination repository
+ commons-lang-1-0-ibiblio-no-namespace --> retrieve commons-lang 1.0 from ibiblio maven using no namespaces
+ commons-lang-1-0-ibiblio-with-namespace --> retrieve commons-lang 1.0 from ibiblio maven using namespaces
+ maven1 --> retrieve commons-lang 1.0 from maven1 repo using namespaces
+ maven2 --> retrieve files from maven2 repo using namespaces
+Default target: basic</pre></div>
+<br/><br/>
+The project is accessible in the <a href="/latest/ivy">sources</a> of Ivy into : IVY_HOME/src/example/build-a-ivy-repository
+
+
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/advanced1.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/advanced1.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/advanced1.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/advanced1.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,186 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 3};</script>
+ <script type="text/javascript" src="../../../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+<h1>On the road to a professional repository</h1>
+We will study in this section how to build a <strong>professionnal</strong> repository. What is a <strong>professionnal</strong> dependency resolver ? Our vision is to say that a good quality repository must follow clear rules about projects naming and must offer corrects, usuables, configurables and verified project descriptors. In order to achieve those goals, we think that you have to build your own repository.
+We have seen in the previous example, that we could use some public repositories to begin to build our own repository.
+Nevertheless, the result is not at all the one that was excepected. Indeed there is a problem with public repositories : their partial incompatibility.
+For example, in <a href="http://ivyrep.jayasoft.org">ivyrep</a> all commons-* projects belong to the apache organisation. In both ibiblio versions, it is not the case. The same problem could appear for other projects with other repositories, it is not the debate here.
+
+To resolve some of the incompatibilities, we will use a new feature of <a href="/ivy">ivy</a> 1.3 the <a href="/ivy">namespaces</a>.
+
+<h1>Using namespaces</h1>
+In order to use namespaces, we first need to see what's happening when none are used on repositories that do not fit our needs.
+Let's take commons-lang 1.0 from ibiblio with a maven2 pom.
+First clean your cache and repository.
+<div class="shell"><pre>Z:\ivy-repository>ant clean-cache clean-repo</pre></div>
+Then call the good ant target : ant commons-lang-1-0-ibiblio-no-namespace
+<div class="shell"><pre>Z:\ivy-repository>ant commons-lang-1-0-ibiblio-no-namespace
+Buildfile: build.xml
+
+init-advanced:
+:: Ivy 20060125070719 - 20060125070719 :: http://ivy.jayasoft.org/ ::
+:: configuring :: file = Z:\ivy-repository\ivy-conf-advanced.xml
+
+commons-lang-1-0-ibiblio-no-namespace:
+:: installing [ commons-lang | commons-lang | 1.0 ] ::
+:: resolving dependencies ::
+ found [ commons-lang | commons-lang | 1.0 ] in ibiblio-maven2-nonamespace
+ found [ junit | junit | 3.7 ] in ibiblio-maven2-nonamespace
+:: downloading artifacts to cache ::
+downloading http://www.ibiblio.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0.jar ...
+.............. (62kB)
+ [SUCCESSFUL ] [ commons-lang | commons-lang | 1.0 ]/commons-lang.jar[jar] (1313ms)
+downloading http://www.ibiblio.org/maven2/junit/junit/3.7/junit-3.7.jar ...
+.............
+.............. (114kB)
+ [SUCCESSFUL ] [ junit | junit | 3.7 ]/junit.jar[jar] (2360ms)
+:: installing in local-repository ::
+ published commons-lang to Z:\ivy-repository/ivy-local-repository/commons-lang/commons-lang/jars/commons-lang-1.0.jar
+ published ivy to Z:\ivy-repository/ivy-local-repository/commons-lang/commons-lang/ivys/ivy-1.0.xml
+ published junit to Z:\ivy-repository/ivy-local-repository/junit/junit/jars/junit-3.7.jar
+ published ivy to Z:\ivy-repository/ivy-local-repository/junit/junit/ivys/ivy-3.7.xml
+:: install resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | default | 2 | 2 | 2 | 0 || 2 | 2 |
+ ---------------------------------------------------------------------
+
+BUILD SUCCESSFUL
+Total time: 6 seconds
+Z:\ivy-repository></pre></div>
+If we take a look at the repository, we can see that we respect the ibiblio maven2 architecture, the organisation apache does not appear.
+<div class="shell"><pre>Z:\ivy-repository>dir /s /B /A:-D ivy-local-repository
+Z:\ivy-repository\ivy-local-repository\commons-lang\commons-lang\ivys\ivy-1.0.xml
+Z:\ivy-repository\ivy-local-repository\commons-lang\commons-lang\jars\commons-lang-1.0.jar
+Z:\ivy-repository\ivy-local-repository\junit\junit\ivys\ivy-3.7.xml
+Z:\ivy-repository\ivy-local-repository\junit\junit\jars\junit-3.7.jar</pre></div>
+If you take a look at the ivy descriptor for commons-lang, you will see that the organisation is still commons-lang. It could not be another thing as we did not do anything for it.
+<div><code type="xml">
+<ivy-module version="1.0">
+ <info organisation="commons-lang"
+ module="commons-lang"
+ revision="1.0"
+ status="integration"
+ publication="20051124062021"
+ />
+</code></div>
+
+<h2>Introduction to namespaces</h2>
+Let's see directly the result, we will have some explanations after.
+Clean your repo and cache, and call : ant commons-lang-1-0-ibiblio-with-namespace
+<div class="shell"><pre>Z:\ivy-repository>ant commons-lang-1-0-ibiblio-with-namespace
+Buildfile: build.xml
+
+init-advanced:
+:: Ivy non official version :: http://ivy.jayasoft.org/ ::
+:: configuring :: file = Z:\ivy-repository\ivy-conf-advanced.xml
+
+commons-lang-1-0-ibiblio-with-namespace:
+:: installing [ apache | commons-lang | 1.0 ] ::
+:: resolving dependencies ::
+ found [ apache | commons-lang | 1.0 ] in ibiblio-maven2
+ found [ junit | junit | 3.7 ] in ibiblio-maven2
+:: downloading artifacts to cache ::
+downloading http://www.ibiblio.org/maven2/commons-lang/commons-lang/1.0/commons-lang-1.0.jar ...
+............. (62kB)
+ [SUCCESSFUL ] [ apache | commons-lang | 1.0 ]/commons-lang.jar[jar] (1094ms)
+downloading http://www.ibiblio.org/maven2/junit/junit/3.7/junit-3.7.jar ...
+............................ (114kB)
+ [SUCCESSFUL ] [ junit | junit | 3.7 ]/junit.jar[jar] (1641ms)
+:: installing in local-repository ::
+ published commons-lang to Z:\ivy-repository/ivy-local-repository/apache/commons-lang/jars/commons-lang-1.0.jar
+ published ivy to Z:\ivy-repository/ivy-local-repository/apache/commons-lang/ivys/ivy-1.0.xml
+ published junit to Z:\ivy-repository/ivy-local-repository/junit/junit/jars/junit-3.7.jar
+ published ivy to Z:\ivy-repository/ivy-local-repository/junit/junit/ivys/ivy-3.7.xml
+:: install resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | default | 2 | 2 | 2 | 0 || 2 | 2 |
+ ---------------------------------------------------------------------
+
+BUILD SUCCESSFUL
+Total time: 5 seconds</pre></div>
+Now if we look at our repository, it seems to look fine.
+<div class="shell"><pre>Z:\ivy-repository>dir /s /B /A:-D ivy-local-repository
+Z:\ivy-repository\ivy-local-repository\apache\commons-lang\ivys\ivy-1.0.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-lang\jars\commons-lang-1.0.jar
+Z:\ivy-repository\ivy-local-repository\junit\junit\ivys\ivy-3.7.xml
+Z:\ivy-repository\ivy-local-repository\junit\junit\jars\junit-3.7.jar</pre></div>
+Have a look at the ivy file to see it it looks better than before. Ok, we have now our apache organisation.
+<div><code type="xml">
+<ivy-module version="1.0">
+ <info organisation="apache"
+ module="commons-lang"
+ revision="1.0"
+ status="integration"
+ publication="20051124062021"
+ />
+</code></div>
+<h2>How does this work ?</h2>
+If we look at the ant target commons-lang-1-0-ibiblio-with-namespace, we can see that it uses a resolver called ibiblio-maven2.
+Let's find it... The configuration file used for this test is ivy-conf-advanced.xml. This one includes ivy-maven2-ivyconf.xml where the required resolver is defined.
+Let's see it's definition :
+<code type="xml"><ibiblio name="ibiblio-maven2"
+ root="${ibiblio-maven2-root}"
+ pattern="${ibiblio-maven2-pattern}"
+ m2compatible="true"
+ namespace="ibiblio-maven2"
+/></code>Ok, i see it, it is a ibiblio resolver for which we specify the root and the pattern. The important things here are the 2 other parameters.
+<ul><li><b>m2compatible</b> is a flag telling that we allow reading POMs file and make some transformations on URLs regarding the organisation name. Indeed, maven transforms organisations like "org.apache" into "some_url/org/apache" to retrieve information on ibiblio repositories.</li>
+<li><b>namespace</b> this attribute defines a domain in which same projects (meanning organsiation, module or revision) can be nammed whith differents kinds.</li></ul>
+
+A namespace is defined by a set of rule, for ibiblio-maven2, whe have declared some rules :
+<h3>rule handling imported apache maven1 projects</h3>
+<code type="xml"><rule> <!-- imported apache maven1 projects -->
+ <fromsystem>
+ <src org="apache" module=".+"/>
+
+ <dest org="$m0" module="$m0"/>
+ </fromsystem>
+ <tosystem>
+ <src org="commons-.+" module="commons-.+" />
+ <src org="ant.*" module="ant.*" />
+ ...
+ <src org="xmlrpc" module="xmlrpc" />
+
+ <dest org="apache" module="$m0"/>
+ </tosystem>
+</rule></code>
+<div class="postit"><u>Note about regular expressions usage :</u>
+In order to distinguish matching regular expressions found in organisation, module & revision the notation used prefixes the matching regular expression with the letters 'o', 'm' & 'r'.
+$o0 : the whole regular expression term in the organisation attribute
+$o1 : the first matching expression term that was marked in the organisation attribute
+...
+The same applies for modules : $m0, $m1, ...
+and for revisions : $r0, $r1, ...
+</div>
+<ul>
+<li><b>fromsystem :</b> we define here that the projects defined in the system under the organisation called "apache" are transformed into the destination namespace (whose resolver it applies) into projects whose organisation is nammed with the module name, we don't care here about the revision. For example, the project ['apache', 'commons-lang', '1.0'] in the namespace system will be translated into ['commons-lang', 'commons-lang', '1.0'] in the ibiblio-maven2 resolver namespace.</li>
+<li><b>tosystem :</b> we define here the reverse mapping, ie how to translate <em>apache</em> projects from ibiblio into real apache projects in the namespace system. The rule here, is telling that all projects matching commons-.+ (see it as java regular expression) for their organisation name and module name are transformed into projects whose organisation is apache with the module name as it was found. The same kind of rule is applied for others apache projects like ant, etc. For example, ['ant','ant','1.6.2'] in ibiblio-maven2 namespace will become ['apache','ant','1.6.2'] int the system namespace.</li>
+</ul>
+<h3>rule handling new apache projects</h3>
+<code type="xml"><rule> <!-- new apache projects -->
+ <fromsystem>
+ <src org="apache" />
+ <dest org="org.apache"/>
+ </fromsystem>
+ <tosystem>
+ <src org="org.apache" />
+ <dest org="apache" />
+ </tosystem>
+</rule></code>
+The mapping adds or removes the package 'org' before the organisation name to conform to maven2 choices.
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/advanced2.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/advanced2.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/advanced2.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/advanced2.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,181 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 3};</script>
+ <script type="text/javascript" src="../../../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+<h1>Building the professional repository</h1>
+Now that we have been well prepared, let's go to a real life example of building our repository.
+We will now focus on a bigger example that uses different public repositories to retrieve the information.
+In this tutorial we will use, in order of preference :<ul><li>our home made repository</li><li>ivyrep official</li><li>ibiblio maven2</li></ul>
+<h2>the resolvers used</h2>
+<code type="xml"><resolvers>
+ <filesystem name="local-repository">
+ <ivy pattern="${dest.repo.dir}/[organisation]/[module]/ivys/ivy-[revision].xml"/>
+ <artifact pattern="${dest.repo.dir}/[organisation]/[module]/[type]s/[artifact]-[revision].[type]"/>
+ </filesystem>
+
+ <chain name="libraries" returnFirst="false">
+ <resolver ref="local-repository" />
+ <ivyrep name="official-ivy-rep"/>
+ <resolver ref="ibiblio-maven2" />
+ </chain>
+</resolvers>
+</code>
+We start the chain with our home made repository because as we can expect, we consider this repository as good ivy file repository (that's why we create it). So all files that are in this repository are considered as valid and correct and usuable.
+The building process is then an iterative process.
+After each import of new projects into our repository, we check and modify the generated ivy files (or you do not as you want). The generated ivy files are those that were translated from a POM or those for which an artifact has been found without a module descriptor (ivy or pom).
+
+<h2>Let's go</h2>
+What about to test our configuration with a big project : hibernate 3.0
+Just run : ant advanced
+
+Here we go !!!!!!!!
+
+<div class="shell"><pre>Z:\build-a-ivy-repository>ant advanced
+Buildfile: build.xml
+
+init-advanced:
+:: Ivy non official version :: http://ivy.jayasoft.org/ ::
+:: configuring :: file = Z:\build-a-ivy-repository\config\ivy-conf-advanced.xml
+
+advanced:
+:: installing [ hibernate | hibernate | 3.0 ] ::
+:: resolving dependencies ::
+ found [ hibernate | hibernate | 3.0 ] in ibiblio-maven2
+ found [ apache | commons-logging | 1.0.4 ] in official-ivy-rep
+ found [ apache | ant | 1.6.3 ] in ibiblio-maven2
+ found [ c3p0 | c3p0 | 0.8.4.5 ] in official-ivy-rep
+ found [ proxool | proxool | 0.8.3 ] in official-ivy-rep
+ found [ ehcache | ehcache | 1.1 ] in official-ivy-rep
+ found [ apache | xerces | 2.5.0 ] in official-ivy-rep
+ found [ apache | commons-collections | 2.1.1 ] in official-ivy-rep
+ found [ opensymphony | oscache | 2.1 ] in ibiblio-maven2
+ found [ swarmcache | swarmcache | 1.0RC2 ] in official-ivy-rep
+ found [ apache | commons-collections | 2.1 ] in official-ivy-rep
+ found [ apache | commons-logging | 1.0.2 ] in official-ivy-rep
+ found [ jgroups | jgroups | 2.2 ] in official-ivy-rep
+ found [ jboss | jboss-cache | 1.2.2 ] in ibiblio-maven2
+ found [ jboss | jboss-system | 4.0.2 ] in ibiblio-maven2
+ found [ jboss | jboss-common | 4.0.2 ] in ibiblio-maven2
+ found [ jboss | jboss-minimal | 4.0.2 ] in ibiblio-maven2
+ found [ jboss | jboss-j2se | 200504122039 ] in ibiblio-maven2
+ found [ concurrent | concurrent | 1.3.4 ] in ibiblio-maven2
+ found [ jgroups | jgroups-all | 2.2.7 ] in ibiblio-maven2
+ found [ cglib | cglib | 2.0.2 ] in official-ivy-rep
+ found [ objectweb | asm | 1.3.4 ] in official-ivy-rep
+ found [ asm | asm | 1.4.3 ] in ibiblio-maven2
+ found [ javax.security | jacc | 1.0 ] in ibiblio-maven2
+ found [ dom4j | dom4j | 1.6 ] in ibiblio-maven2
+ found [ javax.transaction | jta | 1.0.1B ] in ibiblio-maven2
+ found [ hibernate | antlr | 2.7.5H3 ] in ibiblio-maven2
+ found [ odmg | odmg | 3.0 ] in official-ivy-rep
+:: downloading artifacts to cache ::
+downloading http://www.ibiblio.org/maven2/hibernate/hibernate/3.0/hibernate-3.0.jar ...
+..................................................
+.. (1565kB)
+ [SUCCESSFUL ] [ hibernate | hibernate | 3.0 ]/hibernate.jar[jar] (8500ms)
+downloading http://www.ibiblio.org/maven2/hibernate/antlr/2.7.5H3/antlr-2.7.5H3.jar ...
+
+ SOME MINUTES LATER !!!!!!!!!!
+
+downloading http://www.ibiblio.org/maven/commons-logging/jars/commons-logging-1.0.4.jar ...
+........ (37kB)
+ [SUCCESSFUL ] [ apache | commons-logging | 1.0.4 ]/commons-logging.jar[jar] (1110ms)
+:: installing in local-repository ::
+ published hibernate to Z:\build-a-ivy-repository/ivy-local-repository/hibernate/hibernate/jars/hibernate-3.0.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/hibernate/hibernate/ivys/ivy-3.0.xml
+ published antlr to Z:\build-a-ivy-repository/ivy-local-repository/hibernate/antlr/jars/antlr-2.7.5H3.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/hibernate/antlr/ivys/ivy-2.7.5H3.xml
+ published dom4j to Z:\build-a-ivy-repository/ivy-local-repository/dom4j/dom4j/jars/dom4j-1.6.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/dom4j/dom4j/ivys/ivy-1.6.xml
+missing artifact [ javax.security | jacc | 1.0 ]/jacc.jar[jar]: Z:\build-a-ivy-repository\cache\javax.security\jacc\jars\jacc-1.0.jar file does not exist
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/javax.security/jacc/ivys/ivy-1.0.xml
+ published asm to Z:\build-a-ivy-repository/ivy-local-repository/asm/asm/jars/asm-1.4.3.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/asm/asm/ivys/ivy-1.4.3.xml
+ published cglib-full to Z:\build-a-ivy-repository/ivy-local-repository/cglib/cglib/jars/cglib-full-2.0.2.jar
+ published cglib to Z:\build-a-ivy-repository/ivy-local-repository/cglib/cglib/jars/cglib-2.0.2.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/cglib/cglib/ivys/ivy-2.0.2.xml
+ published asm to Z:\build-a-ivy-repository/ivy-local-repository/objectweb/asm/jars/asm-1.3.4.jar
+ published asm-util to Z:\build-a-ivy-repository/ivy-local-repository/objectweb/asm/jars/asm-util-1.3.4.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/objectweb/asm/ivys/ivy-1.3.4.xml
+ published jboss-cache to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-cache/jars/jboss-cache-1.2.2.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-cache/ivys/ivy-1.2.2.xml
+ published jgroups-all to Z:\build-a-ivy-repository/ivy-local-repository/jgroups/jgroups-all/jars/jgroups-all-2.2.7.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jgroups/jgroups-all/ivys/ivy-2.2.7.xml
+ published concurrent to Z:\build-a-ivy-repository/ivy-local-repository/concurrent/concurrent/jars/concurrent-1.3.4.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/concurrent/concurrent/ivys/ivy-1.3.4.xml
+ published jboss-j2se to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-j2se/jars/jboss-j2se-200504122039.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-j2se/ivys/ivy-200504122039.xml
+ published jboss-minimal to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-minimal/jars/jboss-minimal-4.0.2.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-minimal/ivys/ivy-4.0.2.xml
+ published jboss-system to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-system/jars/jboss-system-4.0.2.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-system/ivys/ivy-4.0.2.xml
+ published swarmcache to Z:\build-a-ivy-repository/ivy-local-repository/swarmcache/swarmcache/jars/swarmcache-1.0RC2.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/swarmcache/swarmcache/ivys/ivy-1.0RC2.xml
+missing artifact [ jgroups | jgroups | 2.2 ]/jgroups.jar[jar]: Z:\build-a-ivy-repository\cache\jgroups\jgroups\jars\jgroups-2.2.jar file does not exist
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jgroups/jgroups/ivys/ivy-2.2.xml
+ published commons-logging to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-logging/jars/commons-logging-1.0.2.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-logging/ivys/ivy-1.0.2.xml
+ published oscache to Z:\build-a-ivy-repository/ivy-local-repository/opensymphony/oscache/jars/oscache-2.1.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/opensymphony/oscache/ivys/ivy-2.1.xml
+ published c3p0 to Z:\build-a-ivy-repository/ivy-local-repository/c3p0/c3p0/jars/c3p0-0.8.4.5.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/c3p0/c3p0/ivys/ivy-0.8.4.5.xml
+ published odmg to Z:\build-a-ivy-repository/ivy-local-repository/odmg/odmg/jars/odmg-3.0.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/odmg/odmg/ivys/ivy-3.0.xml
+ published proxool to Z:\build-a-ivy-repository/ivy-local-repository/proxool/proxool/jars/proxool-0.8.3.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/proxool/proxool/ivys/ivy-0.8.3.xml
+missing artifact [ javax.transaction | jta | 1.0.1B ]/jta.jar[jar]: Z:\build-a-ivy-repository\cache\javax.transaction\jta\jars\jta-1.0.1B.jar file does not exist
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/javax.transaction/jta/ivys/ivy-1.0.1B.xml
+ published jboss-common to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-common/jars/jboss-common-4.0.2.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/jboss/jboss-common/ivys/ivy-4.0.2.xml
+ published ant to Z:\build-a-ivy-repository/ivy-local-repository/apache/ant/jars/ant-1.6.3.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/ant/ivys/ivy-1.6.3.xml
+ published commons-collections to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-collections/jars/commons-collections-2.1.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-collections/ivys/ivy-2.1.xml
+ published ehcache to Z:\build-a-ivy-repository/ivy-local-repository/ehcache/ehcache/jars/ehcache-1.1.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/ehcache/ehcache/ivys/ivy-1.1.xml
+ published commons-collections to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-collections/jars/commons-collections-2.1.1.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-collections/ivys/ivy-2.1.1.xml
+ published xercesImpl to Z:\build-a-ivy-repository/ivy-local-repository/apache/xerces/jars/xercesImpl-2.5.0.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/xerces/ivys/ivy-2.5.0.xml
+ published commons-logging to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-logging/jars/commons-logging-1.0.4.jar
+ published ivy to Z:\build-a-ivy-repository/ivy-local-repository/apache/commons-logging/ivys/ivy-1.0.4.xml
+:: install resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | default | 28 | 28 | 28 | 0 || 30 | 27 |
+ ---------------------------------------------------------------------
+
+BUILD SUCCESSFUL
+Total time: 2 minutes 10 seconds
+Z:\build-a-ivy-repository></pre></div>
+
+<h2>Analysing the results</h2>
+OK, it seems that we have a good start point for our repository.
+As you can see in the resolving part of the process :
+<div class="shell"><pre>:: resolving dependencies ::
+ found [ hibernate | hibernate | 3.0 ] in ibiblio-maven2
+ found [ apache | commons-logging | 1.0.4 ] in official-ivy-rep
+ ...
+ found [ odmg | odmg | 3.0 ] in official-ivy-rep</pre></div>
+some ivy files were retrieved from the <a href="http://ivyrep.jayasoft.org">ivyrep</a> the official ivy repository. That significates that for these modules, you have in your home made repository good ivy files (with meaningfull configurations, ...).
+
+<h2>And now</h2>
+Now what you need to do is to download missing artifacts, those not on ibiblio (from sun, ...) and correct the generated ivy files.
+It is important to make a review of the generated ivy files because you could then benefit from all the power of ivy by defining for those projects good configurations and some other good things.
+
+To ease finding generated files, just take a look at the generated resolve report in your cache. You will find there the projects for which a default ivy file was generated
+<center><img src="/misc/ivy/samples/commons-lang1.0-dep-report-part.jpg" style="padding:1em;"/></center>
+and you can see the resolvers that have resolved the modules. In our example, you will update the files whose project were resolved by the ibiblio-maven2 resolver.
+<center><img src="/misc/ivy/samples/hibernate3.0-dep-report-part.jpg" style="padding:1em;"/></center>
+
+
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/basic.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/basic.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/basic.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/tutorial/build-repository/basic.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,209 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 3};</script>
+ <script type="text/javascript" src="../../../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+!!!! UNDER CONSTRUCTION !!!!
+
+
+
+We will study here two cases, corresponding to the two basics targets found in the previous build.xml project file.
+
+<h1>Basic : ivyconf.xml file used</h1>
+The ivy conf file that we will use is very simple here. It defines two resolvers, libraries and local-repository. The first one is used to retrieve the files that we want, the second is used to copy them. The second one will become our own repository.
+<ul>
+<li>ivyrep : nothing special on it, ivy files will be looked for on ivyrep and artifacts will be downloaded from
+ibilio</li>
+<li>local-repository : will store the found files</li>
+</ul>
+
+<div class="ivy-file">
+<code type="xml">
+<ivyconf>
+ <conf defaultCache="${ivy.cache.dir}"
+ defaultResolver="local-repository"
+ defaultConflictManager="all" /> <!-- in order to get all revisions without any eviction -->
+ <resolvers>
+ <ivyrep name="libraries" />
+ <filesystem name="local-repository">
+ <ivy pattern="${dest.repo.dir}/[organisation]/[module]/ivys/ivy-[revision].xml"/>
+ <artifact pattern="${dest.repo.dir}/[organisation]/[module]/[type]s/[artifact]-[revision].[type]"/>
+ </filesystem>
+ </resolvers>
+</ivyconf>
+</code>
+</div>
+
+<h1>basic, retrieve commons-lang 1.0</h1>
+Let's have a look at the <em>basic</em> target.
+<code type="xml">
+ <target name="basic" depends="init-basic" description="--> retrieve files from well formatted ivy repositories">
+ <ivy:install organisation="apache" module="commons-lang" revision="1.0" from="${from-resolver}" to="${to-resolver}" />
+ </target>
+</code>
+After a call to init-basic, that make the ivy initialization with the right ivyconf file, we only call the task <a href="../../../doc/use/install.html">install</a> to retrieve apache commons-lang in it's 1.0 version.
+Here is the ant call output :
+<div class="shell"><pre>Z:\ivy-repository>ant basic
+Buildfile: build.xml
+
+init-basic:
+:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
+:: configuring :: file = Z:\ivy-repository\ivy-conf-basic.xml
+
+basic:
+:: installing [ apache | commons-lang | 1.0 ] ::
+:: resolving dependencies ::
+ found [ apache | commons-lang | 1.0 ] in libraries
+:: downloading artifacts to cache ::
+downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-1.0.jar ...
+............ (62kB)
+ [SUCCESSFUL ] [ apache | commons-lang | 1.0 ]/commons-lang.jar[jar] (1203ms)
+:: installing in local-repository ::
+ published commons-lang to Z:\ivy-repository/ivy-local-repository/apache/commons-lang/jars/commons-lang-1.0.jar
+ published ivy to Z:\ivy-repository/ivy-local-repository/apache/commons-lang/ivys/ivy-1.0.xml
+
+BUILD SUCCESSFUL
+Total time: 2 seconds</pre></div>
+The trace tells us that the module definition was found using the "libraries" resolver and that the corresponding artifact was downloaded from ibiblio. Then both were published in the local repository.
+
+If we take a look at our repository :
+<div class="shell"><pre>Z:\ivy-repository>dir /s /B /A:-D ivy-local-repository
+Z:\ivy-repository\ivy-local-repository\apache\commons-lang\ivys\ivy-1.0.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-lang\jars\commons-lang-1.0.jar
+Z:\ivy-repository></pre>
+</div>
+We can see that we have started our own repository by retrieving the commons-lang 1.0 ivy file descriptor and jar.
+<h1>basic with dependencies, retrieve hibernate 2.1.8</h1>
+Now let's advance a little more by trying a module that has some dependencies. Here is the target that we will call :
+<code type="xml">
+ <target name="basic-deps" depends="init-basic" description="--> retrieve files from well formatted ivy repositories with dependencies">
+ <ivy:install organisation="hibernate" module="hibernate" revision="2.1.8" from="${from-resolver}" to="${to-resolver}" transitive="true" />
+ </target>
+</code>This target is very similar to the basic one, except it defines the transitivity mode to use. By writing, <em>transitive="true"</em>, we tell the task to retrieve the corresponding module and it's dependencies.
+
+Ok let's call the target :
+<div class="shell"><pre>Z:\ivy-repository>ant basic-deps
+Buildfile: build.xml
+
+init-basic:
+:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
+:: configuring :: file = Z:\ivy-repository\ivy-conf-basic.xml
+
+basic-deps:
+:: installing [ hibernate | hibernate | 2.1.8 ] ::
+:: resolving dependencies ::
+ found [ hibernate | hibernate | 2.1.8 ] in libraries
+ found [ cglib | cglib | 2.0.2 ] in libraries
+ found [ apache | commons-collections | 2.1.1 ] in libraries
+ found [ apache | commons-logging | 1.0.4 ] in libraries
+ found [ dom4j | dom4j | 1.4 ] in libraries
+ found [ ehcache | ehcache | 0.9 ] in libraries
+ found [ odmg | odmg | 3.0 ] in libraries
+ found [ sun | jta | 1.0 ] in libraries
+ found [ apache | xalan | 2.4.0 ] in libraries
+ found [ apache | xerces | 2.4.0 ] in libraries
+ found [ sun | jdbc | 2.0 ] in libraries
+ found [ sun | jca | 1.0 ] in libraries
+ found [ sun | jaas | 1.0 ] in libraries
+ found [ c3p0 | c3p0 | 0.8.4.5 ] in libraries
+ found [ apache | commons-dbcp | 1.2.1 ] in libraries
+ found [ apache | commons-pool | 1.2 ] in libraries
+ found [ apache | commons-collections | 2.1 ] in libraries
+ found [ apache | xerces | 2.0.2 ] in libraries
+ found [ proxool | proxool | 0.8.3 ] in libraries
+ found [ jboss | jboss-cache | 1.1.1 ] in libraries
+ found [ opensymphony | oscache | 2.0 ] in libraries
+ found [ apache | commons-logging | 1.0.3 ] in libraries
+ found [ swarmcache | swarmcache | 1.0RC2 ] in libraries
+ found [ apache | commons-logging | 1.0.2 ] in libraries
+ found [ jgroups | jgroups | 2.2 ] in libraries
+:: downloading artifacts to cache ::
+downloading http://www.ibiblio.org/maven/hibernate/jars/hibernate-2.1.8.jar ...
+...........
+............
+.. (944kB)
+ [SUCCESSFUL ] [ hibernate | hibernate | 2.1.8 ]/hibernate.jar[jar] (97063ms)
+
+
+SOME MINUTES LATER .... ;-)
+
+
+downloading http://www.ibiblio.org/maven/commons-logging/jars/commons-logging-1.0.4.jar ...
+..
+......
+.. (37kB)
+ [SUCCESSFUL ] [ apache | commons-logging | 1.0.4 ]/commons-logging.jar[jar] (24172ms)
+
+BUILD SUCCESSFUL
+Total time: 14 minutes 57 seconds
+Z:\ivy-repository></pre>
+</div>
+
+We can see here that <a href="/ivy">ivy</a> has resolved hibernate 2.1.8 and 24 depending modules. If we look at the ivy file for <a href="http://ivyrep.jayasoft.org/hibernate/hibernate/ivy-2.1.8.xml">hibernate 2.1.8</a>, we can see that it defines 17 dependencies. The 7 others that ivy retrieved, were transitive ones used in direct dependent modules of hibernate.
+
+We can notice that we have retrieve 3 differents revisions of apache commons-logging (1.0.2, 1.0.3, 1.0.4) and 2 revisions of commons-collections (1.2, 1.2.1). This is due to the fact that we use the "no conflict" <a href="../../../doc/configuration/conflict-managers.html">conflic manager</a> in the ivyconf file.
+We do not want to evict any modules because we are building our own repository !
+
+8 modules artifacts have not been downloaded cause they have not been found on ibiblio with the ivyconf as it is.
+We will see how to handle this problem in the advanced tutorial.
+
+If we look at our repository now, it starts to look to something good :
+
+<div class="shell"><pre>Z:\ivy-repository>dir /s /B /A:-D ivy-local-repository
+Z:\ivy-repository\ivy-local-repository\apache\commons-collections\ivys\ivy-2.1.1.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-collections\ivys\ivy-2.1.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-collections\jars\commons-collections-2.1.1.jar
+Z:\ivy-repository\ivy-local-repository\apache\commons-collections\jars\commons-collections-2.1.jar
+Z:\ivy-repository\ivy-local-repository\apache\commons-dbcp\ivys\ivy-1.2.1.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-dbcp\jars\commons-dbcp-1.2.1.jar
+Z:\ivy-repository\ivy-local-repository\apache\commons-lang\ivys\ivy-1.0.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-lang\jars\commons-lang-1.0.jar
+Z:\ivy-repository\ivy-local-repository\apache\commons-logging\ivys\ivy-1.0.2.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-logging\ivys\ivy-1.0.3.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-logging\ivys\ivy-1.0.4.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-logging\jars\commons-logging-1.0.2.jar
+Z:\ivy-repository\ivy-local-repository\apache\commons-logging\jars\commons-logging-1.0.3.jar
+Z:\ivy-repository\ivy-local-repository\apache\commons-logging\jars\commons-logging-1.0.4.jar
+Z:\ivy-repository\ivy-local-repository\apache\commons-pool\ivys\ivy-1.2.xml
+Z:\ivy-repository\ivy-local-repository\apache\commons-pool\jars\commons-pool-1.2.jar
+Z:\ivy-repository\ivy-local-repository\apache\xalan\ivys\ivy-2.4.0.xml
+Z:\ivy-repository\ivy-local-repository\apache\xalan\jars\xalan-2.4.0.jar
+Z:\ivy-repository\ivy-local-repository\apache\xerces\ivys\ivy-2.0.2.xml
+Z:\ivy-repository\ivy-local-repository\apache\xerces\ivys\ivy-2.4.0.xml
+Z:\ivy-repository\ivy-local-repository\apache\xerces\jars\xerces-2.0.2.jar
+Z:\ivy-repository\ivy-local-repository\apache\xerces\jars\xerces-2.4.0.jar
+Z:\ivy-repository\ivy-local-repository\apache\xerces\jars\xmlParserAPIs-2.0.2.jar
+Z:\ivy-repository\ivy-local-repository\c3p0\c3p0\ivys\ivy-0.8.4.5.xml
+Z:\ivy-repository\ivy-local-repository\c3p0\c3p0\jars\c3p0-0.8.4.5.jar
+Z:\ivy-repository\ivy-local-repository\cglib\cglib\ivys\ivy-2.0.2.xml
+Z:\ivy-repository\ivy-local-repository\cglib\cglib\jars\cglib-full-2.0.2.jar
+Z:\ivy-repository\ivy-local-repository\dom4j\dom4j\ivys\ivy-1.4.xml
+Z:\ivy-repository\ivy-local-repository\dom4j\dom4j\jars\dom4j-1.4.jar
+Z:\ivy-repository\ivy-local-repository\ehcache\ehcache\ivys\ivy-0.9.xml
+Z:\ivy-repository\ivy-local-repository\ehcache\ehcache\jars\ehcache-0.9.jar
+Z:\ivy-repository\ivy-local-repository\hibernate\hibernate\ivys\ivy-2.1.8.xml
+Z:\ivy-repository\ivy-local-repository\hibernate\hibernate\jars\hibernate-2.1.8.jar
+Z:\ivy-repository\ivy-local-repository\jboss\jboss-cache\ivys\ivy-1.1.1.xml
+Z:\ivy-repository\ivy-local-repository\jgroups\jgroups\ivys\ivy-2.2.xml
+Z:\ivy-repository\ivy-local-repository\odmg\odmg\ivys\ivy-3.0.xml
+Z:\ivy-repository\ivy-local-repository\odmg\odmg\jars\odmg-3.0.jar
+Z:\ivy-repository\ivy-local-repository\opensymphony\oscache\ivys\ivy-2.0.xml
+Z:\ivy-repository\ivy-local-repository\proxool\proxool\ivys\ivy-0.8.3.xml
+Z:\ivy-repository\ivy-local-repository\proxool\proxool\jars\proxool-0.8.3.jar
+Z:\ivy-repository\ivy-local-repository\sun\jaas\ivys\ivy-1.0.xml
+Z:\ivy-repository\ivy-local-repository\sun\jca\ivys\ivy-1.0.xml
+Z:\ivy-repository\ivy-local-repository\sun\jdbc\ivys\ivy-2.0.xml
+Z:\ivy-repository\ivy-local-repository\sun\jta\ivys\ivy-1.0.xml
+Z:\ivy-repository\ivy-local-repository\swarmcache\swarmcache\ivys\ivy-1.0RC2.xml
+Z:\ivy-repository\ivy-local-repository\swarmcache\swarmcache\jars\swarmcache-1.0RC2.jar
+
+Z:\ivy-repository></pre>
+</div>
+
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/tutorial/conf.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/tutorial/conf.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/tutorial/conf.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/tutorial/conf.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,289 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 2};</script>
+ <script type="text/javascript" src="../../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+This tutorial introduces the use of configuration in ivy files. Ivy configurations is indeed a very important concept. Someone even told me one day that using Ivy without using configurations is like eating a good cheese without touching the glass of Chateau Margaux 1976 you have just aside :-)
+
+More seriously, configurations in ivy can be better understood as views on your module, and you will see how they can be used efficiently here.
+
+Reference documentation on configurations can be find <a href="../../doc/terminology.html">here</a> and <a href="../../doc/ivyfile/configurations.html">here</a>.
+<h1>Introduction</h1>
+Source code available in src/example/configurations/multi-projects.
+We have two projects :
+ - a library that define an api to filter String array and two implementations of this api.
+ - a very small app that use this library.
+
+The library produces 3 artifacts:
+ - the api jar,
+ - an implementation jar with no external dependency,
+ - an other implementation that needs commons-collection to perform.
+
+The application only need api to compile and can use any of the two implementation at runtime.
+
+<h1>The library project</h1>
+The first project we defined in this tutorial is the filter-framework.
+In order to have a fine grained artifacts publication definition, we defined configurations to map usage other can make of our library.
+<h2>The ivy.xml file</h2>
+
+<div class="ivy-file">
+<code type="xml">
+<ivy-module version="1.3">
+ <info organisation="jayasoft" module="filter-framework"/>
+ <configurations>
+ <conf name="api" description="only provide filter framework API"/>
+ <conf name="homemade-impl" extends="api" description="provide a home made implementation of our api"/>
+ <conf name="cc-impl" extends="api" description="provide an implementation that use apache common collection framework"/>
+ <conf name="test" extends="cc-impl" visibility="private" description="for testing our framework"/>
+ </configurations>
+ <publications>
+ <artifact name="filter-api" type="jar" conf="api" ext="jar"/>
+ <artifact name="filter-hmimpl" type="jar" conf="homemade-impl" ext="jar"/>
+ <artifact name="filter-ccimpl" type="jar" conf="cc-impl" ext="jar"/>
+ </publications>
+ <dependencies>
+ <dependency org="apache" name="commons-collections" rev="3.1" conf="cc-impl->default"/>
+ <dependency org="junit" name="junit" rev="3.8" conf="test->default"/>
+ </dependencies>
+</ivy-module>
+</code>
+</div>
+<h2>Explanation</h2>
+As you can see we defined 3 public configurations and a private one (defined junit dependency for testing).
+The 2 implementations conf <b>homemade-impl</b>, <b>cc-impl</b> extends <b>api</b> configuration so artifacts defined in api will also be required in its extending conf.
+In the publications tag we defined the artifacts we produce (here it's jars) and we affect them a configuration.
+Later when others will use our library they will have a very flexible way to defined what they need.
+
+<h2>See it in action</h2>
+The library project is build using ant. Open a shell in the root directory of the project and type <b>ant</b>.
+<div class="shell"><pre>
+Buildfile: build.xml
+clean:
+resolve:
+:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
+no configuration file found, using default...
+:: configuring :: url = jar:file:/C:/dev/ant/apache-ant-1.6.2/lib/ivy-20060123130642.jar!/fr/jayasoft/ivy/conf/ivyconf.xml
+:: resolving dependencies :: [ jayasoft | filter-framework | working@SPIDER ]
+ confs: [api, homemade-impl, cc-impl, test]
+ found [ apache | commons-collections | 3.1 ] in main
+ found [ junit | junit | 3.8 ] in main
+downloading http://www.ibiblio.org/maven/commons-collections/jars/commons-collections-3.1.jar ................(546kB)
+ [SUCCESSFUL ] [ apache | commons-collections | 3.1 ]/commons-collections.jar[jar] (34320ms)
+downloading http://www.ibiblio.org/maven/junit/jars/junit-3.8.jar ........................... (118kB)
+ [SUCCESSFUL ] [ junit | junit | 3.8 ]/junit.jar[jar] (8462ms)
+:: resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | api | 0 | 0 | 0 | 0 || 0 | 0 |
+ | homemade-impl | 0 | 0 | 0 | 0 || 0 | 0 |
+ | cc-impl | 1 | 1 | 1 | 0 || 1 | 1 |
+ | test | 2 | 2 | 1 | 0 || 2 | 2 |
+ ---------------------------------------------------------------------
+:: retrieving :: [ jayasoft | filter-framework ]
+ confs: [api, homemade-impl, cc-impl, test]
+ 3 artifacts copied, 0 already retrieved
+
+build:
+ [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build
+ [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\distrib
+ [javac] Compiling 4 source files to D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build
+ [jar] Building jar: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\distrib\filter-api.jar
+ [jar] Building jar: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\distrib\filter-hmimpl.jar
+ [jar] Building jar: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\distrib\filter-ccimpl.jar
+
+test:
+ [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build\test-report
+ [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build\test-classes
+ [javac] Compiling 3 source files to D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\filter-framework\build\test-classes
+ [junit] Running filter.ccimpl.CCFilterTest
+ [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0.02 sec
+ [junit] Running filter.hmimpl.HMFilterTest
+ [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0.01 sec
+
+publish:
+:: delivering :: [ jayasoft | filter-framework | working@SPIDER ] :: 1.3 :: release :: Tue Jan 24 10:53:41 CET 2006
+ delivering ivy file to distrib/ivy.xml
+:: publishing :: [ jayasoft | filter-framework | working@SPIDER ]
+ published filter-api to D:\users\mm\.ivy/local/jayasoft/filter-framework/1.3/jars/filter-api.jar
+ published filter-ccimpl to D:\users\mm\.ivy/local/jayasoft/filter-framework/1.3/jars/filter-ccimpl.jar
+ published filter-hmimpl to D:\users\mm\.ivy/local/jayasoft/filter-framework/1.3/jars/filter-hmimpl.jar
+ published ivy to D:\users\mm\.ivy/local/jayasoft/filter-framework/1.3/ivys/ivy.xml
+ [echo] project filter-framework released with version 1.3
+
+BUILD SUCCESSFUL
+</div></pre>
+The ant's default target is publish.
+This target use ivy to publish our library binaries in a local repository.
+As we do not specify any repository path the default one is use. ({home.dir}/.ivy/local/jayasoft/filter-framework/)
+Now we are ready to use our library.
+
+<h1>The application project</h1>
+
+Now that we have shipped our fantastic library, we want to use it!
+The tutorial comes with a sample application called myapp. You will find it in the tutorial folder.
+<h2>The ivy.xml file</h2>
+
+<div class="ivy-file">
+<code type="xml">
+<ivy-module version="1.3">
+ <info organisation="jayasoft" module="myapp"/>
+
+ <configurations>
+ <conf name="build" visibility="private" description="compilation only need api jar" />
+ <conf name="noexternaljar" description="use only company jar" />
+ <conf name="withexternaljar" description="use company jar and third party jars" />
+ </configurations>
+
+ <dependencies>
+ <dependency org="jayasoft" name="filter-framework" rev="latest.integration" conf="build->api; noexternaljar->homemade-impl; withexternaljar->cc-impl"/>
+ </dependencies>
+</ivy-module>
+</code>
+</div>
+<h2>Explanation</h2>
+We create 3 configurations that define the way we want to use the application.
+The build configuration, (as said before) only need api to compile.
+The other configuration are defined for runtime.
+One configuration will only use "home-made" jars, and the second one will use external jars.
+
+We also defined a dependency on the previous library.
+In the dependency we use configuration mapping to match ours and library configurations.
+You can found more information on configuration mapping <a href="../../doc/ivyfile/configurations.html">here</a>
+<ol>
+ <li><b>build->api</b> : here we tell ivy that our <b>build</b> configuration depends on the api configuration of the dependcy</li>
+ <li><b>noexternaljar->homemade-impl</b> : here we tell ivy that our <b>noexternaljar</b> configuration depends on the <b>homemade-impl</b> configuration of the dependcy.</li>
+ <li><b>withexternaljar->cc-impl</b> : here we tell ivy that our <b>withexternaljar</b> configuration depends on the <b>cc-impl</b> configuration of the dependcy</li>
+</ol>
+Note that we never declares any of the dependency artifacts we need in each configuration: it's the dependency module file which declares the published artifacts and which should be used in each configuration.
+
+In the ant buld.xml file we defined a resolve target as follow:
+
+<code type="xml">
+<target name="resolve" description="--> retreive dependencies with ivy">
+ <ivy:retrieve pattern="${ivy.lib.dir}/[conf]/[artifact].[ext]"/>
+</target>
+</code>
+
+When we call this target, Ivy will do a resolve using our ivy.xml file in the root folder and will after do retrieve putting all the artifacts in folder for each configuration. Here is how your lib directory should look like after a call to this target:
+<div class="shell"><pre>
+ Répertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib
+
+01/24/2006 11:19 AM <REP> build
+01/24/2006 11:19 AM <REP> noexternaljar
+01/24/2006 11:19 AM <REP> withexternaljar
+ 0 fichier(s) 0 octets
+
+ Répertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib\build
+
+01/24/2006 10:53 AM 1,174 filter-api.jar
+ 1 fichier(s) 1,174 octets
+
+ Répertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib\noexternaljar
+
+01/24/2006 10:53 AM 1,174 filter-api.jar
+01/24/2006 10:53 AM 1,030 filter-hmimpl.jar
+ 2 fichier(s) 2,204 octets
+
+ Répertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib\withexternaljar
+01/24/2006 10:53 AM 559,366 commons-collections.jar
+01/24/2006 10:53 AM 1,174 filter-api.jar
+01/24/2006 10:53 AM 1,626 filter-ccimpl.jar
+ 3 fichier(s) 562,166 octets
+</pre></div>
+As you can see for each configuration we have now a set of jars.
+
+Let's try to launch our app.
+
+<h2>See it in action</h2>
+Use ant to run the application.
+Default ant target is run-cc and will launch application using common collection jar.
+<div class="shell"><pre>
+Buildfile: build.xml
+
+resolve:
+:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
+no configuration file found, using default...
+:: configuring :: url = jar:file:/C:/dev/ant/apache-ant-1.6.2/lib/ivy-20060123130642.jar!/fr/jayasoft/ivy/conf/ivyconf.xml
+:: resolving dependencies :: [ jayasoft | myapp | working@SPIDER ]
+ confs: [build, noexternaljar, withexternaljar]
+ found [ jayasoft | filter-framework | 1.3 ] in local
+ [1.3] [ jayasoft | filter-framework | latest.integration ]
+ found [ apache | commons-collections | 3.1 ] in default
+downloading D:\users\mm\.ivy\local\jayasoft\filter-framework\1.3\jars\filter-ccimpl.jar .... (1kB)
+ [SUCCESSFUL ] [ jayasoft | filter-framework | 1.3 ]/filter-ccimpl.jar[jar] (0ms)
+downloading D:\users\mm\.ivy\local\jayasoft\filter-framework\1.3\jars\filter-api.jar .... (1kB)
+ [SUCCESSFUL ] [ jayasoft | filter-framework | 1.3 ]/filter-api.jar[jar] (0ms)
+downloading D:\users\mm\.ivy\local\jayasoft\filter-framework\1.3\jars\filter-hmimpl.jar .... (1kB)
+ [SUCCESSFUL ] [ jayasoft | filter-framework | 1.3 ]/filter-hmimpl.jar[jar] (10ms)
+:: resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | build | 1 | 1 | 1 | 0 || 1 | 1 |
+ | noexternaljar | 1 | 1 | 1 | 0 || 2 | 2 |
+ | withexternaljar | 2 | 1 | 1 | 0 || 3 | 2 |
+ ---------------------------------------------------------------------
+:: retrieving :: [ jayasoft | myapp ]
+ confs: [build, noexternaljar, withexternaljar]
+ 6 artifacts copied, 0 already retrieved
+
+build:
+ [mkdir] Created dir: D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\myapp\build
+ [javac] Compiling 1 source file to D:\svn\jayasoft\projects\tools\ivy\src\example\configurations\multi-projects\myapp\build
+
+run-cc:
+ [java] Filtering with:class filter.ccimpl.CCFilter
+ [java] Result :[two, tree]
+</div></pre>
+Launching application with only home made jars is straingforward.
+type ant run-hm
+
+<div class="shell"><pre>
+Buildfile: build.xml
+
+resolve:
+:: Ivy 20060123130642 - 20060123130642 :: http://ivy.jayasoft.org/ ::
+no configuration file found, using default...
+:: configuring :: url = jar:file:/C:/dev/ant/apache-ant-1.6.2/lib/ivy-20060123130642.jar!/fr/jayasoft/ivy/conf/ivyconf.xml
+:: resolving dependencies :: [ jayasoft | myapp | working@SPIDER ]
+ confs: [build, noexternaljar, withexternaljar]
+ found [ jayasoft | filter-framework | 1.3 ] in default
+ [1.3] [ jayasoft | filter-framework | latest.integration ]
+ found [ apache | commons-collections | 3.1 ] in default
+:: resolution report ::
+ ---------------------------------------------------------------------
+ | | modules || artifacts |
+ | conf | number| search|dwnlded|evicted|| number|dwnlded|
+ ---------------------------------------------------------------------
+ | build | 1 | 1 | 0 | 0 || 1 | 0 |
+ | noexternaljar | 1 | 1 | 0 | 0 || 2 | 0 |
+ | withexternaljar | 2 | 1 | 0 | 0 || 3 | 0 |
+ ---------------------------------------------------------------------
+:: retrieving :: [ jayasoft | myapp ]
+ confs: [build, noexternaljar, withexternaljar]
+ 0 artifacts copied, 6 already retrieved
+
+build:
+
+run-hm:
+ [java] Filtering with:class filter.hmimpl.HMFilter
+ [java] Result :[two, tree]
+
+BUILD SUCCESSFUL
+</pre></div>
+Nice we got the same result but we can see that implementation class are different.
+
+<h1>Conclusion</h1>
+<b>You should use configuration as often as possible</b>
+Configurations are very important concept in ivy. They allow you to groups artifacts set by meaning.
+When you write ivy file for projects that are supposed to be reused, use configurations to allow people to get only they what they need without having to specify it by hand using artifact tag in dependency section.
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Added: incubator/ivy/trunk/src/doc/xooki/doc/tutorial/defaultconf.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/src/doc/xooki/doc/tutorial/defaultconf.html?view=auto&rev=488342
==============================================================================
--- incubator/ivy/trunk/src/doc/xooki/doc/tutorial/defaultconf.html (added)
+++ incubator/ivy/trunk/src/doc/xooki/doc/tutorial/defaultconf.html Mon Dec 18 09:06:07 2006
@@ -0,0 +1,199 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 2};</script>
+ <script type="text/javascript" src="../../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+Until Ivy 1.2a, the default resolver was a simple ivyrep resolver, with only a small number of possibilities of configuration. Whenever you wanted to do something slightly more complicated than looking for ivy files on ivyrep and artifacts on ibiblio, you had to write your own ivyconf file (see other tutorials and <a href="../../doc/configuration.html">configuration</a> reference for details about this).
+
+Ivy 1.3 introduces a new default configuration, fully compatible pre 1.3 one, but a lot more configurable.
+
+<h1>Concept</h1>
+This default configuration mainly consists 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 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.
+
+Now let's describe each of these repositories concept in more details. We will describe how they are setup physically later.
+<h2>Local</h2>
+The local repository is particularly useful when you want to do something without being disturb 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.
+
+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>.
+
+This may be disturbing for some of you, but imagine you have to implement a new feature on a project, and in order to achieve that you need to modify two modules: you add a new method in module foo and exploit this new method in module bar. Then if you publish the module foo to your local repository, you will be sure to get it in your bar module, even if someone else publish a new revision of foo in the shared repository (this revision not having the new method you are currently adding).
+
+But be careful, when you have finished your development and publish it on the shared you will have to clean your local repository to benefit from new versions published in the shared repository.
+
+Note also that modules found in the local repository must be complete, i.e. they must provide both a module descriptor and the published artifacts.
+<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).
+
+Note that modules can be split across the shared repository and the public one: you can have the module descritor in the shared repository and the artifacts in the public one, for instance.
+<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.
+<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.
+
+First, several repositories uses the same root in your filesystem. Referenced as ${ivy.default.ivy.user.dir}, this is by default the directory .ivy in your user home.
+
+Note that several things can be done by setting ivy variable. To set them without defining your own ivyconf.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:
+<code type="xml">
+<target name="resolve">
+ <property name="ivy.default.ivy.user.dir" value="/path/to/ivy/user/dir"/>
+ <ivy:resolve />
+</target>
+</code>
+
+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 configuration.
+<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: <code>ivy.local.default.root</code>. For instance:
+<code>ivy.local.default.root=/opt/ivy/repository/local</code>.
+
+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:
+<code>ivy.local.default.ivy.pattern</code> gives the pattern to find ivy files
+<code>ivy.local.default.artifact.pattern</code> gives the pattern to find artifacts
+For example:
+<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>
+<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 shared directory. You can use <code>ivy.shared.default.root</code> variable to specify in a new directory. Moreover, you can also configure the layout with variables similar to the one for the local repository:
+<code>ivy.shared.default.ivy.pattern</code> gives the pattern to find ivy files
+<code>ivy.shared.default.artifact.pattern</code> gives the pattern to find artifacts
+For example:
+<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>
+
+<h2>Public</h2>
+By default, the public repository is ivyrep. To change the setting of this resolver, you can use the standard way to configure ivyrep:
+<code>ivy.ivyrep.default.ivy.root</code> specify the root for ivy files
+<code>ivy.ivyrep.default.ivy.pattern</code> specify the layout for ivy files
+<code>ivy.ivyrep.default.artifact.root</code> specify the root for artifacts
+<code>ivy.ivyrep.default.artifact.pattern</code> specify the layout for artifacts
+For instance:
+<code>
+ivy.ivyrep.default.ivy.root=http://myserver/ivy/
+ivy.ivyrep.default.artifact.root=http://myserver/ivy/
+</code>
+
+<h1>Going further</h1>
+OK, so we have seen how to easily change the settings of the three main repositories. But what if I want my shared repository is on a web server ? What if the public repository is not compatible with ivyrep ? What if ...
+
+Everything can be changed in the default configuration, for sure, you can even do your own configuration. But you can also benefit from a part of the default configuration without writing a complete one.
+
+But before explaining how, you will need to have a quick overview of how ivy is configured by default.
+
+By default, ivy is configured using an ivyconf.xml which is packaged in the ivy jar. Here is this ivyconf file:
+<code type="xml">
+<ivyconf>
+ <conf defaultResolver="default"/>
+ <include url="${ivy.default.conf.dir}/ivyconf-public.xml"/>
+ <include url="${ivy.default.conf.dir}/ivyconf-shared.xml"/>
+ <include url="${ivy.default.conf.dir}/ivyconf-local.xml"/>
+ <include url="${ivy.default.conf.dir}/ivyconf-main-chain.xml"/>
+ <include url="${ivy.default.conf.dir}/ivyconf-default-chain.xml"/>
+</ivyconf>
+</code>
+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 ivyconf 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 ivyconf like that:
+<code type="xml">
+<ivyconf>
+ <conf defaultResolver="default"/>
+ <include url="http://myserver/ivy/myivyconf-public.xml"/>
+ <include url="${ivy.default.conf.dir}/ivyconf-shared.xml"/>
+ <include url="${ivy.default.conf.dir}/ivyconf-local.xml"/>
+ <include url="${ivy.default.conf.dir}/ivyconf-main-chain.xml"/>
+ <include url="${ivy.default.conf.dir}/ivyconf-default-chain.xml"/>
+</ivyconf>
+</code>
+Note that only the ivyconf-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.conf.dir} is a variable which is always set to the place where ivy default configuration files are (i.e. packaged in the jar).
+To finish this example, you for sure have to write your own ivyconf file for defining your own public resolver. For instance:
+<code type="xml">
+<ivyconf>
+ <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>
+</ivyconf>
+</code>
+No the last thing you will need in order to properly take advantage of the default configuration is the content of each included ivyconf file:
+<strong>ivyconf-public.xml</strong>
+<code type="xml">
+<ivyconf>
+ <resolvers>
+ <ivyrep name="public"/>
+ </resolvers>
+</ivyconf>
+</code>
+<strong>ivyconf-shared.xml</strong>
+<code type="xml">
+<ivyconf>
+ <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>
+</ivyconf>
+</code>
+<strong>ivyconf-local.xml</strong>
+<code type="xml">
+<ivyconf>
+ <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>
+</ivyconf>
+</code>
+<strong>ivyconf-main-chain.xml</strong>
+<code type="xml">
+<ivyconf>
+ <resolvers>
+ <chain name="main" dual="true">
+ <resolver ref="shared"/>
+ <resolver ref="public"/>
+ </chain>
+ </resolvers>
+</ivyconf>
+</code>
+<strong>ivyconf-default-chain.xml</strong>
+<code type="xml">
+<ivyconf>
+ <resolvers>
+ <chain name="default" returnFirst="true">
+ <resolver ref="local"/>
+ <resolver ref="main"/>
+ </chain>
+ </resolvers>
+</ivyconf>
+</code>
+
+Here you are, you have enough clues to configure that the way you want... check the <a href="../../doc/configuration.html">configuration documentation</a> to see if what you want to do is possible, and go ahead !
+ </textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>