Author: xavier
Date: Mon Nov 19 12:19:22 2007
New Revision: 596427
URL: http://svn.apache.org/viewvc?rev=596427&view=rev
Log:
review default settings, chain and dual resolver tutorials (IVY-591)
Modified:
incubator/ivy/core/trunk/doc/tutorial.html
incubator/ivy/core/trunk/doc/tutorial/defaultconf.html
incubator/ivy/core/trunk/doc/tutorial/dual.html
incubator/ivy/core/trunk/doc/tutorial/multiple.html
Modified: incubator/ivy/core/trunk/doc/tutorial.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/tutorial.html?rev=596427&r1=596426&r2=596427&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/tutorial.html (original)
+++ incubator/ivy/core/trunk/doc/tutorial.html Mon Nov 19 12:19:22 2007
@@ -41,10 +41,8 @@
<ul>
<li><a href="tutorial/start.html">Quick Start</a></li>
guide you through your very first steps with ivy.
-<li><a href="tutorial/ivyrep.html">Using IvyRep</a></li>
-show you the out of the box power of ivy + ivyrep.
-<li><a href="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>[[tutorial/defaultconf]]</li>
+give you a better understanding of the default settings and show you how to
customize them to your needs.
<li><a href="tutorial/multiple.html">Multiple Resolvers</a></li>
teach you how to configure Ivy to find its dependencies in multiple places.
<li><a href="tutorial/dual.html">Dual Resolver</a></li>
Modified: incubator/ivy/core/trunk/doc/tutorial/defaultconf.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/tutorial/defaultconf.html?rev=596427&r1=596426&r2=596427&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/tutorial/defaultconf.html (original)
+++ incubator/ivy/core/trunk/doc/tutorial/defaultconf.html Mon Nov 19 12:19:22
2007
@@ -25,23 +25,23 @@
</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 ivysettings file (see other
tutorials and <a href="../configuration.html">settings</a> reference for
details about this).
+Ivy comes bundled with some default settings which makes it pretty simple to
use in common environment. This tutorial, which is close to a reference
documentation, explains what are those default settings and how they can be
adjusted to your needs.
-Ivy 1.3 introduced new default settings a lot more flexible.
+To fully understand the concept of settings and what you can do with them, we
suggest reading other tutorial related to settings (like [[tutorial/multiple]]
and [[tutorial/dual]]) or the <a href="../configuration.html">settings</a>
reference documentation.
<h1>Concept</h1>
This default settings mainly consist of 3 kind of repositories:
<ul>
<li>local</li> a repository which is private to the user.
<li>shared</li> a repository which is shared between all the member of a team
-<li>public</li> a public repository on which most modules can be found
+<li>public</li> a public repository on which most modules, and especially
third party modules, can be found
</ul>
Note that if you work alone, the distinction between local and shared
repository is not very important, but there are some things to know to
distinguish them.
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.
+The local repository is particularly useful when you want to do something
without being disturbed by anything else happening in the environment. This
means that whenever ivy is able to locate a module in this repository it will
be used, no matter of what is available in others.
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>.
@@ -53,7 +53,7 @@
<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.
+Note that modules can be split across the shared repository and the public
one: you can have the module descriptor in the shared repository and the
artifacts in the public one, for instance.
<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>
@@ -88,7 +88,7 @@
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:
+By default, the shared repository lies in ${ivy.default.ivy.user.dir}/shared.
This is fine if you work alone, but the shared repository is supposed to be,
mmm, shared! So changing this directory is often required, and it is usually
modified to point to a network shared directory. You can use
<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:
@@ -99,15 +99,19 @@
</code>
<h2>Public</h2>
-By default, the public repository is ibiblio in m2 compatible mode.
+By default, the public repository is ibiblio in m2 compatible mode (in other
words, the maven 2 public repository).
+
+This repository has the advantage of providing a lot of modules, with metadata
for most of them. The quality of metadata is not always perfect, but it's a
very good start to use a tool like Ivy and benefit from the power of transitive
dependency management.
+
+Despite its ease of use, we suggest reading the [[bestpractices]] 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.
<em>In 1.4 version Ivy was using ivyrep has default resolver, if you want to
restore this, set
ivy.14.compatible=true as an ant property</em>
<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 ...
+OK, so we have seen how to easily change the settings of the three main
repositories. But what if my shared repository is on a web server? What if you
don't want to use maven 2 repository as public repository? What if ...
-Everything can be changed in the default settings, for sure, you can even do
your own settings. But you can also benefit from a part of the default settings
without writing a complete one.
+No problem, Ivy is very flexible and be configured with very specific settings
to match your needs and environment. But before considering writing your own
settings from scratch, we suggest reading the following where you will learn
how to leverage a part of the default settings and adjust the rest.
But before explaining how, you will need to have a quick overview of how ivy
is configured by default.
@@ -115,11 +119,11 @@
<code type="xml">
<ivysettings>
<settings defaultResolver="default"/>
- <include url="${ivy.default.conf.dir}/ivysettings-public.xml"/>
- <include url="${ivy.default.conf.dir}/ivysettings-shared.xml"/>
- <include url="${ivy.default.conf.dir}/ivysettings-local.xml"/>
- <include url="${ivy.default.conf.dir}/ivysettings-main-chain.xml"/>
- <include url="${ivy.default.conf.dir}/ivysettings-default-chain.xml"/>
+ <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>
OK, so not much info here, except a lot of inclusions. These inclusions have
been done on purpose so that you can easily change only one part of the
ivysettings and benefit of the rest easily. For example, if you want to define
your own public resolver, you will just have to configure ivy with an
ivysettings like that:
@@ -134,7 +138,7 @@
</ivysettings>
</code>
Note that only the ivysettings-public inclusion has changed to include a home
made public resolver. Note also that this can be used like that thanks to the
fact that ${ivy.default.settings.dir} is a variable which is always set to the
place where ivy default settings files are (i.e. packaged in the jar).
-To finish this example, you for sure have to write your own ivysettings file
for defining your own public resolver. For instance:
+To finish this example, you have to write your own ivysettings file (that you
will make available at http://myserver/ivy/myivysettings-public.xml in this
example) for defining your own public resolver. For instance:
<code type="xml">
<ivysettings>
<resolvers>
@@ -145,7 +149,7 @@
</resolvers>
</ivysettings>
</code>
-No the last thing you will need in order to properly take advantage of the
default settings is the content of each included ivysettings file:
+Now the last thing you will need in order to properly take advantage of the
default settings is the content of each included ivysettings file:
<strong>ivysettings-public.xml</strong>
<code type="xml">
<ivysettings>
@@ -205,7 +209,7 @@
</ivysettings>
</code>
-Here you are, you have enough clues to configure that the way you want...
check the <a href="../configuration.html">settings documentation</a> to see if
what you want to do is possible, and go ahead !
+Here you are, you have enough clues to configure that the way you want...
check the <a href="../configuration.html">settings documentation</a> to see if
what you want to do is possible, and go ahead!
</textarea>
<script type="text/javascript">xooki.postProcess();</script>
</body>
Modified: incubator/ivy/core/trunk/doc/tutorial/dual.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/tutorial/dual.html?rev=596427&r1=596426&r2=596427&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/tutorial/dual.html (original)
+++ incubator/ivy/core/trunk/doc/tutorial/dual.html Mon Nov 19 12:19:22 2007
@@ -25,65 +25,63 @@
</head>
<body>
<textarea id="xooki-source">
-This tutorial presents the use of the DualResolver, a feature introduced in
the version 0.6 of Ivy.
+In some cases it may happen that your module descriptors (Ivy files, maven
pom, ...) are located at one place and module artifacts (jars, ...) at another
place.
-Dual Resolver is used when ivy files can be found in a repository while
artifacts are in another. It is especially useful to use full power of ivy
(including transitive dependencies) with the ibiblio repository for artifacts.
The problem with the maven ibiblio repository is that it does not contain ivy
files. Since transitive dependencies are based upon ivy files, using the
ibiblio resolver does not permit to use transitive dependencies.
-
-The solution to this problem is to store your own repository only for ivy
files, and use ibiblio for artifacts. That's what is done in this tutorial.
+Dual Resolver is used to address this kind of need, and this tutorial will
show how to use it.
<h1>project description</h1>
Let's have a look at the src/example/dual directory in your ivy distribution.
It contains a build file and 3 directories:
<ul>
-<li>config: contains the ivy settings file</li>
+<li>settings: contains the ivy settings file</li>
<li>repository: a sample repository of ivy files</li>
<li>project: the project making use of ivy with dual resolver</li>
</ul>
<h2>the dual project</h2>
-The project is very simple and contains only one test class : example.Hello
-It depends on two libraries: apache commons-lang and apache commons-httpclient.
+The project is very simple and contains only one simple class: example.Hello
+It depends on two libraries: Apache commons-lang and Apache commons-httpclient.
-Here is the content of the project :
+Here is the content of the project:
<ul>
- <li>build.xml : the ant build file for the project</li>
- <li>ivy.xml : the ivy project file</li>
- <li>src\example\Hello.java : the only class of the project</li>
+ <li>build.xml: the ant build file for the project</li>
+ <li>ivy.xml: the ivy project file</li>
+ <li>src\example\Hello.java: the only class of the project</li>
</ul>
-Take a look at it's <b>ivy.xml</b> file:
+
+Let's have a look at the <b>ivy.xml</b> file:
<code>
<ivy-module version="1.0">
- <info organisation="jayasoft" module="hello-ivy" />
+ <info organisation="org.apache" module="hello-ivy"/>
<dependencies>
- <dependency org="commons-httpclient" name="commons-httpclient"
rev="2.0.2" />
- <dependency org="commons-lang" name="commons-lang" rev="2.0" />
+ <dependency org="commons-httpclient" name="commons-httpclient"
rev="2.0.2"/>
+ <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
</dependencies>
</ivy-module>
</code>
-As you can see, nothing special here... Indeed, it's the philosophy of ivy to
keep ivy files independent of the way dependencies are retrieved.
+As you can see, nothing special here... Indeed, it's the philosophy of ivy to
keep ivy files independent of the way dependencies are resolved.
<h2>the <b>ivy</b> settings</h2>
-The ivy settings is made in the config directory it contains only one file:
ivysettings.xml.
+The ivy settings is made in the settings directory; it contains only one file:
ivysettings.xml.
-Let's analyse it.
<code>
<ivysettings>
- <settings defaultResolver="dual-example" />
+ <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" />
+ <ibiblio name="ibiblio" m2compatible="true" usepoms="false" />
</dual>
</resolvers>
</ivysettings>
</code>
-Here we configure one resolver, the default one, which is a dual resolver.
This dual resolver has two sub resolvers: the first is what is called the "ivy"
resolver of the dual resolver, and the second one is what is called the
"artifact" resolver. It is important that the dual resolver exactly has two sub
resolvers in this given order.
-The ivy resolver, here a filesystem one, is used only to find ivy files. The
settings given in this resolver says that all ivy files are in the same
directory, named like that: [module]-ivy-[revision].xml. If we check the
repository directory, we can confirm that it contains a file named
commons-httpclient-ivy-2.0.2.xml. It fulfills the given pattern and will thus
be find by this resolver.
-The artifact resolver is simply an ibiblio one, and will thus try to find
required artifacts in the maven ibiblio repository.
+Here we configure one resolver, the default one, which is a dual resolver.
This dual resolver has two sub resolvers: the first is what is called the "ivy"
or "metadata" resolver of the dual resolver, and the second one is what is
called the "artifact" resolver. It is important that the dual resolver exactly
has two sub resolvers in this given order.
+The metadata resolver, here a filesystem one, is used only to find module
descriptors, in this case Ivy files. The settings given in this resolver says
that all ivy files are in the same directory, named like that:
[module]-ivy-[revision].xml. If we check the repository directory, we can
confirm that it contains a file named commons-httpclient-ivy-2.0.2.xml. It
fulfills the given pattern and will thus be found by this resolver.
+The artifact resolver is simply an ibiblio one, configured in m2compatible
mode to use the maven 2 repository, with usepoms="false" to make sure it won't
use maven 2 metadata. Note that this isn't strictly necessary, since the second
resolver in a dual resolver (the artifact resolver) is never asked to find
module metadata.
<h1>walkthrough</h1>
<div class="step">
@@ -107,16 +105,23 @@
As you can see, ivy not only downloaded commons-lang and commons-httpclient,
but also commons-logging. Indeed, commons-logging is a dependency of
httpclient, as we can see in the httpclient ivy file found in the repository
directory:
<code>
<ivy-module version="1.0">
- <info organisation="apache" module="commons-httpclient" revision="2.0.2"
status="release" publication="20041010174300" />
+ <info
+ organisation="commons-httpclient"
+ module="commons-httpclient"
+ revision="2.0.2"
+ status="release"
+ publication="20041010174300"/>
<dependencies>
- <dependency name="commons-logging" rev="1.0.4" conf="default" />
+ <dependency org="commons-logging" name="commons-logging" rev="1.0.4"
conf="default"/>
</dependencies>
</ivy-module>
</code>
<br/>
-So everything worked well, ivy file has been found in the repository directory
and artifacts have been downloaded from ibiblio. You now just have to write ivy
files for the module you often use, and they will be much easier to use... And
imagine a world in which each module delivers also an ivy file. Since it is
independent of the way to retrieve dependencies, it would made all dependencies
handling much easier, wouldn't it?
+So everything worked well, ivy file has been found in the repository directory
and artifacts have been downloaded from ibiblio.
+This kind of setup can be useful if you don't want to rely on maven 2
repository for metadata, or if you want to take full advantage of Ivy files for
some or all modules. Combining chain and dual resolvers can lead to very
flexible settings addressing most needs.
+For full details about the dual resolver, have a look at the corresponding
[[resolver/dual reference documentation]].
</textarea>
<script type="text/javascript">xooki.postProcess();</script>
</body>
Modified: incubator/ivy/core/trunk/doc/tutorial/multiple.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/tutorial/multiple.html?rev=596427&r1=596426&r2=596427&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/tutorial/multiple.html (original)
+++ incubator/ivy/core/trunk/doc/tutorial/multiple.html Mon Nov 19 12:19:22 2007
@@ -25,44 +25,54 @@
</head>
<body>
<textarea id="xooki-source">
-This example is an illustration of how artifacts can be retrieved by multiple
resolvers. Using multiple resolvers is very important when using continous
integration. Indeed, in such environments, you can use multiple repositories
and so multiple resolvers to retrieve both released versions of projects than
continous integrated versions produced for example with cruise-control. In our
example, we will just show how to use two resolvers, one on a local repository
and one using ibiblio repository.
+This example is an illustration of how modules can be retrieved by multiple
resolvers. Using multiple resolvers can be useful in many contexts, here are
some examples:
+<ul>
+<li>separate integration builds from releases</li>
+<li>use a public repository for third party modules and a private one for
internal modules</li>
+<li>use a repository for storing modules which are not accurate in an
unmanaged public repository</li>
+<li>use a local repository to expose builds made on one developer's
station</li>
+</ul>
+
+In Ivy, the use of multiple resolvers is supported by one compound resolver
called a chain resolver.
+
+In our example, we will simply show how to use two resolvers, one on a local
repository and one using maven2 repository.
<h1>project description</h1>
-<h2>the project : chained-resolvers</h2>
-The project is very simple and contains only one test class : example.Hello
-It depends on two libraries apache commons-lang and a little test library
(sources are included in jar file). The test library is used by the project to
uppercase a string, and commons-lang is used to capitalize the same string.
+<h2>the project: chained-resolvers</h2>
+The project is very simple and contains only one simple class: example.Hello.
+
+It depends on two libraries: Apache commons-lang and a little test library
(sources are included in jar file). The test library is used by the project to
uppercase a string, and commons-lang is used to capitalize the same string.
Here is the content of the project:
<ul>
- <li>build.xml : the ant build file for the project</li>
- <li>ivy.xml : the ivy project file</li>
- <li>src\example\Hello.java : the only class of the project</li>
+ <li>build.xml: the ant build file for the project</li>
+ <li>ivy.xml: the ivy project file</li>
+ <li>src\example\Hello.java: the only class of the project</li>
</ul>
-Take a look at it's <b>ivy.xml</b> file :
+Let's have a look at the <b>ivy.xml</b> file:
<code>
<ivy-module version="1.0">
- <info organisation="jayasoft" module="chained-resolvers" />
+ <info organisation="org.apache" module="chained-resolvers"/>
<dependencies>
- <dependency org="apache" name="commons-lang" rev="2.0" />
- <dependency name="test" rev="1.0" />
+ <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
+ <dependency name="test" rev="1.0"/>
</dependencies>
</ivy-module>
</code>
-As we expect, the ivy file declares to be dependent on the two libraries that
the project use : apache commons-lang.jar and test.jar.
+As we expect, the ivy file declares to be dependent on the two libraries that
the project use: commons-lang and test. Note that we don't specify the
organisation for the dependency test, in this case Ivy assumes the same org as
the declaring module, ie org.apache in this case.
-<h2>the <b>ivy</b> settings</h2>
-The ivy settings is made in the config directory it contains only one file:
ivysettings.xml.
+<h2>the <b>ivy settings</b></h2>
+The ivy settings is made in the settings directory it contains only one file:
ivysettings.xml.
-Let's analyse it.
<code>
<ivysettings>
- <settings defaultResolver="chain-example" />
+ <settings defaultResolver="chain-example"/>
<resolvers>
<chain name="chain-example">
<filesystem name="libraries">
- <artifact
pattern="${ivy.settings.dir}/repository/[artifact]-[revision].[type]" />
+ <artifact
pattern="${ivy.settings.dir}/repository/[artifact]-[revision].[ext]" />
</filesystem>
- <ibiblio name="ibiblio" />
+ <ibiblio name="ibiblio" m2compatible="true" />
</chain>
</resolvers>
</ivysettings>
@@ -78,25 +88,45 @@
<li>ibiblio : this resolver is a special one. It looks in the ibiblio maven
repository to retrieve the libraries.</li>
</ul>
+That's it, we have configured a chain of resolvers!
+
<h1>walkthrough</h1>
<div class="step">
-<h2>step 1 : preparation</h2>
+<h2>step 1: preparation</h2>
Open a DOS or shell window, and go to the "chained-resolvers" directory.
</div>
<div class="step">
-<h2>step 2 : clean directory tree</h2>
-On the prompt type : ant<br>
+<h2>step 2: clean directory tree</h2>
+On the prompt type: ant<br>
This will clean up the entire project directory tree and ivy cache. You can do
it each time you want to clean up this example.
+
+<div class="tip">
+In almost all examples, we provide a clean target as default target. Since
most examples use the same Ivy cache, you will clean the whole Ivy cache each
time you call this target.
+
+Cleaning Ivy cache is something you can do with no fear (except performance):
it's only a cache, everything can be (and should be) obtained again from
repositories. For those coming from maven 2 land, this may sounds strange, but
remember that in Ivy, the cache is not a local repository, things are kept
cleanly isolated.
+</div>
</div>
<div class="step">
-<h2>step 3 : run the project</h2>
-Goto chainedresolvers-project directory. And simply run <b>ant</b>.
+<h2>step 3: run the project</h2>
+Go to chainedresolvers-project directory. And simply run <b>ant</b>.
<div class="shell"><pre>I:\chained-resolvers\chainedresolvers-project>ant
[<tutorial/log/chained-resolvers.txt>]
</pre></div></div>
-We can see in the log of the resolve task, that the two dependencies have been
retrieved (2 artifacts) and copied to the ivy cache directory (2 downloaded).
The run target succeed in using both commons-lang.jar comming from ibiblio
repository and test.jar coming from the local repository.
+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).
+
+The run target succeed in using both commons-lang.jar comming from ibiblio
repository and test.jar coming from the local repository.
+
+<h1>Going further</h1>
+This very simple example helps to see how to make a basic setting of two
resolvers in a chain. The [[resolver/chain chain resolver's reference
documentation]] is available for those who would like to know all the features
offered by this resolver.
+
+The most interesting things to know that you can try out from this basic
example are:
+<ul>
+<li>a chain is not limited to two nested resolvers, you can use the number you
want</li>
+<li>by setting returnFirst="true", you can have a chain which stops as soon as
it has found a result for a given module</li>
+<li>by setting dual="true", the full chain will be used both for module
descriptors and artifacts, while with dual="false", the resolver in the chain
which found the module descriptor (if any) is also used for artifacts</li>
+</ul>
</textarea>
<script type="text/javascript">xooki.postProcess();</script>
