You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by ja...@apache.org on 2017/06/19 01:58:56 UTC
[13/29] ant-ivy git commit: Initial auto-converted .adoc files from
xooki2asciidoc convertor
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/toc.json
----------------------------------------------------------------------
diff --git a/asciidoc/toc.json b/asciidoc/toc.json
new file mode 100644
index 0000000..55a0f21
--- /dev/null
+++ b/asciidoc/toc.json
@@ -0,0 +1,957 @@
+{
+ "children": [
+ {
+ "id":"index",
+ "title":"Documentation",
+ "children": [
+ {
+ "id":"release-notes",
+ "title":"Release Notes"
+ },
+ {
+ "id":"tutorial",
+ "title":"Tutorials",
+ "children": [
+ {
+ "id":"tutorial/start",
+ "title":"Quick Start",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"tutorial/defaultconf",
+ "title":"Adjusting default settings",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"tutorial/multiple",
+ "title":"Multiple Resolvers",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"tutorial/dual",
+ "title":"Dual Resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"tutorial/dependence",
+ "title":"Project dependencies",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"tutorial/multiproject",
+ "title":"Using Ivy in multiple projects environment",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"tutorial/conf",
+ "title":"Using Ivy Module Configurations",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"tutorial/build-repository",
+ "title":"Building a repository",
+ "children": [
+ {
+ "id":"tutorial/build-repository/basic",
+ "title":"Basic repository copy",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"tutorial/build-repository/advanced",
+ "title":"Using namespaces",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"moreexamples",
+ "title":"More examples",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"reference",
+ "title":"Reference",
+ "children": [
+ {
+ "id":"intro",
+ "title":"Introduction",
+ "isAbstract":true,
+ "children": [
+ {
+ "id":"terminology",
+ "title":"Terminology",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"concept",
+ "title":"Main Concepts",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"textual",
+ "title":"Text Conventions",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"principle",
+ "title":"How does it work ?",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"bestpractices",
+ "title":"Best practices",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"compatibility",
+ "title":"Compatibility",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"install",
+ "title":"Installation",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"settings",
+ "title":"Settings Files",
+ "children": [
+ {
+ "id":"settings/property",
+ "title":"property",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/properties",
+ "title":"properties",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/settings",
+ "title":"settings",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/include",
+ "title":"include",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/classpath",
+ "title":"classpath",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/typedef",
+ "title":"typedef",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/credentials",
+ "title":"credentials",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/signers",
+ "title":"signers",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/lock-strategies",
+ "title":"lock-strategies",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/caches",
+ "title":"caches",
+ "children": [
+ {
+ "id":"settings/caches/cache",
+ "title":"cache",
+ "children": [
+ {
+ "id":"settings/caches/ttl",
+ "title":"ttl",
+ "children": [
+
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id":"settings/latest-strategies",
+ "title":"latest-strategies",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/parsers",
+ "title":"parsers",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/namespaces",
+ "title":"namespaces",
+ "children": [
+ {
+ "id":"settings/namespace",
+ "title":"namespace",
+ "children": [
+ {
+ "id":"settings/namespace/rule",
+ "title":"rule",
+ "children": [
+ {
+ "id":"settings/namespace/fromtosystem",
+ "title":"fromsystem / tosystem",
+ "children": [
+ {
+ "id":"settings/namespace/src",
+ "title":"src",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/namespace/dest",
+ "title":"dest",
+ "children": [
+
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id":"settings/macrodef",
+ "title":"macrodef",
+ "children": [
+ {
+ "id":"settings/macrodef/attribute",
+ "title":"attribute",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"settings/resolvers",
+ "title":"resolvers",
+ "children": [
+ {
+ "id":"resolver/ivyrep",
+ "title":"IvyRep Resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/ibiblio",
+ "title":"IBiblio Resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/packager",
+ "title":"Packager resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/filesystem",
+ "title":"File System resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/url",
+ "title":"Url Resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/chain",
+ "title":"Chain Resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/dual",
+ "title":"Dual resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/sftp",
+ "title":"sftp resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/ssh",
+ "title":"ssh resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/vfs",
+ "title":"vfs resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/jar",
+ "title":"Jar resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/obr",
+ "title":"OSGi Bundle Repository",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/osgiagg",
+ "title":"Aggregated OSGi Repository",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/updatesite",
+ "title":"Eclipse updatesite",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/mirrored",
+ "title":"Mirrored Resolver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"resolver/bintray",
+ "title":"Bintray Resolver",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"settings/conflict-managers",
+ "title":"conflict-managers",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/modules",
+ "title":"modules",
+ "children": [
+ {
+ "id":"settings/module",
+ "title":"module",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"settings/outputters",
+ "title":"outputters",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/signers",
+ "title":"signers",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/statuses",
+ "title":"statuses",
+ "children": [
+ {
+ "id":"settings/status",
+ "title":"status",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"settings/triggers",
+ "title":"triggers",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"settings/version-matchers",
+ "title":"version-matchers",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ivyfile",
+ "title":"Ivy Files",
+ "children": [
+ {
+ "id":"ivyfile/info",
+ "title":"info",
+ "children": [
+ {
+ "id":"ivyfile/extends",
+ "title":"extends",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"ivyfile/license",
+ "title":"license",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"ivyfile/ivyauthor",
+ "title":"ivyauthor",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"ivyfile/repository",
+ "title":"repository",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"ivyfile/description",
+ "title":"description",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ivyfile/configurations",
+ "title":"configurations",
+ "children": [
+ {
+ "id":"ivyfile/conf",
+ "title":"conf",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"ivyfile/include",
+ "title":"include",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ivyfile/publications",
+ "title":"publications",
+ "children": [
+ {
+ "id":"ivyfile/artifact",
+ "title":"artifact",
+ "children": [
+ {
+ "id":"ivyfile/artifact-conf",
+ "title":"conf",
+ "children": [
+
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ivyfile/dependencies",
+ "title":"dependencies",
+ "children": [
+ {
+ "id":"ivyfile/dependency",
+ "title":"dependency",
+ "children": [
+ {
+ "id":"ivyfile/dependency-conf",
+ "title":"conf",
+ "children": [
+ {
+ "id":"ivyfile/mapped",
+ "title":"mapped",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ivyfile/dependency-artifact",
+ "title":"artifact",
+ "children": [
+ {
+ "id":"ivyfile/dependency-artifact-conf",
+ "title":"conf",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ivyfile/artifact-exclude",
+ "title":"exclude",
+ "children": [
+ {
+ "id":"ivyfile/artifact-exclude-conf",
+ "title":"conf",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ivyfile/dependency-include",
+ "title":"include",
+ "children": [
+ {
+ "id":"ivyfile/dependency-include-conf",
+ "title":"conf",
+ "children": [
+
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ivyfile/exclude",
+ "title":"exclude",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"ivyfile/override",
+ "title":"override",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"ivyfile/conflict",
+ "title":"conflict",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ivyfile/conflicts",
+ "title":"conflicts",
+ "children": [
+ {
+ "id":"ivyfile/manager",
+ "title":"manager",
+ "children": [
+
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id":"ant",
+ "title":"Ant Tasks",
+ "children": [
+ {
+ "id":"use/artifactproperty",
+ "title":"artifactproperty",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/artifactreport",
+ "title":"artifactreport",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/buildlist",
+ "title":"buildlist",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/buildobr",
+ "title":"buildobr",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/buildnumber",
+ "title":"buildnumber",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/cachefileset",
+ "title":"cachefileset",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/cachepath",
+ "title":"cachepath",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/checkdepsupdate",
+ "title":"checkdepsupdate",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/cleancache",
+ "title":"cleancache",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/configure",
+ "title":"configure",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/convertmanifest",
+ "title":"convertmanifest",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/convertpom",
+ "title":"convertpom",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/deliver",
+ "title":"deliver",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/dependencytree",
+ "title":"dependencytree",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/findrevision",
+ "title":"findrevision",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/fixdeps",
+ "title":"fixdeps",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/info",
+ "title":"info",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/install",
+ "title":"install",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/listmodules",
+ "title":"listmodules",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/makepom",
+ "title":"makepom",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/postresolvetask",
+ "title":"post resolve tasks",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/publish",
+ "title":"publish",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/repreport",
+ "title":"repreport",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/resolve",
+ "title":"resolve",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/resources",
+ "title":"resources",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/retrieve",
+ "title":"retrieve",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/report",
+ "title":"report",
+ "children": [
+ {
+ "id":"yed",
+ "title":"Using yEd to layout report graphs",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"use/settings",
+ "title":"settings",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"use/var",
+ "title":"var",
+ "children": [
+
+ ]
+ }
+ ]
+ },
+ {
+ "id":"standalone",
+ "title":"Using standalone",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"osgi",
+ "title":"OSGi",
+ "children": [
+ {
+ "id":"osgi/osgi-mapping",
+ "title":"OSGi mapping",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"osgi/eclipse-plugin",
+ "title":"Building an Eclipse plugin",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"osgi/standard-osgi",
+ "title":"Building a standard OSGi bundle",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"osgi/target-platform",
+ "title":"Managing a target platform",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"osgi/sigil",
+ "title":"Apache Felix Sigil",
+ "children": [
+
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id":"dev",
+ "title":"Developer doc",
+ "children": [
+ {
+ "id":"extend",
+ "title":"Extending Ivy",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"dev/makerelease",
+ "title":"Making a release",
+ "children": [
+
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial.adoc b/asciidoc/tutorial.adoc
new file mode 100644
index 0000000..cf997c5
--- /dev/null
+++ b/asciidoc/tutorial.adoc
@@ -0,0 +1,46 @@
+
+The best way to learn is to practice! That's what the Ivy tutorials will help you to do, to discover some of the great Ivy features.
+
+For the first tutorial you won't even have to install Ivy (assuming you have Ant and a JDK properly installed), and it shouldn't take more than 30 seconds.
+
+*First Tutorial*
+
+
+. Make sure you have link:http://ant.apache.org/[ant] 1.6.0 or greater and a link:http://java.sun.com[jdk] properly installed +
+
+. Copy link:samples/build.xml[this build file] in an empty directory on your local filesystem (and make sure you name it build.xml) +
+
+. Open a console in this directory and run "ant". That's it! +
+
+If you have any trouble, check the link:http://ant.apache.org/ivy/faq.html[FAQ]. It is most likely related to your internet connection (proxy anyone?).
+
+OK, you've just seen how easy it is to take your first step with Ivy. Go ahead with the other tutorials, but before you do, make sure you have properly link:install.html[installed] Ivy and downloaded the tutorials sources (included in all Ivy distributions, in the `link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=tree;f=src/example[src/example]` directory).
+
+The following tutorials are available:
+
+
+* link:tutorial/start.html[Quick Start] +
+Guides you through your very first steps with ivy.
+
+* link:tutorial/defaultconf.html[Adjusting default settings] +
+Gives you a better understanding of the default settings and shows you how to customize them to your needs.
+
+* link:tutorial/multiple.html[Multiple Resolvers] +
+Teaches you how to configure Ivy to find its dependencies in multiple places.
+
+* link:tutorial/dual.html[Dual Resolver] +
+Helps you configure Ivy to find ivy files in one place and artifacts in another.
+
+* link:tutorial/dependence.html[Project dependencies]</a> +
+A starting point for using Ivy in a multi-project environment.
+
+* link:tutorial/multiproject.html[Using Ivy in multiple projects environment] +
+A more complex example demonstrating the use of Ant+Ivy in a multi-project environment.
+
+* link:tutorial/conf.html[Using Ivy Module Configurations] +
+ Shows you how to use configurations in an ivy file to define sets of artifacts.
+
+* link:tutorial/build-repository.html[Building a repository] +
+Shows you how to build your own enterprise repository.
+
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial/build-repository.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/build-repository.adoc b/asciidoc/tutorial/build-repository.adoc
new file mode 100644
index 0000000..98a0c52
--- /dev/null
+++ b/asciidoc/tutorial/build-repository.adoc
@@ -0,0 +1,44 @@
+
+The link:../use/install.html[install] Ant task lets you copy a module or a set of modules from one repository to another. This is very useful to build and maintain an enterprise or team repository. If you don't want to give access to the public maven 2 repository to the developers on your team (to keep control over which modules are in use in your company or your team for instance), it can sometimes become tiresome to answer the developers request to add new modules or new versions by hand.
+
+Fortunately the link:../use/install.html[install] task is here to help: you can use specific settings for your repository maintenance build which will be used to maintain your target enterprise repository. These settings will point to another repository (for instance the maven 2 public repository) so that you will just have to ask Ivy to install the modules you want with a simple command line.
+
+To demonstrate this, we will first use a basic ivy settings file to show how it works, and then we will use the advanced link:../settings/namespaces.html[namespaces] features to demonstrate how to deal with naming mismatches between the source and target repository.
+
+
+== The project used
+
+The project that we will use is pretty simple. It is composed of an Ant build file, and two ivy settings files.
+
+Here are the public targets that we will use:
+
+[source,shell]
+----
+
+Z:\ivy-repository>ant -p
+Buildfile: build.xml
+
+Main targets:
+
+ clean-cache --> clean the cache
+ clean-repo --> clean the destination repository
+ maven2 --> install module from maven 2 repository
+ maven2-deps --> install module from maven 2 repository with dependencies
+ maven2-namespace --> install module from maven 2 using namespaces
+ maven2-namespace-deps --> install module with dependencies from maven2 repo using namespaces
+Default target: basic
+
+----
+
+
+
+
+
+This project is accessible in the link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=tree;f=src/example/build-a-ivy-repository[src/example/build-a-ivy-repository]
+
+Next steps:
+link:../tutorial/build-repository/basic.html[Basic repository copy]
+link:../tutorial/build-repository/advanced.html[Using namespaces]
+
+
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial/build-repository/advanced.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/build-repository/advanced.adoc b/asciidoc/tutorial/build-repository/advanced.adoc
new file mode 100644
index 0000000..e24c58f
--- /dev/null
+++ b/asciidoc/tutorial/build-repository/advanced.adoc
@@ -0,0 +1,136 @@
+
+Now that you have seen how simple it is to create your own repository from an existing one, you may wonder how you can handle more complex cases, like when the source and destination repositories don't follow the same naming conventions.
+
+
+
+== On the road to a professional repository
+
+In this section, you will learn how to build a *professional* repository. What is a *professional* repository? Our vision is to say that a good quality repository must follow clear rules about projects naming and must offer correct, useable, configurations 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 always the expected one, especially concerning the naming rules used.
+
+This problem is pretty normal when you have an existing repository, and want to benefit from large public repositories which do not follow the same naming conventions. It also shows up because many public repositories do not use a consistent naming scheme. For example, why don't all the apache commons modules use the org.apache.commons organization? Well.. for historical reasons. But if you setup your own repository, you may not want to suffer from the mistakes of history.
+
+Fortunately, Ivy has a very powerful answer to this problem: link:../../settings/namespaces.html[namespaces].
+
+
+== Using namespaces
+
+If you look at the repository built with the link:../../tutorial/build-repository/basic.html[previous tutorial], you will see exactly what we were talking about: all apache commons modules use their own name as their organization.
+
+So let's see what Ivy can do using namespaces (we will dig into details later):
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/install-namespace.txt[]
+
+----
+
+
+
+Now if we look at our repository, it seems to look fine.
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/myrepository-content-namespace.txt[]
+
+----
+
+
+We can even have a look at the commons-lang ivy file in our repository:
+<div>
+[source]
+----
+
+<?xml version="1.0" encoding="UTF-8"?>
+<ivy-module version="1.0">
+ <info organisation="apache"
+ module="commons-lang"
+ revision="1.0"
+ status="integration"
+ publication="20051124062021"
+ namespace="ibiblio-maven2"
+ />
+
+...
+
+----
+
+</div>
+Alright, we see that the organisation is now 'apache'. But where did Ivy pick this up?
+
+=== How does this work ?
+
+Actually, Ivy uses the same repository as before for the source repository, with only one difference: the namespace parameter:
+
+[source]
+----
+
+<ibiblio name="libraries"
+ root="${ibiblio-maven2-root}"
+ m2compatible="true"
+ namespace="maven2"
+/>
+
+----
+
+A namespace is defined by a set of rules. These rules are based on regular expressions and tell Ivy how to convert data from the repository namespace to what is called the system namespace, i.e. the namespace in which Ivy runs most of the time (Note: the Ivy cache always uses the system namespace).
+
+For the namespace we call __maven2__, we have declared several rules. Below is one of the rules:
+
+==== rule handling the imported apache maven1 projects
+
+
+[source]
+----
+<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>
+----
+
+
+[NOTE]
+====
+Note about regular expressions usage :
+In order to distinguish matching regular expressions found in organization, module, and revision, the notation Ivy uses prefixes the matching regular expression with the letters 'o', 'm' and 'r'.
+$o0 : the whole matching value in the organization attribute
+$o1 : the first matching expression group that was marked in the organization attribute
+...
+The same applies for modules : $m0, $m1, ...
+and for revisions : $r0, $r1, ...
+
+====
+
+To understand namespaces,
+
+
+* *fromsystem :* we define here that the projects defined in the system namespace under the organization called "apache" are transformed into the destination namespace into projects whose organization is named with the module name, whatever the revision is. For example, the project apache#commons-lang;1.0 in the system namespace will be translated into commons-lang#commons-lang;1.0 in the maven2 resolver namespace. +
+
+* *tosystem :* we define here the reverse mapping, i.e. how to translate _apache_ projects from maven 2 repo into apache projects in the system namespace. The rule used here tells Ivy that all projects matching `commons-.+` (see it as java regular expression) for their organization 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 defined for others apache projects like ant, etc. +
+
+
+OK, you should now get the idea behind namespaces, so go ahead and look at the `ivysettings-advanced.xml` file in this example. You can test the installation of a module and its dependencies using namespaces.
+
+Run
+
+[source]
+----
+ant maven2-namespace-deps
+----
+
+and you will see the resulting repository is cleaner than the first one we built.
+
+From our experience, investing in creating a namespace is worth the time it costs if you often need to add new modules or revisions of third party libraries in your own repository, where naming rules already exist or are rather strict.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial/build-repository/basic.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/build-repository/basic.adoc b/asciidoc/tutorial/build-repository/basic.adoc
new file mode 100644
index 0000000..b046fb9
--- /dev/null
+++ b/asciidoc/tutorial/build-repository/basic.adoc
@@ -0,0 +1,122 @@
+
+In this first step, we use the link:../../use/install.html[install] Ant task to install modules from the maven 2 repository to a file system based repository. We first install a module by itself, excluding dependencies, then again with its dependencies.
+
+
+== Basic: ivysettings.xml file used
+
+The ivy settings file that we will use is very simple here. It defines two resolvers, __libraries__ and __my-repository__. The first one is used as the source, the second one as the destination. In a typical setup, the second one would be configured using an link:../../settings/include.html[include] that included an existing settings file used by the development team.
+
+
+[source]
+----
+
+<ivysettings>
+ <settings defaultResolver="libraries"
+ defaultConflictManager="all" /> <!-- in order to get all revisions without any eviction -->
+ <caches defaultCacheDir="${ivy.cache.dir}/no-namespace" />
+ <resolvers>
+ <ibiblio name="libraries" m2compatible="true" />
+ <filesystem name="my-repository">
+ <ivy pattern="${dest.repo.dir}/no-namespace/[organisation]/[module]/ivys/ivy-[revision].xml"/>
+ <artifact pattern="${dest.repo.dir}/no-namespace/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
+ </filesystem>
+ </resolvers>
+</ivysettings>
+
+----
+
+
+== install a simple module with no dependencies
+
+Let's have a look at the _maven2_ target.
+
+[source]
+----
+
+ <target name="maven2" depends="init-ivy"
+ description="--> install module from maven 2 repository">
+ <ivy:install settingsRef="basic.settings"
+ organisation="commons-lang" module="commons-lang" revision="1.0"
+ from="${from.resolver}" to="${to.resolver}" />
+ </target>
+
+----
+
+Pretty simple, we call the [[ant:install] task with the settings we have loaded using link:../../use/settings.html[ivy:settings] as usual. We then set the source and destination repositories using the __from__ and __to__ attributes. We used Ant properties for these values here, which helps ease the maintenance of the script, but it's basically the name of our resolvers: 'libraries' for the source and 'my-repository' for the destination.
+
+Here is the Ant call output :
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/install.txt[]
+
+----
+
+
+The trace tells us that the module definition was found using the "libraries" resolver and that the corresponding artifact was downloaded from the maven 2 repository. Then both were published to the filesystem repository (my-repository).
+
+Let's have a look at our repository :
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/myrepository-content.txt[]
+
+----
+
+
+We can see that we now have the commons-lang module version 1.0 in our repository, with a generated ivy.xml file, its jar, and all the md5 and sha1 checksums for future consistency checks when developers use this repository to resolve modules.
+
+
+== install a module with dependencies
+
+Now let's say that we want to be sure all the dependencies of the module we install are available in our repository after the installation. We could either install without dependencies on a staging repository and check the missing dependencies (more control), or use transitive dependency management and ask Ivy to install everything for us (much simpler).
+
+The `maven2-deps` target is very similar to the one described above, except that we explicitly ask for transitive installation.
+
+[source]
+----
+
+ <target name="maven2-deps" depends="init-ivy"
+ description="--> install module from maven 2 repository with dependencies">
+ <ivy:install settingsRef="basic.settings"
+ organisation="org.hibernate" module="hibernate" revision="3.2.5.ga"
+ from="${from.resolver}" to="${to.resolver}" transitive="true" />
+ </target>
+
+----
+
+If you call this target, you will see that Ivy installs not only the hibernate module but also its dependencies:
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/install-deps.txt[]
+
+
+----
+
+
+
+As you can see the installation has failed, if you look at the log you will see that there are missing artifacts on the source repository. This means that you will need to download those artifacts manually, and copy them to your destination repository to complete the installation. Fortunately Ivy uses a best effort algorithm during install, so that everything gets installed except the missing artifacts. (Note: these missing artifacts are not in the public maven repository due to licensing issues)
+
+You may also have noticed that Ivy installed 2 different revisions of commons-logging (1.0.2, 1.0.4). This is due to the fact that we used the "no conflict" link:../../settings/conflict-managers.html[conflict manager] in the ivysettings file.
+
+We do not want to evict any modules because we are building our own repository. Indeed if we get both commons-logging 1.0.2 and 1.0.4 it's because some modules among the transitive dependencies of hibernate depend on 1.0.2 and others on 1.0.4. If we got only 1.0.4, the module depending on 1.0.2 would be inconsistent in your own repository (depending on a version you don't have installed). Thus developers using this module directly would run into a problem.
+
+If you now have a closer look at your repository, you will probably notice that it isn't an exact replication of the original one. Let's have a look at the directory of one module:
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/myrepository-content-deps.txt[]
+
+
+----
+
+
+
+As you can see there is no pom here (pom is the module metadata format used by maven 2, available on the maven 2 repository). Instead you can see there's an ivy file, which is actually the original hibernate pom converted into an ivy file. So now you have a true Ivy repository with ivy files, where you can use the full power of Ivy if you want to adjust the module metadata (module configurations, fine grain exclusions and transitivity control, per module conflict manager, ...).
+
+OK, enough for this simple repository installation, the link:../../tutorial/build-repository/advanced.html[next tutorial] will show how you can deal with more complex cases where your source and destination repositories do not follow the same naming conventions.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial/conf.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/conf.adoc b/asciidoc/tutorial/conf.adoc
new file mode 100644
index 0000000..82859ee
--- /dev/null
+++ b/asciidoc/tutorial/conf.adoc
@@ -0,0 +1,204 @@
+
+This tutorial introduces the use of module configurations in ivy files. Ivy module configurations are indeed a very important concept. Someone even told me one day that using Ivy without using configurations is like eating a good cheese without touching the glass of Chateau Margaux 1976 you have just poured :-)
+
+More seriously, configurations in Ivy can be better understood as views on your module, and you will see how they can be used effectively here.
+
+Reference documentation on configurations can be found link:../terminology.html[here] and link:../ivyfile/configurations.html[here].
+
+== Introduction
+
+Source code is available in `src/example/configurations/multi-projects`.
+We have two projects :
+ - filter-framework is a library that defines an api to filter String arrays and two implementations of this api.
+ - myapp is a very small app that uses filter-framework.
+
+The filter-framework library project produces 3 artifacts:
+ - the api jar,
+ - an implementation jar with no external dependencies,
+ - a second implementation jar that needs commons-collections to perform.
+
+The application only needs the api jar to compile and can use either of the two implementations at runtime.
+
+
+== The library project
+
+The first project we'll look at in this tutorial is filter-framework. In order to have a fine-grained artifacts publication definition, we defined several configurations, each which maps to a set of artifacts that other projects can make use of.
+
+=== The ivy.xml file
+
+
+
+
+[source]
+----
+
+<ivy-module version="1.0">
+ <info organisation="org.apache" 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="commons-collections" name="commons-collections" rev="3.1" conf="cc-impl->default"/>
+ <dependency org="junit" name="junit" rev="3.8" conf="test->default"/>
+ </dependencies>
+</ivy-module>
+
+----
+
+
+
+=== Explanation
+
+As you can see, we defined 4 configurations, with 3 being public and 1 private. (the junit dependency for testing).
+The 2 implementation configurations, *homemade-impl* and *cc-impl* extend the *api* configuration so that all artifacts defined in *api* will also be part of the extending configuration.
+
+In the publications tag, we defined the artifacts we produce (jars in this case) and we assign them to a configuration. When others use our library they will have a flexible way to ask for what they need.
+
+
+=== See it in action
+
+The filter-framework project is built using Ant. Open a shell in the root directory of the project and type `ant`.
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/configurations-lib.txt[]
+
+----
+
+
+The Ant default target is publish. This target uses Ivy to publish our library binaries to a local repository. Since we do not specify any repository path, the default one is used. (`${home.dir}/.ivy2/local/org.apache/filter-framework/`) At this point, we are ready to use our library.
+
+
+== The application project
+
+
+Now that we have shipped (published) our fantastic filter library, we want to use it! The tutorial comes with a sample application called myapp.
+
+=== The `ivy.xml` file
+
+
+
+
+[source]
+----
+
+<ivy-module version="1.0">
+ <info organisation="org.apache" 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="org.apache" name="filter-framework" rev="latest.integration" conf="build->api; noexternaljar->homemade-impl; withexternaljar->cc-impl"/>
+ </dependencies>
+</ivy-module>
+
+----
+
+
+
+=== Explanation
+
+We create 3 configurations that define the different ways we want to use the application. The *build* configuration defines the compile-time dependencies, and thus only needs the api conf from the filter-framework project. The other two configurations define runtime dependencies. One will only use our "home-made" jar, and the other will use an external jar.
+
+We also defined a dependency on our previously built library. In this dependency, we use configuration mappings to match ours with the dependency's configurations. You can find more information about configuration mapping link:../ivyfile/configurations.html[here]
+
+
+. *build->api* : here we tell Ivy that our *build* configuration depends on the *api* configuration of the dependency +
+
+. *noexternaljar->homemade-impl* : here we tell Ivy that our *noexternaljar* configuration depends on the *homemade-impl* configuration of the dependency. +
+
+. *withexternaljar->cc-impl* : here we tell Ivy that our *withexternaljar* configuration depends on the *cc-impl* configuration of the dependency +
+
+Note that we never declare any of the dependency's artifacts we need in each configuration: it's the dependency module's ivy file which declares the published artifacts and which should be used in each configuration.
+
+In the Ant `build.xml` file, we defined a 'resolve' target as follow:
+
+
+[source]
+----
+
+<target name="resolve" description="--> retreive dependencies with ivy">
+ <ivy:retrieve pattern="${ivy.lib.dir}/[conf]/[artifact].[ext]"/>
+</target>
+
+----
+
+When we call this target, Ivy will do a resolve using our `ivy.xml` file in the root folder and then retrieve all the artifacts. The artifacts retrieved are kept in separate folders according to the configurations they belong to. Here is how your lib directory should look after a call to this target:
+
+[source,shell]
+----
+
+ Repertoire 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
+
+ Repertoire 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
+
+ Repertoire 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
+
+ Repertoire 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
+
+----
+
+
+As you can see, for each configuration we have now a set of jars.
+
+Let's try to launch our app.
+
+
+=== See it in action
+
+Use Ant to run the application. The default Ant target is __run-cc__ and will launch the application using the Apache commons-collections implementation.
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/configurations-runcc.txt[]
+
+----
+
+
+Launching the application using the homemade implementation is also straightforward.
+type `ant run-hm`
+
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/configurations-runhm.txt[]
+----
+
+
+Nice! We got the same result, but we can see that the implementation classes are different.
+
+
+== Conclusion
+
+*You should use configurations as often as possible.* Configurations are a very important concept in Ivy. They allow you to group artifacts and give the group a meaning. When you write ivy files for projects that are intended for use by others, use configurations to allow people to get only what they need, without having to specify them one by one in their own dependency list.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial/defaultconf.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/defaultconf.adoc b/asciidoc/tutorial/defaultconf.adoc
new file mode 100644
index 0000000..25dbf9d
--- /dev/null
+++ b/asciidoc/tutorial/defaultconf.adoc
@@ -0,0 +1,306 @@
+
+Ivy comes bundled with some default settings which makes it pretty simple to use in a typical environment. This tutorial, which is close to a reference document, explains what those default settings are and how they can be adjusted to your needs.
+
+To fully understand the concept of settings and what you can do with them, we suggest reading other tutorials related to settings (like link:../tutorial/multiple.html[Multiple Resolvers] and link:../tutorial/dual.html[Dual Resolver]) or the link:../settings.html[Settings Files] reference documentation.
+
+
+== Concept
+
+The default settings include 3 types of repositories:
+
+
+* local +
+ a repository which is private to the user.
+
+* shared +
+ a repository which is shared between all the members of a team
+
+* public +
+ a public repository on which most modules, and especially third party modules, can be found
+
+
+Note that if you work alone, the distinction between a local and shared repository is not very important, but there are some things you should know to distinguish them.
+
+Now let's describe each of these repository concepts in more detail. We will describe how they are set up physically later.
+
+=== Local
+
+The local repository is particularly useful when you want to do something without being disturbed by anything else happening in the environment. This means that whenever Ivy is able to locate a module in this repository it will be used, no matter what is available in others.
+
+For instance, if you have a module declaring a dependency on the module __foo__ with a revision of __latest.integration__, then if a revision of __foo__ is found in the local repository, it will be used, _even if a more recent revision is available in other repositories_.
+
+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 publishes 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 repository, 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.
+
+=== Shared
+
+As its name suggest, the shared repository is aimed to be shared among a whole development team. It is a place where you can publish your team's private modules, and it's also a place where you can put modules not available in the public repository (sun jars, for instance). You can also put modules here that are simply inaccurate in a public repository (bad or incomplete module descriptors for instance).
+
+Note that modules can be split across the shared repository and the public one: For example, you can have the module descriptor in the shared repository and the artifacts in the public one.
+
+=== Public
+
+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.
+
+== Setting up the repositories
+
+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 use the same root in your filesystem. Referenced as `${ivy.default.ivy.user.dir}`, this is by default the directory `.ivy2` in your user home.
+
+Note that several things can be done by setting Ivy variables. To set them without defining your own `ivysettings.xml` file, you can:
+
+* set an Ant property before any call to Ivy in your build file if you use Ivy from Ant +
+
+* set an environment variable if you use Ivy from the command line +
+
+For example:
+
+[source]
+----
+
+<target name="resolve">
+ <property name="ivy.default.ivy.user.dir" value="/path/to/ivy/user/dir"/>
+ <ivy:resolve />
+</target>
+
+----
+
+Next we will show you how to override default values for the different kinds of repositories. Note that you can find what the default values are below in the details of the default settings.
+
+=== Local
+
+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. No problem, you just have to set the following Ivy variable to the directory you want to use:
+[source]
+----
+ivy.local.default.root
+----
+
+. For instance:
+
+[source]
+----
+ivy.local.default.root=/opt/ivy/repository/local
+----
+
+.
+
+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:
+
+[source]
+----
+ivy.local.default.ivy.pattern
+----
+
+gives the pattern to find ivy files
+
+[source]
+----
+ivy.local.default.artifact.pattern
+----
+
+gives the pattern to find artifacts
+For example:
+
+[source]
+----
+
+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]
+
+----
+
+
+=== Shared
+
+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 the
+[source]
+----
+ivy.shared.default.root
+----
+
+variable to specify a different directory. Moreover, you can also configure the layout with variables similar to the ones used for the local repository:
+
+[source]
+----
+ivy.shared.default.ivy.pattern
+----
+
+gives the pattern to find ivy files
+
+[source]
+----
+ivy.shared.default.artifact.pattern
+----
+
+gives the pattern to find artifacts
+For example:
+
+[source]
+----
+
+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]
+
+----
+
+
+=== Public
+
+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 link:../bestpractices.html[Best practices] 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.
+
+_In 1.4 version Ivy was using ivyrep as the default resolver, if you want to restore this, set
+ivy.14.compatible=true as an ant property_
+
+
+== Going further
+
+OK, so we have seen how to easily change the settings of the three main repositories. But what if my shared repository is on a web server? What if you don't want to use maven 2 repository as the public repository? What if ...
+
+No problem, Ivy is very flexible and can be configured with specific settings to match your needs and environment. But before considering writing your own settings from scratch, we suggest reading the following where you will learn how to leverage a part of the default settings and adjust the rest.
+
+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 `ivysettings.xml` which is packaged in the Ivy jar. Here is this settings file:
+
+[source]
+----
+
+<ivysettings>
+ <settings defaultResolver="default"/>
+ <include url="${ivy.default.settings.dir}/ivysettings-public.xml"/>
+ <include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/>
+ <include url="${ivy.default.settings.dir}/ivysettings-local.xml"/>
+ <include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/>
+ <include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/>
+</ivysettings>
+
+----
+
+OK, so not much info here, except a lot of inclusions. These inclusions have been done on purpose so that you can easily change only one part of the ivysettings and easily benefit from the rest. For example, if you want to define your own public resolver, you will just have to configure Ivy with an ivysettings like the following:
+
+[source]
+----
+
+<ivysettings>
+ <settings defaultResolver="default"/>
+ <include url="http://myserver/ivy/myivysettings-public.xml"/>
+ <include url="${ivy.default.settings.dir}/ivysettings-shared.xml"/>
+ <include url="${ivy.default.settings.dir}/ivysettings-local.xml"/>
+ <include url="${ivy.default.settings.dir}/ivysettings-main-chain.xml"/>
+ <include url="${ivy.default.settings.dir}/ivysettings-default-chain.xml"/>
+</ivysettings>
+
+----
+
+Note that only the `ivysettings-public.xml` inclusion has changed to include a homemade 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's default settings files are (i.e. packaged in the jar).
+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:
+
+[source]
+----
+
+<ivysettings>
+ <resolvers>
+ <filesystem name="public">
+ <ivy pattern="/path/to/my/public/rep/[organisation]/[module]/ivy-[revision].xml" />
+ <artifact pattern="/path/to/my/public/rep/[organisation]/[module]/[artifact]-[revision].[ext]" />
+ </filesystem>
+ </resolvers>
+</ivysettings>
+
+----
+
+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:
+*ivysettings-public.xml*
+
+[source]
+----
+
+<ivysettings>
+ <resolvers>
+ <ibiblio name="public" m2compatible="true"/>
+ </resolvers>
+</ivysettings>
+
+----
+
+*ivysettings-shared.xml*
+
+[source]
+----
+
+<ivysettings>
+ <property name="ivy.shared.default.root" value="${ivy.default.ivy.user.dir}/shared" override="false"/>
+ <property name="ivy.shared.default.ivy.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/>
+ <property name="ivy.shared.default.artifact.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/>
+ <resolvers>
+ <filesystem name="shared">
+ <ivy pattern="${ivy.shared.default.root}/${ivy.shared.default.ivy.pattern}" />
+ <artifact pattern="${ivy.shared.default.root}/${ivy.shared.default.artifact.pattern}" />
+ </filesystem>
+ </resolvers>
+</ivysettings>
+
+----
+
+*ivysettings-local.xml*
+
+[source]
+----
+
+<ivysettings>
+ <property name="ivy.local.default.root" value="${ivy.default.ivy.user.dir}/local" override="false"/>
+ <property name="ivy.local.default.ivy.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/>
+ <property name="ivy.local.default.artifact.pattern" value="[organisation]/[module]/[revision]/[type]s/[artifact].[ext]" override="false"/>
+ <resolvers>
+ <filesystem name="local">
+ <ivy pattern="${ivy.local.default.root}/${ivy.local.default.ivy.pattern}" />
+ <artifact pattern="${ivy.local.default.root}/${ivy.local.default.artifact.pattern}" />
+ </filesystem>
+ </resolvers>
+</ivysettings>
+
+----
+
+*ivysettings-main-chain.xml*
+
+[source]
+----
+
+<ivysettings>
+ <resolvers>
+ <chain name="main" dual="true">
+ <resolver ref="shared"/>
+ <resolver ref="public"/>
+ </chain>
+ </resolvers>
+</ivysettings>
+
+----
+
+*ivysettings-default-chain.xml*
+
+[source]
+----
+
+<ivysettings>
+ <resolvers>
+ <chain name="default" returnFirst="true">
+ <resolver ref="local"/>
+ <resolver ref="main"/>
+ </chain>
+ </resolvers>
+</ivysettings>
+
+----
+
+There you go, you should have enough clues to configure Ivy the way you want. Check the link:../settings.html[settings documentation] to see if what you want to do is possible, and go ahead!
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial/dependence.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/dependence.adoc b/asciidoc/tutorial/dependence.adoc
new file mode 100644
index 0000000..72a8bb1
--- /dev/null
+++ b/asciidoc/tutorial/dependence.adoc
@@ -0,0 +1,255 @@
+
+This tutorial will show you how to use Ivy when one of your projects depends on another.
+
+For our example, we will have two projects, depender and dependee, where the depender project uses/requires the dependee project. This example will help illustrate two things about Ivy:
+
+
+* that dependencies defined by parent projects (dependee) will automatically be retrieved for use by child projects (depender) +
+
+* that child projects can retrieve the "latest" version of the dependee project +
+
+
+== projects used
+
+
+=== dependee
+
+The dependee project is very simple. It depends on the apache library commons-lang and contains only one class: `standalone.Main` which provides two services:
+
+
+* return the version of the project +
+
+* capitalize a string using `org.apache.commons.lang.WordUtils.capitalizeFully` +
+
+Here is the content of the project:
+
+
+* build.xml: the ant build file for the project +
+
+* ivy.xml: the project ivy file +
+
+* src tandalone\Main.java: the only class of the project +
+
+Take a look at the *ivy.xml* file:
+
+[source]
+----
+
+<ivy-module version="1.0">
+ <info organisation="org.apache" module="dependee"/>
+ <dependencies>
+ <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
+ </dependencies>
+</ivy-module>
+
+----
+
+The ivy file declares only one dependency, that being the apache commons-lang library.
+
+=== depender
+
+The depender project is very simple as well. It declares only one dependency on the latest version of the dependee project, and it contains only one class, `depending.Main`, which does 2 things:
+
+
+* gets the version of the standalone project by calling `standalone.Main.getVersion()` +
+
+* transforms a string by calling `standalone.Main.capitalizeWords(str)` +
+
+Take a look at the `ivy.xml` file:
+
+[source]
+----
+
+<ivy-module version="1.0">
+ <info organisation="org.apache" module="depender"/>
+ <dependencies>
+ <dependency name="dependee" rev="latest.integration" />
+ </dependencies>
+</ivy-module>
+
+----
+
+
+== settings
+
+The Ivy settings are defined in two files located in the settings directory:
+
+
+* `ivysettings.properties`: a property file +
+
+* `ivysettings.xml`: the file containing the settings +
+
+
+Let's have a look at the `ivysettings.xml` file:
+
+[source]
+----
+
+<ivysettings>
+ <properties file="${ivy.settings.dir}/ivysettings.properties"/>
+ <settings defaultResolver="libraries" />
+ <caches defaultCacheDir="${ivy.settings.dir}/ivy-cache" />
+ <resolvers>
+ <filesystem name="projects">
+ <artifact pattern="${repository.dir}/[artifact]-[revision].[ext]" />
+ <ivy pattern="${repository.dir}/[module]-[revision].xml" />
+ </filesystem>
+ <ibiblio name="libraries" m2compatible="true" usepoms="false" />
+ </resolvers>
+ <modules>
+ <module organisation="org.apache" name="dependee" resolver="projects"/>
+ </modules>
+</ivysettings>
+
+----
+
+The file contains four main tags: properties, settings, resolvers and modules.
+
+=== properties
+
+This tag loads some properties for the Ivy process, just like Ant does.
+
+=== settings
+
+This tag initializes some parameters for the Ivy process. In this case, the directory that Ivy will use to cache artifacts will be in a sub directory called ivy-cache of the directory containing the `ivysettings.xml` file itself.
+The second parameter, tells Ivy to use a resolver named "libraries" as its default resolver. More information can be found in the link:../settings.html[settings reference documentation].
+
+=== resolvers
+
+This tag defines the resolvers to use. Here we have two resolvers defined: "projects" and "libraries".
+The filesystem resolver called "projects" is able to resolve the internal dependencies by locating them on the local filesystem.
+The ibiblio resolver called "libraries" is able to find dependencies on the maven 2 repository, but doesn't use maven poms.
+
+=== modules
+
+The modules tag allows you to configure which resolver should be used for which module. Here the setting tells Ivy to use the "projects" resolver for all modules having an organisation of `org.apache` and module name of `dependee`. This actually corresponds to only one module, but a regular expression could be used, or many other types of expressions (like glob expressions).
+
+All other modules (i.e. all modules but org.apache#dependee), will use the default resolver ("libraries").
+
+== walkthrough
+
+
+
+=== step 1: preparation
+
+Open a DOS or shell window, and go to the `src/example/dependence` directory.
+
+
+
+=== step 2: clean directory tree
+
+On the prompt type: `ant`
+This will clean up the entire project directory tree. You can do this each time you want to clean up this example.
+
+
+
+=== step 3: publication of dependee project
+
+Go to `dependee` directory and publish the project
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/dependence-standalone.txt[]
+
+----
+
+
+What we see here:
+
+
+* the project depends on 1 library (1 artifact) +
+
+* the library was not in the Ivy cache and so was downloaded (1 downloaded) +
+
+* the project has been released under version number 1 +
+
+
+As you can see, the call to the publish task has resulted in two main things:
+
+
+* the delivery of a resolved ivy file to `build/ivy.xml`. +
+This has been done because by default, the publish task not only publishes artifacts, but also its ivy file. So it has looked to the path where the ivy file to publish should be, using the artifactspattern: `${build.dir}/[artifact].[ext]`. For an ivy file, this resolves to `build/ivy.xml`. Because this file does not exist, it automatically makes a call to the deliver task which delivers a resolved ivy file to this destination.
+
+
+* the publication of artifact 'dependee' and its resolved ivy file to the repository. +
+Both are just copies of the files found in the current project, or more precisely, those in the `build` directory. This is because the artifactspattern has been set to `${build.dir}/[artifact].[ext]`, so the dependee artifact is found at `build/dependee.jar` and the ivy file in `build/ivy.xml`. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to `repository\dependee-1.jar` and to `repository\dependee-1.xml`, respecting the artifact and ivy patterns of our settings (see above).
+
+
+
+
+=== step 4: running the depender project
+
+Go to directory depender and run `ant`
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/dependence-depending.txt[]
+
+----
+
+
+What we see here:
+
+
+* the project depends on 2 libraries (2 artifacts) +
+
+* one of the libraries was in the cache because there was only 1 download (1 downloaded) +
+
+* Ivy retrieved version 1 of the project "dependee". The call to `standalone.Main.getVersion()` has returned 1. If you look in the `depender/lib` directory, you should see `dependee-1.jar` which is the version 1 artifact of the project "dependee" +
+
+* the call to `standalone.Main.capitalizeWords(str)` succeed, which means that the required library was in the classpath. If you look at the `lib` directory, you will see that the library `commons-lang-2.0.jar` was also retrieved. This library was declared as a dependency of the "dependee" project, so Ivy retrieves it (transitively) along with the dependee artifact. +
+
+
+
+
+=== step 5: new version of dependee project
+
+Like we did before in step 3, publish the dependee project again. This will result in a new version of the project being published.
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/dependence-standalone-2.txt[]
+
+----
+
+
+Now if you look in your repository folder, you will find 2 versions of the dependee project.
+Let's look at it:
+
+[source,shell]
+----
+I:\dependee>dir ..\settings\repository /w
+
+[.] [..] dependee-1.jar dependee-1.xml dependee-2.jar dependee-2.xml
+
+I:\dependee>
+----
+
+
+
+OK, now our repository contains two versions of the project *dependee*, so other projects can refer to either version.
+
+
+=== step 6: get the new version in _depender_ project
+
+What should we expect if we run the depender project again? It should:
+
+
+* retrieve version 2 as the latest.integration version of the dependee project +
+
+* display version 2 of dependee project +
+
+Let's try it!!
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/dependence-depending-2.txt[]
+
+----
+
+
+OK, we got what we expected as the `run` target shows that we are using version 2 of the main class of the dependee project. If we take a look at the resolve target results, we see that one artifact has been downloaded to the ivy cache. In fact, this file is the same version 2 of the dependee project that is in the repository, but now all future retrievals will pull it from your ivy-cache directory.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial/dual.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/dual.adoc b/asciidoc/tutorial/dual.adoc
new file mode 100644
index 0000000..44c3287
--- /dev/null
+++ b/asciidoc/tutorial/dual.adoc
@@ -0,0 +1,140 @@
+
+In some cases, your module descriptions (i.e. Ivy files, maven poms) are located separately from the module artifacts (i.e. jars). So what can you do about it?
+
+Use a Dual resolver! And this tutorial will show you how.
+
+
+== project description
+
+Let's have a look at the `src/example/dual` directory in your Ivy distribution.
+It contains a build file and 3 directories:
+
+
+* settings: contains the ivy settings file +
+
+* repository: a sample repository of ivy files +
+
+* project: the project making use of Ivy with dual resolver +
+
+
+
+=== the dual project
+
+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:
+
+
+* build.xml: the ant build file for the project +
+
+* ivy.xml: the ivy project file +
+
+* src\example\Hello.java: the only class of the project +
+
+
+Let's have a look at the `ivy.xml` file:
+
+[source]
+----
+
+<ivy-module version="1.0">
+ <info organisation="org.apache" module="hello-ivy"/>
+ <dependencies>
+ <dependency org="commons-httpclient" name="commons-httpclient" rev="2.0.2"/>
+ <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
+ </dependencies>
+</ivy-module>
+
+----
+
+As you can see, nothing special here... Indeed, Ivy's philosophy is to keep ivy files independent of the way dependencies are resolved.
+
+
+=== the *ivy* settings
+
+The ivy settings are defined in the `ivysettings.xml` file located in the `settings` directory. Here is what it contains, followed by an explanation.
+
+
+[source]
+----
+
+<ivysettings>
+ <settings defaultResolver="dual-example"/>
+ <resolvers>
+ <dual name="dual-example">
+ <filesystem name="ivys">
+ <ivy pattern="${ivy.settings.dir}/../repository/[module]-ivy-[revision].xml" />
+ </filesystem>
+ <ibiblio name="ibiblio" m2compatible="true" usepoms="false" />
+ </dual>
+ </resolvers>
+</ivysettings>
+
+----
+
+Here we configured one resolver, the default one, which is a dual resolver. This dual resolver has two sub resolvers: the first is what is called the "ivy" or "metadata" resolver of the dual resolver, and the second one is what is called the "artifact" resolver. It is important that the dual resolver has exactly two sub resolvers in this given order.
+
+The metadata resolver, here a filesystem one, is used only to find module descriptors, in this case Ivy files. The setting shown here tells Ivy that all ivy files are in the `repository` directory, named with the pattern: `[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`. This file matches the pattern, so it will be found by the 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 necessary, since the second resolver in a dual resolver (the artifact resolver) is never asked to find module metadata.
+
+
+== walkthrough
+
+
+
+=== step 1 : preparation
+
+Open a DOS or shell window, and go to the `dual` directory.
+
+
+
+=== step 2 : clean up
+
+On the prompt type : `ant`
+
+This will clean up the entire project directory tree (compiled classes and retrieved libs) and the Ivy cache. You can run this each time you want to clean up this example.
+
+
+
+=== step 3 : run the project
+
+Go to the project directory. And simply run `ant`.
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/dual.txt[]
+
+----
+
+
+
+
+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:
+
+[source]
+----
+
+<ivy-module version="1.0">
+ <info
+ organisation="commons-httpclient"
+ module="commons-httpclient"
+ revision="2.0.2"
+ status="release"
+ publication="20041010174300"/>
+ <dependencies>
+ <dependency org="commons-logging" name="commons-logging" rev="1.0.4" conf="default"/>
+ </dependencies>
+</ivy-module>
+
+----
+
+
+
+So everything seemed to work. The ivy file was found in the `repository` directory and the artifacts have been downloaded from ibiblio.
+
+This kind of setup can be useful if you don't want to rely on the maven 2 repository for metadata, or if you want to take full advantage of Ivy files for some or all modules. Combining chain and dual resolvers should give you enough flexibility to meet almost any requirement.
+
+For full details about the dual resolver, have a look at the corresponding link:../resolver/dual.html[reference documentation].
\ No newline at end of file