ant-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jaiki...@apache.org
Subject [17/29] ant-ivy git commit: Initial auto-converted .adoc files from xooki2asciidoc convertor
Date Mon, 19 Jun 2017 01:59:00 GMT
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/osgi/eclipse-plugin.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/osgi/eclipse-plugin.adoc b/asciidoc/osgi/eclipse-plugin.adoc
new file mode 100644
index 0000000..d49ac83
--- /dev/null
+++ b/asciidoc/osgi/eclipse-plugin.adoc
@@ -0,0 +1,88 @@
+
+
+
+[NOTE]
+====
+
+<table class="notice">
+  <tr>
+    <td style="vertical-align: top"><svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="1em" version="1.1" y="0px" x="0px" viewBox="0 0 980.02045 886.1"><g fill="red"><path d="m972.9158,794.5l-426.1,-761.1c-10.5,-20 -31.1,-32.7 -53.7,-33.4l-1.7,0c-22,0 -42.4,11.5 -53.7,30.5l-428.9,761c-11.5,19.4 -11.8,43.3 -0.6,62.9c11.1,19.6 31.9,31.7 54.4,31.7l854.9,0c21.9,0 42.2,-11.5 53.5,-30.2s12,-42 1.9,-61.4zm-910.4,29.2l428.9,-761.1l426,761.1l-854.9,0z"/><path d="m490.3158,626.7c-36.5,0 -62.1,25.6 -62.1,62.8c0,35.8 24.9,62.8 60.7,62.8l1.4,0c37.3,0 61.5,-27 61.5,-62.8c-0.7,-37.3 -24.9,-62.8 -61.5,-62.8z"/><path d="m451.0158,592.1l78.7,0l15.2,-312.6l-109,0l15.1,312.6z"/></g></svg></td>
+    <td>
+    Note that this feature is considered as *experimental*. It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discussed your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev].
+
+====
+
+
+This page describes how to build an Eclipse&#153; plugin with Apache Ivy&#153; and its OSGi&#153; capabilities.
+
+
+== Quick setup
+
+
+In few steps, we will setup a build to compile and package an Eclipse plugin.
+
+
+
+. download this <a href="../samples/eclipse-plugin/ivy.xml">ivy.xml<a>, this <a href="../samples/eclipse-plugin/ivysettings.xml">ivysettings.xml</a>, this <a href="../samples/eclipse-plugin/ivysettings.properties">ivysettings.properties</a>, this <a href="../samples/eclipse-plugin/build.xml">build.xml</a>, and put them into your plugin folder; +
+
+. in the ivysettings.properties, specify the location of the plugins folder of your Eclipse target; +
+
+. in the ivy.xml, change the symbolic name declared in the extends element; +
+
+. __(optional)__ by default the build.xml is expecting the sources to be in the `src` folder. You may want to edit it if it is not the case +
+
+. __(optional)__ if Ivy is not in Ant's classpath, get the jar of <a href="../download.html">Apache Ivy</a> and edit the build.xml accordingly (see the comments at the begining of the file) +
+
+
+And that's it ! Now let's use it.
+
+First, Ivy needs to aggregate the OSGi metadata of the target platform. To do so just launch:
+
+[source]
+----
+ant buildobr
+----
+
+You need to run that command only once. Or each time your target platform get modified.
+
+Then to resolve and build, just run:
+
+[source]
+----
+ant build
+----
+
+
+=== Eclipse setup
+
+
+You probably have already configured your project in Eclipse via the PDE. Let's see how to chnage that and use <a href="http://ant.apache.org/ivy/ivyde/">Apache IvyDE</a>.
+
+
+
+. so first remove from your project's classpath the PDE dependencies container; +
+
+. then right click on the ivy.xml you just added and select "Add Ivy library"; +
+
+. in the configuration panel of the IvyDE classpath container, as the settings file put '${workspace_loc:mypluginproject/ivysettings.xml}'; +
+
+. click finish and your Eclipse project should build now. +
+
+
+Nota Bene: to be resolved correctly Ivy is relying on the aggregated metadata of your target platform. Even if you want to only build with Eclipse, you will have to run the command `ant obrindex` at least one time.
+
+
+== Details on the setup
+
+
+
+=== The repository
+
+
+When building an Eclipse plugin, we are relying on a "target platform", the Eclipse installation we want our plugin to be eventually installed into. For Ivy, this will represent the repository of artifacts.
+
+Ivy needs an aggragation of the OSGi metadata in order to resolve a such repository. The Ant task <a href="../use/buildobr.html">buildobr</a> build a OBR (OSGi Bundle Repository) descriptor file from a set of OSGi bundles. So here we are using this Ant task to gather OSGi metadata from the Eclipse plugins in the "target platform". In the above exemple, the file is build in `target/repo-eclipse.xml`.
+
+The plugin to be build has then a ivy.xml file describing its depedencies to be used by Ivy. Since the actual depedencies are in the MANIFEST.MF file, in the ivy.xml file we specify that it extends `META-INF/MANIFEST.MF`. So there not much dependencies specified in the ivy.xml. But as Ivy doesn't support the `Bundle-Fragment` OSGi feature, the ivy.xml can help specify the missing dependencies. 
+
+Having this setup, it is then a standard Ant+Ivy build. Ivy computes the classpath to be then used by the `javac` tasks. Note that `javac` is not aware of the OSGi metadata and is then incapable of failing to compile if private packages are accessed.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/osgi/osgi-mapping.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/osgi/osgi-mapping.adoc b/asciidoc/osgi/osgi-mapping.adoc
new file mode 100644
index 0000000..818d6f6
--- /dev/null
+++ b/asciidoc/osgi/osgi-mapping.adoc
@@ -0,0 +1,242 @@
+
+
+This page is a description of how OSGi&#153; dependencies are mapped into Apache Ivy&#153; ones
+
+Goal: the purpose of this mapping is to transform an OSGi manifest into an ivy.xml, so Ivy can understand OSGi bundles and resolve them. We don't want to do the reverse here.
+
+
+=== Bundle Symbolic name / Ivy organisation and module
+
+
+In OSGi a bundle is identified by its symbolic name. In Ivy there is a notion of organisation and module name.
+
+The choosen mapping is:
+
+
+* The organisation is "bundle" (transitive dependencies like pakages or services have their own organisations, "package" and "service") +
+
+* The module name is the symbolic name +
+
+
+
+[]
+|=======
+| *OSGi* | *Ivy* 
+| `Bundle-SymbolicName: com.acme.product.plugin` |
+
+[source]
+----
+
+<info organisation="bundle" module="com.acme.product.plugin" />
+
+----
+
+
+|=======
+
+
+
+=== Version and version range
+
+
+The OSGi specification is defining a version as a composition of 3 numbers and an arbitrary qualifier. This fit well into the lazy definition of Ivy. We will just have to use a special latest strategy in Ivy.
+
+Then about version range, Ivy will understand correctly fully defined range as `[1.2.3,1.4.9)` or `(1.2.3,1.4.9]`. But for OSGi version range defined as in `1.2.3`, it has to be transformed into `[1.2.3,)`
+
+
+[]
+|=======
+| *OSGi* | *Ivy* 
+| `Bundle-Version: 3.3.3` | `revision="3.3.3"` 
+|`Require-Bundle: com.acme.product.plugin;bundle-version="3.2.1"` |
+
+[source]
+----
+
+<dependency org="bundle" name="com.acme.product.plugin" rev="[3.2.1,)" />
+
+----
+
+
+|=======
+
+
+
+=== Ivy configurations
+
+
+The Ivy configuration is a notion that doesn't exist explicitely in OSGi, but some notion of the latter can be expressed with that configurations.
+
+First the mapping is defining three configurations:
+
+
+* `default` : it will contain every required dependency (transitively) +
+
+* `optional` : it will contain every optional dependency and every required depedency the the first degree dependencies. +
+
+* `transitive-optional` : it will contain every optional dependency (optional transitively) +
+
+
+Then there will be some configurations used for the `use` parameter of the `Import-Package` OSGi manifest header. All of these kinds of configuration have their names starting with "use_". See in the next section.
+
+
+=== OSGi capabilities
+
+
+Generally speaking, declaring capabilities in an ivy.xml is useless (in the scope of this mapping which is to transform an OSGi manifest into an ivy.xml and not the reverse). In the resolve process we want to find the bundle which have the capability matching the expected requirement. In Ivy, if we are about to get the ivy.xml of a module, we are getting the bundle so we already have reached the requirement.
+
+So OSGi capabilities of bundles in a repo will be gathered direclty from the manifests to passed directly to the Ivy resolver, no need to express them into ivy.xml, except for the Export-Package, see the next section.
+
+
+==== Export-Package
+
+
+Exported package are declaring capabilities of the bundle in term of package. But they also declare dependencies between the declared package via the parameter `use`. These dependencies have to be declared in the ivy.xml. And we will use Ivy configurations for that.
+
+First, each exported package will be declared in the ivy.xml as a configuration. The name of the configuration will start will `use_` and will finished with the name of that package.
+
+Then each time an exported package is declared to use some other one, it will be mapped as a dependency between the Ivy configurations coresponding to those packages. 
+
+
+[]
+|=======
+| *OSGi* | *Ivy* 
+| `Export-Package: com.acme.product.plugin.utils` |
+
+[source]
+----
+
+<configuration name="use_com.acme.product.plugin.utils" extends="default" />
+
+----
+
+
+| `Export-Package: com.acme.product.plugin.utils,com.acme.product.plugin.common;use:=com.acme.product.plugin.utils` |
+
+[source]
+----
+
+<configuration name="use_com.acme.product.plugin.utils" extends="default" />
+<configuration name="use_com.acme.product.plugin.common" extends="default,use_com.acme.product.plugin.utils" />
+
+----
+
+
+|=======
+
+
+
+=== OSGi Requirements / Ivy dependencies
+
+
+In OSGi there are different kind of dependencies, which is an OSGi bundle repository documentation is called a "requirement". The problem is that Ivy is understanding only one kind of requirement, so we use here some extra attribute to declare those different kind of dependency.
+
+
+==== Require-Bundle
+
+
+The OSGi `Require-Bundle` is some a requirement directly on a specific bundle. Ivy does it too. So we just use the `osgi="bundle"` extra attribute.
+
+If there is the OSGi `resolution` parameter specified to `optional`, then the dependency will be declared in the configuration `optional` and `transitive-optional`. Otherwise it will be declared in the `default` configuration.
+
+
+[]
+|=======
+| *OSGi* | *Ivy* 
+| `Require-Bundle: com.acme.product.plugin;bundle-version="3.2.1"` 
+|
+
+[source]
+----
+
+<dependency osgi="bundle" org="" name="com.acme.product.plugin" rev="[3.2.1,)" conf="default->default" />
+
+----
+
+
+| `Require-Bundle: com.acme.product.plugin;bundle-version="3.2.1";resolution:="optional"` |
+
+[source]
+----
+
+<dependency org="bundle" name="com.acme.product.plugin" rev="[3.2.1,)" conf="optional->default;transitive-optional->transitive-optional" />
+
+----
+
+
+|=======
+
+
+
+==== Import-Package
+
+
+The OSGi `Import-Package` is some a requirement on a package of a bundle. Ivy has no notion of package. So we will use the `osgi="pkg"` extra attribute.
+
+If there is the OSGi `resolution` parameter specified to `optional`, then the dependency will be declared in the configuration `optional` and `transitive-optional`. Otherwise it will be declared in the `default` configuration.
+
+As it is an import package the configuration of the dependency will be the `use_XXX` one. So that transitive dependency via the use parameter will be respected in the dependency.
+
+
+[]
+|=======
+| *OSGi* | *Ivy* 
+| `Import-Package: com.acme.product.plugin.utils;version="3.2.1"` 
+|
+
+[source]
+----
+
+<dependency org="package" name="com.acme.product.plugin.utils" rev="[3.2.1,)" conf="default->default;use_com.acme.product.plugin.utils->use_com.acme.product.plugin.utils" />
+
+----
+
+
+| `Import-Package: com.acme.product.plugin.utils;version="3.2.1";resolution:="optional"` |
+ 
+[source]
+----
+
+<dependency org="package" name="com.acme.product.plugin.utils" rev="[3.2.1,)" conf="optional->default;transitive-optional->transitive-optional;use_com.acme.product.plugin.utils->use_com.acme.product.plugin.utils" />
+
+----
+
+
+|=======
+
+
+
+=== Execution environment
+
+
+The OSGi `Bundle-RequiredExecutionEnvironment` manifest attribute is specifing is which environment the bundle is expected to run. In our problematic of dependency management it means that some of the transitive dependencies won't be resolved within the OSGi space but will be provided by the JRE. So we have to exclude from the dependency tree every requirement that will be provided by the environment. Basically it will be about excluding the packaged declared in the JRE.
+
+
+[]
+|=======
+| *OSGi* | *Ivy* 
+| `Bundle-RequiredExecutionEnvironment: JavaSE-1.6` |
+
+[source]
+----
+
+<dependencies>
+    <exclude org="package" module="javax.accessibility" />
+    <exclude org="package" module="javax.activation" />
+    <exclude org="package" module="javax.activity" />
+    ...
+</dependencies>
+
+----
+
+
+|=======
+
+
+
+=== Bundle Fragment
+
+
+Ivy doesn't support the header `Fragment-Host`.
+
+The work around is to manually specify as dependencies in the ivy.xml the bundles which would fit to be the extensions of the host bundle.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/osgi/sigil.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/osgi/sigil.adoc b/asciidoc/osgi/sigil.adoc
new file mode 100644
index 0000000..00fc3aa
--- /dev/null
+++ b/asciidoc/osgi/sigil.adoc
@@ -0,0 +1,37 @@
+
+
+Another initiative to manage OSGi&#153; dependencies is the project link:http://felix.apache.org/site/apache-felix-sigil.html[Apache Felix Sigil&#153;]. Sigil can used also together with Ivy. We will try to explain here the different approach taken there compared to the build-in OSGi capabilities of Ivy.
+
+
+== A different approach
+
+
+Apache Felix Sigil is at its core about managing OSGi dependencies, not directly related to Ivy. Most of it core feature is about the implementation of the not yet released OBR (OSGi Bundle Repository) specification. It then provides integration layers with sevral tools so human being can actually use the OBR API. As "layer" there is an Eclipse plugin, and there are the Ant/Ivy tasks and resolver.
+
+On the other hand the build in OSGi capabilities in Ivy are targeted against users already familiar with Ivy and their link:http://ant.apache.org/ivy/links.html[tools] like link:http://ant.apache.org/ivy/ivyde[Apache IvyDE&#153;]. So with a minimum of effort, they can get OSGi dependency management.
+
+
+== Resulting differences
+
+
+
+=== Resolve
+
+
+The build-in OSGi resolver is __obviously__ using the Ivy engine to do the resolution of the dependencies. The OSGi capability of Ivy is mainly implemented with a module descriptor parser which understands the OSGi metadata of a MANIFEST.MF.
+
+On the other hand, Sigil is using a separate "engine" to do the resolution, the OBR, an engine which is dedicated to understand the OSGi metadata and their semantics.
+
+The immediate consequence of this difference is that the build-in resolver is probably less accurate than the Sigil one as to understand the OSGi dependencies semantics. As explained in this link:osgi-mapping.html[page], the OSGi model doesn't fit well into the Ivy one.
+
+Whereas Ivy is not ready yet to fill most OSGi use cases, OSGi dependency management at build time is not that complex, contrary to the runtime one. We hope that Ivy will catch up soon.
+
+
+=== Source of metadata
+
+
+Apache Felix Sigil has its own format about specifying the OSGi dependencies. Whereas Ivy requires an ivysettings.xml and an ivy.xml, Sigil requires a sigil-repos.properties and a sigil.properties. Then if you want to use the Sigil resolver in Ivy, you will need 4 files, the 2 Ivy ones and the 2 Sigil ones, as described link:http://felix.apache.org/site/apache-felix-sigil-ivy-quickstart.html[there].
+
+To support OSGi directly in Ivy, you just need to add an extra namespace in the ivy.xml, and in the ivysettings.xml, just declare the proper resolver and latest revision strategy.
+
+	
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/osgi/standard-osgi.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/osgi/standard-osgi.adoc b/asciidoc/osgi/standard-osgi.adoc
new file mode 100644
index 0000000..1225e54
--- /dev/null
+++ b/asciidoc/osgi/standard-osgi.adoc
@@ -0,0 +1,46 @@
+
+
+
+[NOTE]
+====
+
+<table class="notice">
+  <tr>
+    <td style="vertical-align: top"><svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="1em" version="1.1" y="0px" x="0px" viewBox="0 0 980.02045 886.1"><g fill="red"><path d="m972.9158,794.5l-426.1,-761.1c-10.5,-20 -31.1,-32.7 -53.7,-33.4l-1.7,0c-22,0 -42.4,11.5 -53.7,30.5l-428.9,761c-11.5,19.4 -11.8,43.3 -0.6,62.9c11.1,19.6 31.9,31.7 54.4,31.7l854.9,0c21.9,0 42.2,-11.5 53.5,-30.2s12,-42 1.9,-61.4zm-910.4,29.2l428.9,-761.1l426,761.1l-854.9,0z"/><path d="m490.3158,626.7c-36.5,0 -62.1,25.6 -62.1,62.8c0,35.8 24.9,62.8 60.7,62.8l1.4,0c37.3,0 61.5,-27 61.5,-62.8c-0.7,-37.3 -24.9,-62.8 -61.5,-62.8z"/><path d="m451.0158,592.1l78.7,0l15.2,-312.6l-109,0l15.1,312.6z"/></g></svg></td>
+    <td>
+    Note that this feature is considered as *experimental*. It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discussed your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev].
+
+====
+
+
+
+'''
+
+*TODO - WORK IN PROGRESS*
+
+'''
+
+
+This page describes how to build an OSGi&#153; bundle with Apache Ivy&#153;. In this use case, we just basically want to compute a classpath to compile, optionaly one for testing too, and then publish our bundle in a OSGi aware repository.
+
+In oder to produce OSGi metadata of suffient quality and to avoid maintaining them manually, the link:http://www.aqute.biz/Code/Bnd[bnd] tool will be used. The approach taken is then an "Ivy file first" approach. The dependencies will be specified in the ivy.xml file, the MANIFEST.MF being generated from the computed classpath.
+
+
+
+== Quick setup
+
+
+In few steps, we will setup a build to compile and publish an OSGi bundle.
+
+
+
+. download this <a href="../samples/standard-osgi/ivy.xml">ivy.xml<a>, this <a href="../samples/standard-osgi/ivysettings.xml">ivysettings.xml</a>, this <a href="../samples/standard-osgi/build.xml">build.xml</a>, this <a href="../samples/standard-osgi/org.apache.ivy.sample.standard-osgi.bnd">bnd file</a>, and put them into your project folder; +
+
+. in the ivysettings.properties, specify the location of the plugins folder of your Eclipse target; +
+
+. __(optional)__ by default the build.xml is expecting the sources to be in the `src` folder. You may want to edit it if it is not the case +
+
+. __(optional)__ if Ivy is not in Ant's classpath, get the jar of <a href="../download.html">Apache Ivy</a> and edit the build.xml accordingly (see the comments at the begining of the file) +
+
+
+	
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/osgi/target-platform.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/osgi/target-platform.adoc b/asciidoc/osgi/target-platform.adoc
new file mode 100644
index 0000000..479dbbc
--- /dev/null
+++ b/asciidoc/osgi/target-platform.adoc
@@ -0,0 +1,48 @@
+
+
+
+[NOTE]
+====
+
+<table class="notice">
+  <tr>
+    <td style="vertical-align: top"><svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="1em" version="1.1" y="0px" x="0px" viewBox="0 0 980.02045 886.1"><g fill="red"><path d="m972.9158,794.5l-426.1,-761.1c-10.5,-20 -31.1,-32.7 -53.7,-33.4l-1.7,0c-22,0 -42.4,11.5 -53.7,30.5l-428.9,761c-11.5,19.4 -11.8,43.3 -0.6,62.9c11.1,19.6 31.9,31.7 54.4,31.7l854.9,0c21.9,0 42.2,-11.5 53.5,-30.2s12,-42 1.9,-61.4zm-910.4,29.2l428.9,-761.1l426,761.1l-854.9,0z"/><path d="m490.3158,626.7c-36.5,0 -62.1,25.6 -62.1,62.8c0,35.8 24.9,62.8 60.7,62.8l1.4,0c37.3,0 61.5,-27 61.5,-62.8c-0.7,-37.3 -24.9,-62.8 -61.5,-62.8z"/><path d="m451.0158,592.1l78.7,0l15.2,-312.6l-109,0l15.1,312.6z"/></g></svg></td>
+    <td>
+    Note that this feature is considered as *experimental*. It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discussed your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev].
+
+====
+
+
+The concept of "target platform" is a concept introduced by Eclipse&#153; to describe the set of bundle which will run together in an OSGi&#153; environement. Then when developping an OSGi bundle, we expect it to run in a such "target platform".
+
+When developping a single OSGi bundle, a single ivy.xml (together with the use of the link:../use/fixdeps.html[fixdeps] task) is sufficent to describe precisely how the bundle requirements.
+
+But when developping several bundles, it will be error prone to declare for each bundle its dependencies. Because once deployed in an OSGi environement, the bindings are sensitive to the available bundles. So when developping, we must ensure that the set of bundles will be the same set as the one at deploy time.
+
+The concept of "target platform" is a perfect fit to describe the set of bundles to resolve against. Here is a recipe to handle it with just Ant+Ivy.
+
+
+== A Target Platform Project
+
+
+First you need a project (basically a folder) in which you will manage your target platform. In this project you'll need 3 files:
+
+
+* an link:../samples/target-platform/ivy.xml[ivy.xml] in which you will describe the bundles you need, +
+
+* an link:../samples/target-platform/ivysettings.xml[ivysettings.xml] which will describe where to download bundles from, +
+
+* and a link:../samples/target-platform/build.xml[build.xml] with which you'll manage your target platform. +
+
+
+In the build there is a first important target: `'update-dependencies'`. Since the OSGi dependencies are very sensible to the available resources to resolve against, it is important to make the resolve as tight and reproductible as possible. First this target will do a resolve with the `ivy.xml`: a resolve which is very sensible to the content of the remote repo, thus not much reproductible. And it is will generate an `ivy-fixed.xml` from the resolved depedencies: this Ivy file contains only fixed non transitive dependencies (see the link:../use/fixdeps.html[fixdeps] task for further info). With that `ivy-fixed.xml` file, resolves are then reproductible and will always generate the same set of artifacts.
+
+Once generated, it is recommended to share that `ivy-fixed.xml` file into you version control system (subversion, git, etc...). The target `'update-dependencies'` is then to be launched each time you edit the `ivy.xml`, when you want to change the content of your target platform.
+
+The second target `'generate-target-platform'` will generate an `obr.xml`, a OSGi Bundle repository descriptor. This file will list every artifact wich has been resolved by the `ivy-fixed.xml`. Then each of your bundles you develop will do its resolve against that `obr.xml` (see the link:../resolver/obr.html[obr resolver]).
+
+The generated `obr.xml` contains paths to the local filesystem, so it is recommended to not share it between developpers.
+
+If it is required to develop your plugin with the Eclipse PDE plugin, you can then use the alternative target `generate-retrieved-target-platform`. It has the same principle than the `'generate-target-platform'` but the artifacts are also retrieved in a single folder, just like are plugins in an Eclipse install. That way you can define your target platform within Eclipse quite easily.
+
+	
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/principle.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/principle.adoc b/asciidoc/principle.adoc
new file mode 100644
index 0000000..678166c
--- /dev/null
+++ b/asciidoc/principle.adoc
@@ -0,0 +1,64 @@
+
+Now that you have been introduced to the main ivy terminology and concepts, it is time to give some explanation of how ivy works.
+
+
+== Usual cycle of modules between different locations
+
+image::images/main-tasks.png[]
+More details on ant tasks link:ant.html[here].
+
+
+== Configure
+
+Ivy needs to be configured to be able to resolve your dependencies. This configuration is usually done with a settings file, which defines a set of dependency resolvers. Each resolver is able to find ivy files and/or artifacts, given simple information such as organisation, module, revision, artifact name, artifact type and artifact extension. 
+
+The configuration is also responsible for indicating which resolver should be used to resolve which module. This configuration is dependent only on your environment, i.e. where the modules and artifacts can be found. 
+
+A default configuration is used by ivy when none is given. This configuration uses an link:resolver/ibiblio.html[ibiblio resolver] pointing to https://repo1.maven.org/maven2/ to resolve all modules.
+
+== Resolve
+
+The resolve time is the moment when ivy actually resolves the dependencies of one module. It first needs to access the ivy file of the module for which it resolves the dependencies. 
+
+Then, for each dependency declared in this file, it asks the appropriate resolver (according to settings) to find the module (i.e. either an ivy file for it, or its artifacts if no ivy file can be found). It also uses a filesystem based cache to avoid asking for a dependency if it is already in cache (at least if possible, which is not the case with latest revisions).
+
+If the resolver is a composite one (i.e. a chain or a dual resolver), several resolvers may actually be called to find the module.
+
+When the dependency module has been found, its ivy file is downloaded to the ivy cache. Then ivy checks if the dependency module has dependencies, in which case it recursilvely traverses the graph of dependencies. 
+
+All over this traversal, conflict management is done to prevent access to a module as soon as possible.
+
+When ivy has traversed the whole graph, it asks the resolvers to download the artifacts corresponding to each of the dependencies which are not already in the cache and which have not been evicted by conflict managers. All downloads are made to the ivy cache.
+
+Finally, an xml report is generated in the cache, which allows ivy to easily know what are all the dependencies of a module, without traversing the graph again.
+
+After this resolve step, two main steps are possible: either build a path with artifacts in the cache, or copy them to another directory structure.
+
+
+== Retrieve
+
+What is called retrieve in ivy is the act of copying artifacts from the cache to another directory structure. This is done using a pattern, which indicates to ivy where the files should be copied.
+
+For this, ivy uses the xml report in the cache corresponding to the module it should retrieve to know which artifacts should be copied.
+
+It also checks if the files are not already copied to maximize performances.
+
+== Building a path from the cache
+
+In some cases, it is preferable to use artifacts directly from the cache. Ivy is able to use the xml report generated at resolve time to build a path of all artifacts required.
+
+This can be particularly useful when building plug-ins for IDEs.
+
+
+== Reports
+
+Ivy is also able to generate readable reports describing the dependencies resolution.
+
+This is done with a simple xsl transformation of the xml report generated at resolve time.
+
+
+== Publish
+
+Finally, Ivy can be used to publish a particular version of a module in your repository, so that it becomes available for future resolving. This task is usually called either manually or from a continuous integration server.
+
+	
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/reference.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/reference.adoc b/asciidoc/reference.adoc
new file mode 100644
index 0000000..6e872aa
--- /dev/null
+++ b/asciidoc/reference.adoc
@@ -0,0 +1,38 @@
+
+Welcome to the Ivy reference documentation!
+
+If you don't know Ivy at all, take a look at its features, the faq and the link:tutorial.html[tutorials] before digging into this reference documentation.
+
+
+== Reference Overview
+
+This documentation is broken into several parts:
+
+
+* Introduction +
+<ul>
+
+* link:terminology.html[Terminology] +
+This part gives you the meaning of some words used all over the Ivy documentation, such as organization, module, configurations, settings, ...
+
+* link:concept.html[Main Concepts] +
+This part introduces the main concepts used in Ivy: dependency resolvers, variables, patterns, and also a good introduction to a central ivy concept: module configurations.
+
+* link:principle.html[How does it work ?] +
+As the title suggests, here you will find an explanation of how Ivy does work internally, which can help to better understand and customize its use.
+
+* link:install.html[Installation] +
+This part describes how to install Ivy.
+
+* running +
+This part describes possibility to control the behavior of Ivy at run time
+
+<li>link:settings.html[Settings Files]</li>
+This part is dedicated to the specification of the settings file of Ivy (usually called ivysettings.xml). It also gives the list of built-in dependency resolvers available in Ivy.
+<li>link:ivyfile.html[Ivy Files]</li>
+This part is the reference for the module descriptors, the Ivy files in which you describe your dependencies. If you have any questions about what can be done or not in an ivy file, you will find the answer here.
+<li>link:ant.html[Ant Tasks]</li>
+This part describes how to use Ivy from ant. It's in this section that all ant tasks provided by Ivy are specified.
+<li>link:standalone.html[Using standalone]</li>
+Even though Ivy is most often used from ant, it can also be used from the command line. This page describes how you can do this.
+</ul>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/release-notes.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/release-notes.adoc b/asciidoc/release-notes.adoc
new file mode 100644
index 0000000..eab6563
--- /dev/null
+++ b/asciidoc/release-notes.adoc
@@ -0,0 +1,377 @@
+
+
+
+=== Announcement
+
+
+
+[source]
+----
+
+December 21, 2015 - The Apache Ivy project is pleased to announce its 2.5.0 release.
+ 
+Apache Ivy is a tool for managing (recording, tracking, resolving and
+reporting) project dependencies, characterized by flexibility,
+configurability, and tight integration with Apache Ant.
+
+Key features of this 2.5.0 release are
+* Ivy now uses BoucyCastle 1.52. Due to the non backward compatibility of that library, earlier versions are not supported.
+* the minimum Java version required is now Java 7
+* TODO
+* TODO
+
+You can download this 2.5.0 release at:
+http://ant.apache.org/ivy/download.cgi
+ 
+Issues should be reported to:
+https://issues.apache.org/jira/browse/IVY
+ 
+More information can be found on the website:
+http://ant.apache.org/ivy/
+
+----
+
+
+ 
+
+=== List of Changes in this Release
+
+ 
+For details about the following changes, check our JIRA install at 
+http://issues.apache.org/jira/browse/ivy
+ 
+List of changes since Ivy 2.4.0:
+
+- FIX: Made the maven 'test' configuration public so we can use the test-jar as dependency (link:https://issues.apache.org/jira/browse/IVY-1444[IVY-1444])
+- FIX: NullPointerException in dependencytree with no dependencies (link:https://issues.apache.org/jira/browse/IVY-1539[IVY-1539])
+- FIX: checkIfChanged is not settable attribute for checkdepsupdate ant task (link:https://issues.apache.org/jira/browse/IVY-1549[IVY-1549])
+- FIX: ArrayIndexOutOfBoundsException when using a p2 repository for dependencies (link:https://issues.apache.org/jira/browse/IVY-1504[IVY-1504])
+- FIX: fixdeps remove transitive 'kept' dependencies
+- FIX: PomModuleDescriptorParser should parse licenses from parent POM (link:https://issues.apache.org/jira/browse/IVY-1526[IVY-1526]) (Thanks to Jaikiran Pai)
+- FIX: dynamic revisions are not cached per resolver (link:https://issues.apache.org/jira/browse/IVY-1430[IVY-1430]) (Thanks to Stephen Haberman)
+- FIX: Dependencies failed using branch attribute (and extra attributes) (link:https://issues.apache.org/jira/browse/IVY-1141[IVY-1141]) (Thanks to Stephen Haberman)
+- FIX: useCacheOnly should allow lookup of changing dependencies in cache (link:https://issues.apache.org/jira/browse/IVY-1515[IVY-1515]) (Thanks to Ilya)
+- FIX: Translation of POM to Ivy XML with * exclusion is removing main artifact (link:https://issues.apache.org/jira/browse/IVY-1531[IVY-1531]) (Thanks to Jaikiran Pai)
+- FIX: Have makepom task take description from ivy-module > info > description element (link:https://issues.apache.org/jira/browse/IVY-1520[IVY-1520])
+- FIX: Fix RetrieveEngine to take into account the correct extension while dealing with unpacked artifacts (link:https://issues.apache.org/jira/browse/IVY-1478[IVY-1478]) (Thanks to Jaikiran Pai)
+- FIX: ParseException "Unsupported repository, resources names are not uris" for ivy.xml with parent on Windows (link:https://issues.apache.org/jira/browse/IVY-1448[IVY-1448]) (Thanks to Riccardo Foschia and Jaikiran Pai)
+- FIX: Ivy 2.4.0 improperly handles modules with colon (:) in version (link:https://issues.apache.org/jira/browse/IVY-1522[IVY-1522]) (Thanks to Jaikiran Pai)
+- FIX: Delay the processing of configured cache ttls, until the IvySettings object is usable (link:https://issues.apache.org/jira/browse/IVY-1495[IVY-1495]) (Thanks to Jaikiran Pai)
+- FIX: Including optional ivysettings of type 'file' doesn't work when file doesn't exist (link:https://issues.apache.org/jira/browse/IVY-1555[IVY-1555]) (Thanks to Jaikiran Pai)
+- FIX: Makepom ignores dependency classifiers (link:https://issues.apache.org/jira/browse/IVY-1528[IVY-1528]) (Thanks to Jaikiran Pai)
+- FIX: Infinite loop in dependencytree (link:https://issues.apache.org/jira/browse/IVY-1540[IVY-1540]) (Thanks to Jaikiran Pai)
+
+- IMPROVEMENT: Throw an IllegalStateException when retrieving the resolutionCacheRoot on the DefaultResolutionCacheManager if the basedir (or IvySettings) is not set (link:https://issues.apache.org/jira/browse/IVY-1482[IVY-1482])
+- IMPROVEMENT: Optimization: limit the revision numbers scanned if revision prefix is specified (Thanks to Ernestas Vaiciukevi&#269;ius)
+- IMPROVEMENT: Update bouncycastle to 1.52 (link:https://issues.apache.org/jira/browse/IVY-1521[IVY-1521]) (Thanks to Michal Srb)
+
+- NEW: Lets ssh-based resolvers use an ~/.ssh/config file to find username/hostname/keyfile options (Thanks to Colin Stanfill)
+- NEW: Add ivy.maven.lookup.sources and ivy.maven.lookup.javadoc variables to control the lookup of the additional artifacts. Defaults to true, for backward compatibility (link:https://issues.apache.org/jira/browse/IVY-1529[IVY-1529])
+- NEW: Add (conditional) support for SHA-256 SHA-512 and SHA-384 checksum algorithms (link:https://issues.apache.org/jira/browse/IVY-1554[IVY-1554]) (Thanks to Jaikiran Pai)
+
+
+////
+ Samples :
+- NEW: bla bla bla (link:https://issues.apache.org/jira/browse/IVY-1234[IVY-1234]) (Thanks to Jane Doe)
+- IMPROVEMENT: bla bla bla (link:https://issues.apache.org/jira/browse/IVY-1234[IVY-1234]) (Thanks to Jane Doe)
+- FIX: bla bla bla (link:https://issues.apache.org/jira/browse/IVY-1234[IVY-1234]) (Thanks to Jane Doe)
+- DOCUMENTATION: bla bla bla (link:https://issues.apache.org/jira/browse/IVY-1234[IVY-1234]) (Thanks to Jane Doe)
+
+////
+
+
+
+=== Committers and Contributors
+
+
+Here is the list of people who have contributed source code and documentation up to this release. Many thanks to all of them, and also to the whole IvyDE community contributing ideas and feedback, and promoting the use of Apache Ivy !
+
+Committers
+
+* Matt Benson +
+
+* Jean-Louis Boudart +
+
+* Maarten Coene +
+
+* Charles Duffy +
+
+* Xavier Hanin +
+
+* Nicolas Lalevee +
+
+* Jon Schneider +
+
+* Gilles Scokart +
+
+
+Contributors:
+
+* Ingo Adler +
+
+* alex322 +
+
+* Mathieu Anquetin +
+
+* Andreas Axelsson +
+
+* Stephane Bailliez +
+
+* Karl Baum +
+
+* Andrew Bernhagen +
+
+* Mikkel Bjerg +
+
+* Per Arnold Blaasmo +
+
+* Jeffrey Blattman +
+
+* Jasper Blues +
+
+* Jim Bonanno +
+
+* Joseph Boyd +
+
+* Dave Brosius +
+
+* Matthieu Brouillard +
+
+* Carlton Brown +
+
+* Mirko Bulovic +
+
+* Ed Burcher +
+
+* Jamie Burns +
+
+* Wei Chen +
+
+* Chris Chilvers +
+
+* Kristian Cibulskis +
+
+* Andrea Bernardo Ciddio +
+
+* Archie Cobbs +
+
+* Flavio Coutinho da Costa +
+
+* Stefan De Boey +
+
+* Mykhailo Delegan +
+
+* Charles Duffy +
+
+* Martin Eigenbrodt +
+
+* Stephen Evanchik +
+
+* Robin Fernandes +
+
+* Gregory Fernandez +
+
+* Danno Ferrin +
+
+* Riccardo Foschia +
+
+* Benjamin Francisoud +
+
+* Wolfgang Frank +
+
+* Jacob Grydholt Jensen +
+
+* John Gibson +
+
+* Mitch Gitman +
+
+* Evgeny Goldin +
+
+* Scott Goldstein +
+
+* Gintautas Grigelionis +
+
+* Pierre H&#228;gnestrand +
+
+* Scott Hebert +
+
+* Tobias Himstedt +
+
+* Aaron Hachez +
+
+* Ben Hale +
+
+* Stephen Haberman +
+
+* Peter Hayes +
+
+* Scott Hebert +
+
+* Payam Hekmat +
+
+* Achim Huegen +
+
+* Ilya +
+
+* Matt Inger +
+
+* Anders Jacobsson +
+
+* Anders Janmyr +
+
+* Steve Jones +
+
+* Christer Jonsson +
+
+* Michael Kebe +
+
+* Matthias Kilian +
+
+* Alexey Kiselev +
+
+* Gregory Kisling +
+
+* Stepan Koltsov +
+
+* Heschi Kreinick +
+
+* Sebastian Krueger +
+
+* Thomas Kurpick +
+
+* Tat Leung +
+
+* Costin Leau +
+
+* Antoine Levy-Lambert +
+
+* Tony Likhite +
+
+* Andrey Lomakin +
+
+* William Lyvers +
+
+* Sakari Maaranen +
+
+* Jan Materne +
+
+* Markus M. May +
+
+* Abel Muino +
+
+* J. Lewis Muir +
+
+* Stephen Nesbitt +
+
+* Joshua Nichols +
+
+* Bernard Niset +
+
+* Ales Nosek +
+
+* David Maplesden +
+
+* Glen Marchesani +
+
+* Phil Messenger +
+
+* Steve Miller +
+
+* Mathias Muller +
+
+* Randy Nott +
+
+* Peter Oxenham +
+
+* Jaikiran Pai +
+
+* Douglas Palmer +
+
+* Jesper Pedersen +
+
+* Emmanuel Pellereau +
+
+* Carsten Pfeiffer +
+
+* Yanus Poluektovich +
+
+* Roshan Punnoose +
+
+* Jean-Baptiste Quenot +
+
+* Carl Quinn +
+
+* Damon Rand +
+
+* Geoff Reedy +
+
+* Torkild U. Resheim +
+
+* Christian Riege +
+
+* Frederic Riviere +
+
+* Jens Rohloff +
+
+* Andreas Sahlbach +
+
+* Brian Sanders +
+
+* Adrian Sandor +
+
+* Michael Scheetz +
+
+* Ben Schmidt +
+
+* Ruslan Shevchenko +
+
+* John Shields +
+
+* Nihal Sinha +
+
+* Gene Smith +
+
+* Michal Srb +
+
+* Colin Stanfill +
+
+* Simon Steiner +
+
+* Johan Stuyts +
+
+* John Tinetti +
+
+* Erwin Tratar +
+
+* Jason Trump +
+
+* David Turner +
+
+* Ernestas Vaiciukevi&#269;ius +
+
+* Tjeerd Verhagen +
+
+* Richard Vowles +
+
+* Sven Walter +
+
+* James P. White +
+
+* Tom Widmer +
+
+* John Williams +
+
+* Chris Wood +
+
+* Patrick Woodworth +
+
+* Jaroslaw Wypychowski +
+
+* Sven Zethelius +
+
+* Aleksey Zhukov +
+
+* Zhong Wang +
+
+
+	
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/bintray.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/bintray.adoc b/asciidoc/resolver/bintray.adoc
new file mode 100644
index 0000000..9ed84b0
--- /dev/null
+++ b/asciidoc/resolver/bintray.adoc
@@ -0,0 +1,53 @@
+
+
+[]
+|=======
+|Tag|bintray
+|Handle latest|yes, at least if the repository server is apache based
+|Handle publish|no
+|=======
+
+
+This resolver uses Bintray DaaS (Distribution as a Service) platform to retrieve artifacts.
+
+
+== Attributes
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|subject|Bintray username of a repository owner.|No, defaults to Bintray
+|repo|User's repository name.|No, defaults to JCenter
+|=======
+
+
+
+== Examples
+
+
+[source]
+----
+
+<bintray />
+
+----
+
+A default, defines a link:https://bintray.com/bintray/jcenter[JCenter] (http://jcenter.bintray.com/) resolver. 
+In most circumstances you won't need any other resolvers as JCenter is already a super-set of many other repositories, including Maven Central.
+
+
+'''
+
+
+
+[source]
+----
+
+<bintray subject="dsowerby" repo="maven"/>
+<bintray subject="igelgrun" repo="batrak"/>
+
+----
+
+Defines two resolvers to use a link:https://bintray.com/dsowerby/maven[repository] "maven" of user "dsowerby" (https://dl.bintray.com/dsowerby/maven/) 
+and link:https://bintray.com/igelgrun/batrak[repository] "batrak" of user "igelgrun" (https://dl.bintray.com/igelgrun/batrak/).
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/chain.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/chain.adoc b/asciidoc/resolver/chain.adoc
new file mode 100644
index 0000000..77981d5
--- /dev/null
+++ b/asciidoc/resolver/chain.adoc
@@ -0,0 +1,87 @@
+
+
+[]
+|=======
+|Tag|chain
+|Handle latest|depends on sub resolvers
+|Handle publish|delegates to first sub resolver in chain
+|=======
+
+
+This resolver is only a container of a chain of other resolvers. The sub resolvers can be any resolver, including a chain. An attribute enable to indicate if the chain must be iterated after the first found or not (at least when asking for a latest revision). If the chain is iterated, then it's the latest among the ones found that is returned. If the chain is not iterated, then it's the first found which is returned.
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of composite resolvers.
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|returnFirst|true if the first found should be returned.|No, defaults to false
+|dual|true if the chain should behave like a dual chain. *__since 1.3__*|No, defaults to false
+|=======
+
+
+== Child elements
+
+
+[options="header"]
+|=======
+|Element|Description|Cardinality
+|any resolver|a sub resolver to use|1..n
+|=======
+
+
+== Examples
+
+
+[source]
+----
+
+<chain name="test">
+  <filesystem name="1">
+    <ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
+    <artifact pattern="${ivy.settings.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
+  </filesystem>
+  <ivyrep name="2"/>
+</chain>
+
+----
+
+Both a filesystem and ivyrep will be used to look for ivy files. If a dynamic revision is required, then both the filesystem and ivyrep will be queried to find the most recent revision among the two resolvers. Once the most recent revision is found in one resolver, it's the same resolver which will be used to download artifacts.
+
+'''
+
+
+[source]
+----
+
+<chain name="test" returnFirst="true">
+  <filesystem name="1">
+    <ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
+    <artifact pattern="${ivy.settings.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
+  </filesystem>
+  <ivyrep name="2"/>
+</chain>
+
+----
+
+Same as before, except that if a revision is found in the filesystem then ivyrep will not be queried: its the filesystem which will be used for both the ivy file and the artifacts.
+
+'''
+
+
+[source]
+----
+
+<chain name="test" dual="true">
+  <filesystem name="1">
+    <ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
+    <artifact pattern="${ivy.settings.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
+  </filesystem>
+  <ivyrep name="2"/>
+</chain>
+
+----
+
+Same as first example, except that once a module is found by either filesystem or ivyrep, then it's the whole chain which will be queried to download the artifacts. So in this case ivy file and artifacts may be split across the two resolvers for the same module.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/dual.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/dual.adoc b/asciidoc/resolver/dual.adoc
new file mode 100644
index 0000000..9459e6f
--- /dev/null
+++ b/asciidoc/resolver/dual.adoc
@@ -0,0 +1,29 @@
+
+
+[]
+|=======
+|Tag|dual
+|Handle latest|depends on sub resolvers
+|Handle publish|delegates to ivy sub resolver if artifact to publish is of "ivy" type, to artifact sub resolver otherwise
+|=======
+
+
+This resolver delegates its job to one resolver for ivy files and another for artifacts.
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of composite resolvers.
+
+
+== Child elements
+
+
+[options="header"]
+|=======
+|Element|Description|Cardinality
+|any resolver|two resolvers, the first being the ivy resolver, the second the artifact resolver|2
+|=======
+
+
+	
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/filesystem.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/filesystem.adoc b/asciidoc/resolver/filesystem.adoc
new file mode 100644
index 0000000..1ed5eb3
--- /dev/null
+++ b/asciidoc/resolver/filesystem.adoc
@@ -0,0 +1,77 @@
+
+
+[]
+|=======
+|Tag|filesystem
+|Handle latest|yes
+|Handle publish|yes
+|=======
+
+
+
+This resolver uses the file system to resolve ivy files and artifacts. An advantage of this resolver is that it usually provides very good performance. Moreover, it is easy to setup using basic OS file sharing mechanisms.
+
+The configuration of such a resolver is mainly done through ivy and artifact patterns, indicating where ivy files and artifacts can be found in the file system. These patterns must be absolute paths (*__since 2.0__*). You can indicate a list of patterns which will be checked one after the other.
+
+*__since 1.3__* Using the m2compatible attribute, this resolver will convert dots found in organisation into slashes like maven2 does for groupId. For instance, it will transform the organisation from 'com.company' into 'com/company' when replacing the token [organisation] in your pattern.
+*Limitation*: in m2compatible mode, this resolver is not able list available organizations. It means some features like link:../use/repreport.html[repreport] are not available.
+
+
+=== Atomic publish support
+
+*__since 2.0__* This resolver supports atomic publish, which is useful for environments with a lot of concurrent publish and resolve actions. The atomic publish relies on the atomicity of the rename operation in the underlying filesystem (which includes NTFS and POSIX based filesystems).
+In this case the resolver starts by publishing the module according to the pattern, but where a '.part' suffix is appended to the revision. Then the publish is committed with a rename to the final location. 
+
+*Limitations*
+Atomic publish is currently limited in several ways:
+
+
+* you need to use a pattern for both the artifact and the ivy files which uses the revision as a directory. For instance "${repository.dir}/[module]/[revision]/[artifact].[ext]" works, "${repository.dir}/[module]/[artifact]-[revision].[ext]" doesn't +
+
+* both the artifact and ivy pattern should have the same prefix until the [revision] token. +
+
+* overwrite during publish is not supported +
+
+* you should not use revision names ending with '.part' +
+
+
+The *transactional* attribute can be used to configure the atomicity behavior:
+
+
+* auto +
+ use transaction if possible (according to limitation), otherwise don't
+
+* true +
+ always use transaction, fail the build if a limitation is not fulfilled
+
+* false +
+ don't use transaction at all
+
+
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of standard resolvers.
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|m2compatible|True if this resolver should be maven2 compatible, false otherwise *__since 1.3__*|No, defaults to false
+|local|True if this resolver should be considered local, false otherwise *__since 1.4__*. See useOrigin attribute on the link:../settings/caches.html[caches] element for details.|No, defaults to true
+|transactional|true to force the use of transaction, false to prevent the use of transaction, auto to get transaction when possible *__since 2.0__*. See above for details.|No, defaults to auto
+|=======
+
+
+== Child elements
+
+
+[options="header"]
+|=======
+|Element|Description|Cardinality
+|ivy|defines a pattern for ivy files, using the pattern attribute|0..n
+|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|=======
+
+
+	
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/ibiblio.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/ibiblio.adoc b/asciidoc/resolver/ibiblio.adoc
new file mode 100644
index 0000000..4315fcd
--- /dev/null
+++ b/asciidoc/resolver/ibiblio.adoc
@@ -0,0 +1,70 @@
+
+
+[]
+|=======
+|Tag|ibiblio
+|Handle latest|yes, at least if the repository server is apache based
+|Handle publish|no
+|=======
+
+
+This resolver usually uses ibiblio to find artifacts. 
+
+*__since 1.3__* Using the m2compatible attribute, you can benefit from maven 2 repository compatibility (convert dots in organisation into slashes, search for poms, use transitive dependencies of poms). This setting also affects the default place where the resolver looks for its artifacts to point to the maven2 repository. So setting this attribute to true is sufficient to use maven 2 ibiblio repository.
+
+*__since 1.4__* When using the m2compatible flag, you can disable the use of poms by setting the usepoms flag to false. It is then roughly equivalent to a url resolver configured like this:
+
+[source]
+----
+
+<url name="test" m2compatible="true">
+  <artifact pattern="https://repo1.maven.org/maven2/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
+</url>
+
+----
+
+*__since 2.0__* When used in m2compatible mode with the default pattern, this resolver uses maven-metadata.xml files (if present) to list the revisions available on the repository. This is especially useful when using a maven specific proxy, which does not serve directory listing. This can be disabled by using the useMavenMetadata flag.
+
+*Limitation*: in m2compatible mode, this resolver is not able list available organizations. It means some features like link:../use/repreport.html[repreport] are not available.
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of standard resolvers.
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|root|the root of the artifacts repository.|No, defaults to ${ivy.ibiblio.default.artifact.root}
+|pattern|a pattern describing the layout of the artifacts repository.|No, defaults to ${ivy.ibiblio.default.artifact.pattern}
+|m2compatible|True if this resolver should be maven2 compatible, false otherwise *__since 1.3__*|No, defaults to false
+|usepoms|True if this resolver should use maven poms when it is already in m2compatible mode, false otherwise *__since 1.4__*|No, defaults to true
+|useMavenMetadata|True if this resolver should use maven-metadata.xml files to list available revisions, false to use directory listing *__since 2.0__*|No, defaults to true
+|=======
+
+
+
+== Examples
+
+
+[source]
+----
+
+<ibiblio name="maven2" m2compatible="true"/>
+
+----
+
+Defines a resolver called "maven2" using the maven 2 public repository to find module metadata (using maven 2 poms) and artifacts.
+
+
+'''
+
+
+[source]
+----
+
+<ibiblio name="maven" m2compatible="true" usepoms="false"/>
+
+----
+
+Same as above, but doesn't use poms, only artifacts.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/ivyrep.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/ivyrep.adoc b/asciidoc/resolver/ivyrep.adoc
new file mode 100644
index 0000000..18c1d1d
--- /dev/null
+++ b/asciidoc/resolver/ivyrep.adoc
@@ -0,0 +1,47 @@
+
+
+[]
+|=======
+|Tag|ivyrep
+|Handle latest|yes, at least if the repository server is apache based
+|Handle publish|no
+|=======
+
+This resolver usually uses an URL based repository usually similar in structure to link:http://ivyrep.jayasoft.org/[ivyrep] to find ivy files, and ibiblio to find artifacts.
+It can also be configured to use other similar repositories.
+
+
+[NOTE]
+====
+
+Since ivyrep is not maintained anymore, the ivyroot attribute is mandatory, and the use of this resolver is not recommended (we recommend using link:../resolver/url.html[url resolver] as replacement in most cases).
+
+====
+
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of standard resolvers.
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|ivyroot|the root of the ivy repository.|Yes, but may be provided through ${ivy.ivyrep.default.ivy.root} *__since 2.0__*
+|ivypattern|a pattern describing the layout of the ivy repository.|No, defaults to ${ivy.ivyrep.default.ivy.pattern}
+|artroot|the root of the artifacts repository.|No, defaults to ${ivy.ivyrep.default.artifact.root}
+|artpattern|a pattern describing the layout of the artifacts repository.|No, defaults to ${ivy.ivyrep.default.artifact pattern}
+|=======
+
+
+== Examples
+
+
+[source]
+----
+
+<ivyrep name="ivyrep" ivyroot="http://ivyrep.mycompany.com"/>
+
+----
+
+Looks for ivy files on and ivyrep like web site located at http://ivyrep.mycompany.com.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/jar.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/jar.adoc b/asciidoc/resolver/jar.adoc
new file mode 100644
index 0000000..e5b31bc
--- /dev/null
+++ b/asciidoc/resolver/jar.adoc
@@ -0,0 +1,76 @@
+
+
+[]
+|=======
+|Tag|jar
+|Handle latest|yes
+|Handle publish|no
+|=======
+
+
+
+*__since 2.3__*
+
+This resolver uses a specified jar resolve ivy files and artifacts.
+
+This kind of resolver helps the packaging of an entire repository. Since the entire "repository" jar is expected to be local at some point, the size of a such repository should be considered to be not too large if it is expected to be remote; hence the artifacts in a such repo should be little in size.
+
+The configuration of such a resolver is done via specifying the location of the jar, and through ivy and artifact patterns, indicating where ivy files and artifacts can be found in the jar. You can indicate a list of patterns which will be checked one after the other. Note that the patterns MUST NOT start with a slash.
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of standard resolvers.
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|file|the absolute path of the jar|One of 'file' or 'url' is required
+|url|the url of the jar|One of 'file' or 'url' is required
+|=======
+
+
+== Child elements
+
+
+[options="header"]
+|=======
+|Element|Description|Cardinality
+|ivy|defines a pattern for ivy files, using the pattern attribute|0..n
+|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|=======
+
+
+
+== Examples
+
+
+[source]
+----
+
+<jar name="my-local-jar-resolver" file="/home/me/myrepo.jar">
+    <ivy pattern="[organisation]/[module]/ivys/ivy-[revision].xml" />
+    <artifact pattern="[organisation]/[module]/[type]s/[artifact]-[revision].[type]" />
+</jar>
+
+----
+
+A simple local jar repository.
+
+'''
+
+
+[source]
+----
+
+<jar name="my-remote-jar-resolver" url="http://www.mywebsite.com/dist/myrepo.jar">
+    <ivy pattern="dir_in_jar/subdir_in_jar/[organisation]/[module]/ivys/ivy-[revision].xml" />
+    <ivy pattern="dir_in_jar/another_subdir_in_jar/[organisation]/[module]/ivys/ivy-[revision].xml" />
+    <artifact pattern="dir_in_jar/subdir_in_jar/[organisation]/[module]/[type]s/[artifact]-[revision].[type]" />
+    <artifact pattern="dir_in_jar/another_subdir_in_jar/[organisation]/[module]/[type]s/[artifact]-[revision].[type]" />
+    <artifact pattern="dir_in_jar/yet_another_subdir_in_jar/[organisation]/[module]/[type]s/[artifact]-[revision].[type]" />
+</jar>
+
+----
+
+A remote jar repository with multiple ivy and artifact patterns, patterns pointing in some sub directories in the jar.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/mirrored.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/mirrored.adoc b/asciidoc/resolver/mirrored.adoc
new file mode 100644
index 0000000..0656f0d
--- /dev/null
+++ b/asciidoc/resolver/mirrored.adoc
@@ -0,0 +1,83 @@
+
+
+[]
+|=======
+|Tag|mirroredurl
+|Handle latest|yes with http urls (and apache server) and with file urls, no with other urls
+|Handle publish|no
+|=======
+
+
+*__since 2.3__*
+
+
+
+<span class="tagdoc" id="ivysettings.resolvers.mirroredurl">This resolver can resolve dependencies against several mirrors of the same repository. From a list of mirror urls, it will iteratively try to resolve the dependencies against each one.
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of standard resolvers.
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|m2compatible|True if this resolver should be maven2 compatible, false otherwise|No, defaults to false
+|mirrorListUrl|The url where to retrive the list of mirror urls.|Yes
+|=======
+
+
+== Child elements
+
+
+[options="header"]
+|=======
+|Element|Description|Cardinality
+|ivy|defines a pattern for ivy files, using the pattern attribute|0..n
+|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|=======
+
+
+
+== Example
+
+
+Having the file mavenrepolist.txt content:
+
+[source]
+----
+
+https://repo1.maven.org/maven2/
+http://repo2.maven.org/maven2/
+
+----
+
+And the piece of settings:
+
+[source]
+----
+
+<mirroredurl name="mirrored-maven" m2compatible="true" mirrorListUrl="file:///Users/me/dev/repo/mavenrepolist.txt">
+      <artifact pattern="[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
+</mirroredurl>
+
+----
+
+It will resolve first on the repo1 and if failing it will fall back on repo2.
+
+
+'''
+
+
+The mirror list can be retrieved from a geo-location aware url:
+
+[source]
+----
+
+<mirroredurl name="mirrored-asf" mirrorListUrl="http://www.apache.org/dyn/closer.cgi">
+  <ivy pattern="repo/[organisation]/[module]/[revision]/ivy.xml" />
+  <artifact pattern="repo/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
+</mirroredurl>
+
+----
+

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/obr.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/obr.adoc b/asciidoc/resolver/obr.adoc
new file mode 100644
index 0000000..0e319da
--- /dev/null
+++ b/asciidoc/resolver/obr.adoc
@@ -0,0 +1,62 @@
+
+
+[]
+|=======
+|Tag|obr
+|Handle latest|yes
+|Handle publish|no
+|=======
+
+
+*__since 2.3__*
+
+<span class="tagdoc" id="ivysettings.resolvers.obr">This resolver is one of the resolver which supports link:../osgi.html[OSGi&#153;] dependencies. As part of the OSGi specification resides the OBR (OSGi Bundle Repository). The OBR defines the aggregation of the OSGi metadata of every bundle included in an repository. So contrary to the other resolvers, this resolver needs to get the descriptor of the repository (an obr.xml) before starting to resolve modules.
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of composite resolvers.
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|repoXmlURL|the URL of the obr.xml to load.|Yes
+|repoXmlFile|the local path of the obr.xml to load.|Yes
+|requirementStrategy|defines how strict should be the OSGi resolution. Can be one of `first` or `noambiguity`|No, default to `noambiguity`
+|metadataTtl|the time in milliseconds the obr.xml is considered up to date|No, default to 3600000 (1 hour)
+|forceMetadataUpdate|force the update of the obr.xml without checking its freshness|No, default to false
+|=======
+
+
+The requirement strategy is defining how the resolver should behave in front of several choices. In the OSGi dependency model, an `Import-Package` requirement can be satisfied by several different bundles. So when resolving such requirement, Ivy will first look into the already resolved bundles if one provides that package. If it fails to find one, then two behaviours can occur:
+
+
+* if the requirement strategy is `first`, among the bundles statifying the requirement, it will shoose the first one. A warn will be logged ahout the choice Ivy has to arbitrarily do. +
+
+* if the requirement strategy is `noambiguity`, Ivy will make the resolution fail. +
+
+
+
+== Examples
+
+
+[source]
+----
+
+<obr name="felix-repo" repoXmlURL="http://felix.apache.org/obr/releases.xml" />
+
+----
+
+A simple repository configured to use the Felix OBR.
+
+'''
+
+
+[source]
+----
+
+<obr name="my-osgi-repo" repoXmlFile="${ivy.settings.dir}/obr/obr.xml" requirementStrategy="first" />
+
+----
+
+A local repository which is trusted to always provide correct dependency for the `Import-Package` requirements.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/osgiagg.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/osgiagg.adoc b/asciidoc/resolver/osgiagg.adoc
new file mode 100644
index 0000000..2e21935
--- /dev/null
+++ b/asciidoc/resolver/osgiagg.adoc
@@ -0,0 +1,43 @@
+
+
+[]
+|=======
+|Tag|osgi-agg
+|Handle latest|yes
+|Handle publish|no
+|=======
+
+
+*__since 2.4__*
+
+<span class="tagdoc" id="ivysettings.resolvers.osgi-agg">This resolver is one of the resolver which supports link:../osgi.html[OSGi&#153;] dependencies.
+
+This resolvers is like a classic link:[chain] resolver, but which better support OSGi metadata.
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of composite resolvers.
+
+
+== Elements
+
+As sub element, this resolver accept any kind of OSGi resolver: link:../obr.html[obr], link:../updatesite.html[updatesite], or any other `osgi-agg`.
+
+
+== Examples
+
+
+[source]
+----
+
+<updatesite name="ivyde-updatesite" url="http://www.apache.org/dist/ant/ivyde/updatesite" />
+<obr name="felix-repo" repoXmlURL="http://felix.apache.org/obr/releases.xml" />
+<osgi-agg name="all-osgi">
+    <resolver ref="ivyde-updatesite" />
+    <resolver ref="felix-repo" />
+</osgi-agg>
+
+----
+
+An aggregated OSGi reporsory composed of the Apache IvyDE Eclipse update site and the Felix OBR.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/packager.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/packager.adoc b/asciidoc/resolver/packager.adoc
new file mode 100644
index 0000000..d5ba189
--- /dev/null
+++ b/asciidoc/resolver/packager.adoc
@@ -0,0 +1,351 @@
+
+
+[]
+|=======
+|Tag|packager
+|Handle latest|yes with http urls (and apache server) and with file urls, no with other urls
+|Handle publish|no
+|=======
+
+
+
+
+
+
+
+*__Since 2.0__*.
+
+
+
+
+
+
+
+This resolver accesses ivy files and "packaging instructions" from an online "packager" repository. "Packager" repositories contain no actual artifacts. To get the artifacts, the packaging instructions are downloaded from the repository and executed locally. These instructions specify additional resource(s) to download and how to create the artifacts from them, for example, by downloading a project's original distribution archive directly from their web site and extracting the desired artifacts.
+
+
+
+
+
+
+
+Packager repositories allow the creation of Ivy repositories that require neither the participation of any of the modules' creators nor setting up a huge mirror site. One such repository on the web is link:http://ivyroundup.googlecode.com/[Ivy RoundUp]. Of course, private packager repositories are feasible as well.
+
+
+
+
+
+
+
+The Packager resolver supports a "resource cache", where downloaded archives can be stored to avoid duplicate downloads. This cache is entirely separate from the link:../concept.html#cache[normal Ivy cache]: it is "private" to the Packager resolver, and it stores unmodified original software archives, not Ivy artifacts. See the <span class="ivy-att">resourceCache</span> attribute below for details.
+
+
+
+
+
+
+
+The packaging instructions are contained in "packager.xml" in a simple XML format. At resolve time this file gets converted into a "build.xml" file via XSLT and then executed using link:http://ant.apache.org/[ant]. Therefore, ant must be available as an executable on the platform. The ant task executes in a separate ant project and so is not affected by properties, etc. that may be set in any existing ant environment in which Ivy is running. However, Ivy will define a few properties for convenience; see the "Properties" listed below.
+
+
+
+
+
+
+
+For security reasons, the XSLT transform ensures that (a) all downloaded archives have verified SHA1 checksums (including cached resources); and (b) only a very limited set of ant tasks can be performed during the artifact "build" phase; currently these include move, copy, mkdir, zip, unzip, tar, and untar (this restriction may be overridden however; see below).
+
+
+
+
+
+
+
+The Packager resolver is based on the link:url.html[URL resolver] and is configured similarly, except the artifact child tags specify where to find the packager.xml files, rather than the artifacts themselves.
+
+
+
+
+
+
+
+Because the packaging process is relatively slow, it is important to use link:../concept.html#cache[Ivy's caching support] to avoid repeated execution of the packaging instructions.
+
+
+
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of standard resolvers, plus the following:
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|buildRoot|Defines the root of the temporary build directory hierarchy|Yes
+|resourceCache|Directory where downloaded resources should be cached|No; defaults to none
+|resourceURL|Ivy pattern that specifies a base URL to use for downloading __all__ resources; overrides the URLs in the packaging instructions|No; defaults to none
+|restricted|True if this resolver should only allow "safe" ant tasks in the packaging instructions. *Warning:* setting <span class="ivy-att">restricted</span> to false creates a security problem due to ant tasks like delete, exec, etc. Do not use this setting when your configuration points to an untrusted repository.|No; defaults to true
+|verbose|True to run ant with the -verbose flag|No; defaults to false
+|quiet|True to run ant with the -quiet flag|No; defaults to false
+|validate|True if this resolver should validate (via XSD) the downloaded XML packaging instructions|No; defaults to true
+|preserveBuildDirectories|True if this resolver should not delete the temporary build directories in which the ant tasks are executed (for debugging purposes)|No; defaults to false
+|=======
+
+
+
+
+
+
+Setting a resourceURL will cause the resolver to override the URLs for resources specified by the packaging instructions. Instead, all resources will be downloaded from an URL constructed by first resolving the resourceURL pattern into a base URL, and then resolving the resource filename relative to that base URL. In other words, the resourceURL pattern specifies the URL "directory", so it should always end in a forward slash.
+
+
+
+
+
+
+
+If a resourceURL download fails, the resolver will fall back to the original URL from the packaging instructions.
+
+
+
+
+
+
+
+Configure a resourceURL in situations where you don't want to rely on (or wait for) the web sites configured in the packaging instructions, and have access to a better (perhaps private) mirror site.
+
+
+
+
+
+== Child elements
+
+
+[options="header"]
+|=======
+|Element|Description|Cardinality
+|ivy|Defines a pattern for ivy.xml files, using the pattern attribute|1..n
+|artifact|Defines a pattern for packager.xml files, using the pattern attribute|1..n
+|=======
+
+
+
+== Examples
+
+
+[source]
+----
+
+<packager name="ivyroundup"
+         buildRoot="${user.home}/.ivy2/packager/build"
+         resourceCache="${user.home}/.ivy2/packager/cache"
+         resourceURL="ftp://mirror.example.com/pub/resources/[organisation]/[module]/">
+    <ivy pattern="http://ivyroundup.googlecode.com/svn/trunk/repo/modules/[organisation]/[module]/[revision]/ivy.xml"/>
+    <artifact pattern="http://ivyroundup.googlecode.com/svn/trunk/repo/modules/[organisation]/[module]/[revision]/packager.xml"/>
+</packager>
+
+----
+
+Defines a packager resolver which points to the link:http://ivyroundup.googlecode.com/[Ivy RoundUp] online repository. Builds will occur in a subdirectory of 
+[source]
+----
+${user.home}/.ivy2/packager/build
+----
+
+downloaded resources will be cached in 
+[source]
+----
+${user.home}/.ivy2/packager/cache
+----
+
+and the mirror site 
+[source]
+----
+ftp://mirror.example.com/pub/resources/[organisation]/[module]/ 
+----
+
+will be tried first for all resources.
+
+
+== Packaging Instructions
+
+
+
+
+The goal of the packaging instructions is to download the required archives, extract the artifacts, and put the artifacts into a subdirectory. Each artifact should be written to artifacts/[type]s/[artifact].[ext] when the ant build completes.
+
+
+
+
+
+
+
+Below is an example of packaging instructions for link:http://testng.org/[TestNG 2.5]:
+
+[source]
+----
+
+<packager-module version="1.0">
+
+    <property name="name" value="${ivy.packager.module}"/>
+    <property name="version" value="${ivy.packager.revision}"/>
+    <property name="zipname" value="${name}-${version}"/>
+
+    <resource dest="archive" url="http://testng.org/${zipname}.zip" sha1="2ea19275dc17453306f8bb780fe6ef6e9af7756b">
+        <url href="http://mirror.example.com/archives/${zipname}.zip"/>
+        <include name="${zipname}/src/main/**/*"/>
+        <include name="${zipname}/src/jdk15/**/*"/>
+        <include name="${zipname}/javadocs/**/*"/>
+        <include name="${zipname}/*.jar"/>
+    </resource>
+
+    <build>
+
+        <!-- jar  -->
+        <move file="archive/${zipname}/${zipname}-jdk14.jar" tofile="artifacts/jars/${name}-jdk14.jar"/>
+        <move file="archive/${zipname}/${zipname}-jdk15.jar" tofile="artifacts/jars/${name}-jdk15.jar"/>
+
+        <!-- source -->
+        <zip destfile="artifacts/sources/${name}.zip">
+            <fileset dir="archive/${zipname}/src/main">
+                <include name="**/*.java"/>
+            </fileset>
+            <fileset dir="archive/${zipname}/src/jdk15">
+                <include name="**/*.java"/>
+            </fileset>
+        </zip>
+
+        <!-- javadoc -->
+        <zip destfile="artifacts/javadocs/javadoc.zip">
+            <fileset dir="archive/${zipname}/javadocs"/>
+        </zip>
+    </build>
+</packager-module>
+
+----
+
+Of course, packaging instructions must produce artifacts consistent with those listed in the associated ivy.xml file.
+
+
+
+
+
+== Build-time properties
+
+This resolver ensures following ant properties are defined when it executes the ant build task.
+
+[options="header",cols="15%,50%"]
+|=======
+|Property|Description
+|ivy.packager.organisation|Organization of the ivy module whose artifacts are being built
+|ivy.packager.module|Module of the ivy module whose artifacts are being built
+|ivy.packager.revision|Revision of the ivy module whose artifacts are being built
+|ivy.packager.branch|Branch of the ivy module whose artifacts are being built
+|ivy.packager.resourceCache|The configured <span class="ivy-att">resourceCache</span> if any; otherwise not defined
+|ivy.packager.resourceURL|The resolved <span class="ivy-att">resourceURL</span> pattern if any; otherwise not defined
+|=======
+
+
+
+== Packager XML Elements
+
+The packager.xml document element can contain the following child tags.
+
+[options="header"]
+|=======
+|Element|Description|Cardinality
+|property|Set an ant property|0..n
+|resource|Define a resource to download and (optionally) unpack|0..n
+|m2resource|Define a Maven2 resource to download and (optionally) unpack|0..n
+|build|Specify ant tasks that ultimately result in each artifact being placed into artifacts/[type]s/[artifact].[ext]|0..1
+|=======
+
+
+
+Which ant tasks are allowed within the build tag is controlled by the <span class="ivy-att">restricted</span> configuration attribute. When true (the default), only the following ant tasks are allowed: copy, jar, mkdir, move, tar, unjar, untar, unwar, unzip, war, and zip. When false, all ant tasks are allowed.
+
+
+
+
+*Warning:* setting <span class="ivy-att">restricted</span> to false creates a security problem due to ant tasks like delete, exec, etc. Do not use this setting when your configuration points to an untrusted repository.
+
+
+
+
+
+== Resource XML Elements
+
+The resource XML tag supports the following attributes:
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|url|Primary URL for the resource|Yes
+|sha1|SHA1 checksum of the resource|Yes
+|dest|Defines the name of the subdirectory into which the artifact should be unpacked|No; defaults to "archive"
+|tofile|Where to put the file directly; if present no extraction will be performed|No; if present, "dest" is ignored
+|filename|Name of the file to download|No; if not present, same as the last component of the URL
+|type|Type of archive: "zip", "jar", "war", "tar", "tgz", "tar.gz", "tar.bz2"|No; if not present, will be automatically determined from the filename suffix
+|=======
+
+
+
+The resource XML tag may contain child elements. An url tag with an href attribute specifies an alternate URL for the resource (see TestNG example above). Any other tags will be included as children of an automatically generated fileset tag.
+
+
+== Maven2 Resources
+
+Special support is included for maven2 resources. For these resources, use the m2resource tag instead of the resource tag. Each m2resource tag specifies one or more artifacts that are downloaded from the Maven2 repository.
+
+
+== M2Resource XML Elements
+
+The m2resource XML tag supports the following attributes:
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|groupId|Maven group ID|No; defaults to ${ivy.packager.organisation}
+|artifactId|Maven artifact ID|No; defaults to ${ivy.packager.module}
+|version|Maven version|No; defaults to ${ivy.packager.revision}
+|repo|Maven repository URL|No; defaults to https://repo1.maven.org/maven2/ 
+|=======
+
+
+
+Each m2resource XML tag must have one or more artifact tags that define the artifacts to directly download. The URL for each artifact is constructed automatically based on the attributes in the m2resource and artifact tags.
+
+
+== M2Resource Artifact Attributes
+
+The artifact children of m2resource tags support the following attributes:
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|ext|Maven filename extension|No; defaults to "jar"
+|classifier|Maven classifier (e.g., "sources", "javadoc")|No; defaults to none
+|sha1|SHA1 checksum of the resource|Yes
+|dest|Defines the name of the subdirectory into which the artifact should be unpacked|Exactly one of "dest" or "tofile" must be supplied
+|tofile|Where to put the file; no extraction will be performed
+|type|Type of archive: "zip", "jar", "war", "tar", "tgz", "tar.gz", "tar.bz2"|No; if not present, will be automatically determined from the filename suffix
+|=======
+
+
+
+Below is an example of packaging instructions for the link:http://commons.apache.org/email/[Apache Commons Email] module. Note that no build tag is required because all of the maven2 artifacts are usable directly (i.e., without unpacking anything).
+
+[source]
+----
+
+<packager-module version="1.0">
+    <m2resource>
+        <artifact tofile="artifacts/jars/${ivy.packager.module}.jar" sha1="a05c4de7bf2e0579ac0f21e16f3737ec6fa0ff98"/>
+        <artifact classifier="javadoc" tofile="artifacts/javadocs/javadoc.zip" sha1="8f09630f1600bcd0472a36fb2fa2d2a6f2836535"/>
+        <artifact classifier="sources" tofile="artifacts/sources/source.zip" sha1="15d67ca689a792ed8f29d0d21e2d0116fa117b7e"/>
+    </m2resource>
+</packager-module>
+
+----
+

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/sftp.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/sftp.adoc b/asciidoc/resolver/sftp.adoc
new file mode 100644
index 0000000..73528a7
--- /dev/null
+++ b/asciidoc/resolver/sftp.adoc
@@ -0,0 +1,133 @@
+
+
+[]
+|=======
+|Tag|sftp
+|Handle latest|yes
+|Handle publish|yes
+|=======
+
+
+
+
+This resolver can be used when your ivy repository is located on a server accessible via sftp. The secured nature of sftp and its widespread implementation on most *nix servers makes this resolver a very good candidate in an enterprise environment. *__since 1.4__*
+
+If your server supports ssh but not sftp, there is also an link:../resolver/ssh.html[ssh resolver].
+
+Note that sftp is also supported by vfs, so you can use a vfs resolver instead. The advantage of this resolver is that you have a better control over authentication, it can prompt for username/password credentials, or you can use private/public key authentication, which is not possible with the vfs resolver. When it prompts for username/password, it uses a Swing dialog, which is not possible in a headless environment. If you want to prompt for the credentials on the command line, use ant input task for example before calling ivy.
+
+All necessary connection parameters can be set here via attributes, or via an OpenSSH-style config file specified by sshConfig.
+However all attributes defined in the pattern url of the resolver will have higher priority and will overwrite the values given here. To specify connection parameters in the pattern, you have to specify a full url and not just a path as pattern.
+e.g. pattern="/path/to/my/repos/[artifact].[ext]" will use all connection parameters from this class
+e.g. pattern="sftp://myserver.com/path/to/my/repos/[artifact].[ext]" will use all parameters from the attributes with the exception of the host, which will be "myserver.com"
+e.g. pattern="sftp://user:geheim@myserver.com:8022/path/to/my/repos/[artifact].[ext]" will use only the keyFile and keyFilePassword from the attributes (if needed). Rest will come from the url.
+
+
+
+Note that the authentication features of this resolver are exactly the same as the ssh resolver. Choosing between the two is often a matter of server implementation. If your server supports sftp, usually it's preferrable.
+
+Internally this resolver relies on link:http://www.jcraft.com/jsch/[jsch] as ssh client, which is a popular java ssh client, used for example in eclipse.
+
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of standard resolvers.
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|user|The username to provide as credential|No, defaults to username given on the patterns, or prompt if none is set
+|userPassword|The password to provide as credential|No, defaults to password given on the patterns, or prompt if none is set
+|keyFile|Path to the keyfile to use for authentication|No, defaults to username/password authentication
+|keyFilePassword|the password used to protect the key file|No, will prompt for password if keyFile authentication is used and if it is password encrypted
+|host|The host to connect to|No, defaults to host given on the patterns, fail if none is set
+|port|The port to connect to|No, defaults to 22
+|sshConfig|Path to an OpenSSH-style config file containing additional
+            configuration|No
+|=======
+
+
+== Child elements
+
+
+[options="header"]
+|=======
+|Element|Description|Cardinality
+|ivy|defines a pattern for ivy files, using the pattern attribute|0..n
+|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|=======
+
+
+
+== Example
+
+
+[source]
+----
+
+<sftp user="myuser" host="myhost.com">
+  <ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
+  <artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
+</sftp> 
+
+----
+
+Will connect to myhost.com using myuser and prompt for the password.
+
+'''
+
+
+[source]
+----
+
+<sftp user="${myuser}" userPassword="${my.password}" host="myhost.com">
+  <ivy pattern="path/to/ivy/[module]/ivy.xml"/>
+  <artifact pattern="path/to/[organisation]/[module]/[artifact].[ext]"/>
+</sftp>
+
+----
+
+Will connect to myhost.com using user and password provided with ivy variables.
+
+'''
+
+
+[source]
+----
+
+<sftp>
+  <ivy pattern="sftp://user:geheim@yourserver.com:8022/path/to/repos/[module]/[revision]/ivy.xml"/>
+  <artifact pattern="sftp://user:secret@myserver.com:8022/path/to/my/repos/[artifact].[ext]"/>
+</sftp>
+
+----
+
+Will connect to yourserver.com on port 8022 with user 'user' and password 'geheim' for authentication for ivy files, and to myserver.com on port 8022 using user 'user' and password 'secret' for the artifacts.
+
+'''
+
+
+[source]
+----
+
+<sftp keyFile="path/to/key/file" keyFilePassword="${password}">
+  <ivy pattern="sftp://user@yourserver.com:8022/path/to/repos/[module]/[revision]/ivy.xml"/>
+  <artifact pattern="sftp://user@myserver.com:8022/path/to/my/repos/[artifact].[ext]"/>
+</sftp>
+
+----
+
+Will connect to yourserver.com on port 8022 with user 'user' and use keyFile path/to/key/file for keyFile and the value of password variable for keyFilePassword authentication for ivy files, and to myserver.com on port 8022 using user 'user' with the same keyFile/keyFilePassword pair for the artifacts.
+
+
+[source]
+----
+
+<sftp host="myhost" sshConfig="/path/to/.ssh/config">
+  <ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
+  <artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
+</ssh>
+
+----
+
+Will connect to the host named by myhost according to the config file in /path/to/.ssh/config, using the hostname, username, and optionally IdentityFile specified in the config section "Host myhost". For example, if the corresponding Host section contains "Hostname yourserver.com" and "User myremoteusername", it will connect to yourserver.com using username myremoteusername.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/resolver/ssh.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/resolver/ssh.adoc b/asciidoc/resolver/ssh.adoc
new file mode 100644
index 0000000..2b01dcf
--- /dev/null
+++ b/asciidoc/resolver/ssh.adoc
@@ -0,0 +1,92 @@
+
+
+[]
+|=======
+|Tag|ssh
+|Handle latest|yes
+|Handle publish|yes
+|=======
+
+
+
+
+This resolver can be used when your ivy repository is located on a server accessible via ssh. The secured nature of ssh and its widespread implementation on most *nix servers makes this resolver a very good candidate in an enterprise environment. *__since 1.4__*
+
+If your server supports sftp, you can consider using the link:../resolver/sftp.html[sftp resolver].
+
+Internally this resolver shares most of its behaviour with the link:../resolver/sftp.html[sftp resolver], so refer to its documentation for details.
+
+== Attributes
+
+This resolver shares the link:../settings/resolvers.html#common[common attributes] of standard resolvers.
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|user|The username to provide as credential|No, defaults to username given on the patterns, or prompt if none is set
+|userPassword|The password to provide as credential|No, defaults to password given on the patterns, or prompt if none is set
+|keyFile|Path to the keyfile to use for authentication|No, defaults to username/password authentication
+|keyFilePassword|the password used to protect the key file|No, will prompt for password if keyFile authentication is used and if it is password encrypted
+|host|The host to connect to|No, defaults to host given on the patterns, fail if none is set
+|port|The port to connect to|No, defaults to 22
+|sshConfig|Path to an OpenSSH-style config file containing additional
+            configuration|No
+|publishPermissions|A four digit string (e.g., 0644, see "man chmod", "man open") specifying the permissions of the published files. *__(since 2.0)__*
+|No, defaults to scp standard behaviour
+|=======
+
+
+== Child elements
+
+
+[options="header"]
+|=======
+|Element|Description|Cardinality
+|ivy|defines a pattern for ivy files, using the pattern attribute|0..n
+|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|=======
+
+
+
+== Example
+
+
+[source]
+----
+
+<ssh user="myuser" host="myhost.com">
+  <ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
+  <artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
+</ssh> 
+
+----
+
+Will connect to myhost.com using myuser and prompt for the password.
+
+'''
+
+
+[source]
+----
+
+<ssh keyFile="path/to/key/file" keyFilePassword="${password}">
+  <ivy pattern="ssh://user:geheim@yourserver.com:8022/path/to/repos/[module]/[revision]/ivy.xml"/>
+  <artifact pattern="ssh://user:geheim@myserver.com:8022/path/to/my/repos/[artifact].[ext]"/>
+</ssh>
+
+----
+
+Will connect to yourserver.com on port 8022 with user geheim and use keyFile path/to/key/file for keyFile and the value of password variable for keyFilePassword authentication for ivy files, and to myserver.com on port 8022 using user geheim with the same keyFile/keyFilePassword pair for the artifacts.
+
+
+[source]
+----
+
+<ssh host="myhost" sshConfig="/path/to/.ssh/config">
+  <ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
+  <artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
+</ssh>
+
+----
+
+Will connect to the host named by myhost according to the config file in /path/to/.ssh/config, using the hostname, username, and optionally IdentityFile specified in the config section "Host myhost". For example, if the corresponding Host section contains "Hostname yourserver.com" and "User myremoteusername", it will connect to yourserver.com using username myremoteusername.
\ No newline at end of file


Mime
View raw message