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/07/25 11:01:50 UTC
ant-ivy git commit: [doc fixes] Updates to the tutorials asciidoc
documentation
Repository: ant-ivy
Updated Branches:
refs/heads/master d4c3cbcca -> 87c4e0656
[doc fixes] Updates to the tutorials asciidoc documentation
Project: http://git-wip-us.apache.org/repos/asf/ant-ivy/repo
Commit: http://git-wip-us.apache.org/repos/asf/ant-ivy/commit/87c4e065
Tree: http://git-wip-us.apache.org/repos/asf/ant-ivy/tree/87c4e065
Diff: http://git-wip-us.apache.org/repos/asf/ant-ivy/diff/87c4e065
Branch: refs/heads/master
Commit: 87c4e0656a10f7d9c18a203cf80c01406aeb6820
Parents: d4c3cbc
Author: Jaikiran Pai <ja...@apache.org>
Authored: Tue Jul 25 15:52:33 2017 +0530
Committer: Jaikiran Pai <ja...@apache.org>
Committed: Tue Jul 25 16:30:56 2017 +0530
----------------------------------------------------------------------
asciidoc/tutorial.adoc | 48 ++++++++------
asciidoc/tutorial/defaultconf.adoc | 114 ++++++++++++--------------------
asciidoc/tutorial/multiple.adoc | 91 +++++++++++--------------
asciidoc/tutorial/start.adoc | 44 ++++++------
4 files changed, 127 insertions(+), 170 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/87c4e065/asciidoc/tutorial.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial.adoc b/asciidoc/tutorial.adoc
index 208e829..9faab9e 100644
--- a/asciidoc/tutorial.adoc
+++ b/asciidoc/tutorial.adoc
@@ -17,46 +17,50 @@
under the License.
////
+= Ivy Tutorials
+
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 link:https://ant.apache.org/ivy/features.html[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*
+== First Tutorial
+
+ * Make sure you have link:http://ant.apache.org/[Ant] 1.9.9 or greater and a link:https://www.java.com/en/download/[Java JDK] properly installed +
-. Make sure you have link:http://ant.apache.org/[ant] 1.9.9 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`) +
-. 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 the command: `ant`. That's it! +
-. Open a console in this directory and run "ant". That's it! +
+If you have any trouble, check our link:http://ant.apache.org/ivy/faq.html[FAQ].
-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).
-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).
+== List of available tutorials
The following tutorials are available:
-* link:tutorial/start.html[Quick Start] +
-Guides you through your very first steps with ivy.
+ * 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/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/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/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 starting point for using Ivy in a multi-project environment.
+ * link:tutorial/dependence.html[Project dependencies] +
+ 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/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/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.
+ * link:tutorial/build-repository.html[Building a repository] +
+ Shows you how to build your own enterprise repository.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/87c4e065/asciidoc/tutorial/defaultconf.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/defaultconf.adoc b/asciidoc/tutorial/defaultconf.adoc
index ac0841e..681837d 100644
--- a/asciidoc/tutorial/defaultconf.adoc
+++ b/asciidoc/tutorial/defaultconf.adoc
@@ -17,6 +17,8 @@
under the License.
////
+= Adjusting default Ivy configurations
+
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.
@@ -27,14 +29,14 @@ To fully understand the concept of settings and what you can do with them, we su
The default settings include 3 types of repositories:
-* local +
- a repository which is private to the user.
+ * local +
+ A repository which is private to the user.
-* shared +
- a repository which is shared between all the members of a team
+ * 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
+ * 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.
@@ -45,9 +47,9 @@ Now let's describe each of these repository concepts in more detail. We will des
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_.
+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).
+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.
@@ -55,7 +57,7 @@ Note also that modules found in the local repository must be complete, i.e. they
=== 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).
+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. 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.
@@ -71,13 +73,13 @@ First, several repositories use the same root in your filesystem. Referenced as
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 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 +
+ * set an environment variable if you use Ivy from the command line +
For example:
-[source]
+[source, xml]
----
<target name="resolve">
@@ -91,36 +93,21 @@ Next we will show you how to override default values for the different kinds of
=== 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
-----
+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 `ivy.local.default.root` Ivy variable to the directory you want to use:
-. For instance:
+For example:
[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
-----
+ * `ivy.local.default.ivy.pattern` which gives the pattern to find Ivy module descriptor files
+
+ * `ivy.local.default.artifact.pattern` which gives the pattern to find the artifacts
-gives the pattern to find artifacts
For example:
[source]
@@ -135,27 +122,12 @@ 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
-----
+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 `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:
-gives the pattern to find ivy files
-
-[source]
-----
-ivy.shared.default.artifact.pattern
-----
+ * `ivy.shared.default.ivy.pattern` which gives the pattern to find Ivy module descriptor files
+
+ * `ivy.shared.default.artifact.pattern` which gives the pattern to find the artifacts
-gives the pattern to find artifacts
For example:
[source]
@@ -170,19 +142,18 @@ ivy.shared.default.artifact.pattern=[organisation]/[module]/[revision]/[artifact
=== Public
-By default, the public repository is ibiblio in m2 compatible mode (in other words, the maven 2 public repository).
+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_
+NOTE: 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 ...
+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.
@@ -190,7 +161,7 @@ But before explaining how, you will need to have a quick overview of how Ivy is
By default, Ivy is configured using an `ivysettings.xml` which is packaged in the Ivy jar. Here is this settings file:
-[source]
+[source, xml]
----
<ivysettings>
@@ -206,7 +177,7 @@ By default, Ivy is configured using an `ivysettings.xml` which is packaged in th
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]
+[source, xml]
----
<ivysettings>
@@ -221,9 +192,10 @@ OK, so not much info here, except a lot of inclusions. These inclusions have bee
----
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]
+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, the contents of such a file could be:
+
+[source, xml]
----
<ivysettings>
@@ -238,9 +210,9 @@ To finish this example, you have to write your own ivysettings file (that you wi
----
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-public.xml*
+[source, xml]
----
<ivysettings>
@@ -251,9 +223,8 @@ Now the last thing you will need in order to properly take advantage of the defa
----
-*ivysettings-shared.xml*
-
-[source]
+.*ivysettings-shared.xml*
+[source, xml]
----
<ivysettings>
@@ -270,9 +241,8 @@ Now the last thing you will need in order to properly take advantage of the defa
----
-*ivysettings-local.xml*
-
-[source]
+.*ivysettings-local.xml*
+[source, xml]
----
<ivysettings>
@@ -289,9 +259,8 @@ Now the last thing you will need in order to properly take advantage of the defa
----
-*ivysettings-main-chain.xml*
-
-[source]
+.*ivysettings-main-chain.xml*
+[source, xml]
----
<ivysettings>
@@ -305,9 +274,8 @@ Now the last thing you will need in order to properly take advantage of the defa
----
-*ivysettings-default-chain.xml*
-
-[source]
+.*ivysettings-default-chain.xml*
+[source, xml]
----
<ivysettings>
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/87c4e065/asciidoc/tutorial/multiple.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/multiple.adoc b/asciidoc/tutorial/multiple.adoc
index e1707f3..c9a273e 100644
--- a/asciidoc/tutorial/multiple.adoc
+++ b/asciidoc/tutorial/multiple.adoc
@@ -17,114 +17,99 @@
under the License.
////
+= Multiple Resolvers
+
This tutorial is an example of how modules can be retrieved by multiple resolvers. Using multiple resolvers can be useful in many contexts. For example:
-* separating integration builds from releases +
+ * separating integration builds from releases +
-* using a public repository for third party modules and a private one for internal modules +
+ * using a public repository for third party modules and a private one for internal modules +
-* use a repository for storing modules which are not accurate in an unmanaged public repository +
+ * use a repository for storing modules which are not accurate in an unmanaged public repository +
-* use a local repository to expose builds made on one developer's station +
+ * use a local repository to expose builds made on one developer's station +
In Ivy, the use of multiple resolvers is supported by a compound resolver called the chain resolver.
-In our example, we will simply show you how to use two resolvers, one on a local repository and one using the maven2 repository.
+In our example, we will simply show you how to use two resolvers, one on a local repository and one using the Maven2 repository.
-== project description
+== Project Description
-=== the project: chained-resolvers
+=== The project: chained-resolvers
-The project is very simple and contains only one simple class: example.Hello.
+The project is very simple and contains only one simple class: `example.Hello`.
-It depends on two libraries: Apache's commons-lang and a custom library named test (sources are included in test-1.0jar file). The test library is used by the project to uppercase a string, and commons-lang is used to capitalize the same string.
+It depends on two libraries: Apache's `commons-lang` and a custom library named `test` (sources are included in `test-1.0.jar` file). The test library is used by the project to uppercase a string, and `commons-lang` is used to capitalize the same string.
Here is the content of the project:
-* build.xml: the ant build file for the project +
+ * build.xml: the ant build file for the project +
-* ivy.xml: the Ivy project file +
+ * ivy.xml: the Ivy project file +
-* src\example\Hello.java: the only class of the project +
+ * src\example\Hello.java: the only class of the project +
Let's have a look at the *ivy.xml* file:
-[source]
+[source, xml]
----
-<ivy-module version="1.0">
- <info organisation="org.apache" module="chained-resolvers"/>
- <dependencies>
- <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
- <dependency name="test" rev="1.0"/>
- </dependencies>
-</ivy-module>
+include::src/example/chained-resolvers/chainedresolvers-project/ivy.xml[]
----
-As we'd expect, the ivy file declares this module to be dependent on the two libraries it uses: 'commons-lang' and 'test'. Note that we didn't specify the org for the dependency 'test'. When we exclude org, Ivy assumes it is in the same org as the declaring module. (i.e. 'org.apache').
+As we'd expect, the ivy file declares this module to be dependent on the two libraries it uses: `commons-lang` and `test`. Note that we didn't specify the `org` for the dependency `test`. When we exclude `org`, Ivy assumes it is in the same `org` as the declaring module. (in this example, it's `org.apache`).
-=== the *ivy settings*
+=== The Ivy Settings
-The settings are defined in the ivysettings.xml file located in the settings directory of the project. Below are its contents, followed by an explanation of what it's doing.
+The settings are defined in the `ivysettings.xml` file located in the `settings` directory of the project. Below are its contents, followed by an explanation of what it's doing.
[source]
----
-
-<ivysettings>
- <settings defaultResolver="chain-example"/>
- <resolvers>
- <chain name="chain-example">
- <filesystem name="libraries">
- <artifact pattern="${ivy.settings.dir}/repository/[artifact]-[revision].[ext]"/>
- </filesystem>
- <ibiblio name="ibiblio" m2compatible="true"/>
- </chain>
- </resolvers>
-</ivysettings>
-
+include::src/example/chained-resolvers/settings/ivysettings.xml[]
----
-=== the *settings* tag
+=== The *settings* tag
This tag initializes Ivy with some parameters. Here only one parameter is set, the name of the resolver to use by default.
-=== the *resolvers* tag
+=== The *resolvers* tag
+
+The resolvers section defines the list of resolvers that Ivy will use to locate artifacts. In our example, we have only one resolver named `chain-example`, which is unique in that it defines a list (hence a chain) of resolvers.
-The resolvers section defines the list of resolvers that Ivy will use to locate artifacts. In our example, we have only one resolver named "chain-example", which is unique in that it defines a list (hence a chain) of resolvers.
The resolvers in this chain are:
-* libraries : It is a filesystem resolver, so looks at a directory structure to retrieve the artifacts. This one is configured to look in the `repository` sub directory of the directory that contains the `ivysettings.xml` file. +
+ * `libraries` : It is a filesystem resolver, so looks at a directory structure to retrieve the artifacts. This one is configured to look in the `repository` sub directory of the directory that contains the `ivysettings.xml` file. +
-* ibiblio : It looks in the ibiblio maven repository to retrieve the artifacts. +
+ * `ibiblio` : It looks in the ibiblio Maven repository to retrieve the artifacts. +
That's it, we have just configured a chain of resolvers!
-== walkthrough
+== Walkthrough
-=== step 1: preparation
+=== Step 1: Preparation
-Open a DOS or shell window, and go to the "chained-resolvers" directory.
+Open a DOS or shell window, and go to the `src/example/chained-resolvers` directory.
-=== step 2: clean directory tree
+=== Step 2: clean directory tree
-On the prompt type: ant
+On the prompt type: `ant`
This will clean up the entire project directory tree and Ivy cache. You can do this each time you want to clean up this example.
@@ -132,16 +117,16 @@ This will clean up the entire project directory tree and Ivy cache. You can do t
[NOTE]
====
-In almost all examples, we provide a clean target as default target. Since most examples use the same Ivy cache, you will clean the whole Ivy cache each time you call this target.
+In almost all examples, we provide a `clean` target, as the default target. Since most examples use the same Ivy cache, you will clean the whole Ivy cache each time you call this target.
-Cleaning the Ivy cache is something you can do without fear (except performance): it's only a cache, so everything can be (and should be) obtained again from repositories. This may sound strange to those coming from maven 2 land. But remember that in Ivy, the cache is not a local repository and the two are completely isolated.
+Cleaning the Ivy cache is something you can do without fear (except performance): it's only a cache, so everything can be (and should be) obtained again from repositories. This may sound strange to those coming from Maven 2 land. But remember that in Ivy, the cache is not a local repository and the two are completely isolated.
====
-=== step 3: run the project
+=== Step 3: run the project
Go to `chained-resolvers` project directory. And simply run `ant`.
@@ -157,7 +142,7 @@ include::asciidoc/tutorial/log/chained-resolvers.txt[]
We can see in the log of the resolve task, that the two dependencies have been retrieved (2 artifacts) and copied to the Ivy cache directory (2 downloaded).
-Also notice that the 'run' Ant target succeeded in using both commons-lang.jar coming from the ibiblio repository and test.jar coming from the local repository.
+Also notice that the `run` Ant target succeeded in using both `commons-lang.jar` coming from the ibiblio repository and `test.jar` coming from the local repository.
== Going further
@@ -167,8 +152,8 @@ This very simple example helps us see how to set up two resolvers in a chain. Th
Below are a few more interesting things worth knowing about chain resolvers. After reading them, go ahead and try tweaking this example using your new wealth of knowledge!
-* a chain is not limited to two nested resolvers, you can use as many as you want +
+ * a chain is not limited to two nested resolvers, you can use as many as you want +
-* by setting `returnFirst="true"`, you can have a chain which stops as soon as it has found a result for a given module +
+ * by setting `returnFirst="true"`, you can have a chain which stops as soon as it has found a result for a given module +
-* by setting `dual="true"`, the full chain will be used both for module descriptors and artifacts, while setting `dual="false"`, the resolver in the chain which found the module descriptor (if any) is also used for artifacts +
+ * by setting `dual="true"`, the full chain will be used both for module descriptors and artifacts, while setting `dual="false"`, the resolver in the chain which found the module descriptor (if any) is also used for artifacts +
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/87c4e065/asciidoc/tutorial/start.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/start.adoc b/asciidoc/tutorial/start.adoc
index 4471a65..8fc1e94 100644
--- a/asciidoc/tutorial/start.adoc
+++ b/asciidoc/tutorial/start.adoc
@@ -17,7 +17,9 @@
under the License.
////
-In this tutorial, you will see one of the simplest ways to use Ivy. With no specific settings, Ivy uses the maven 2 repository to resolve the dependencies you declare in an Ivy file. Let's have a look at the content of the files involved.
+= Ivy Quickstart
+
+In this tutorial, you will see one of the simplest ways to use Ivy. With no specific settings, Ivy uses the Maven 2 repository to resolve the dependencies you declare in an Ivy file. Let's have a look at the content of the files involved.
_You'll find this tutorial's sources in the ivy distribution in the src/example/hello-ivy directory._
@@ -27,7 +29,7 @@ _You'll find this tutorial's sources in the ivy distribution in the src/example/
This file is used to describe the dependencies of the project on other libraries.
Here is the sample:
-[source]
+[source, xml]
----
<ivy-module version="2.0">
@@ -40,35 +42,33 @@ Here is the sample:
----
-The format of this file should pretty easy to understand, but let's give some details about what is declared here. First, the root element ivy-module, with the version attribute used to tell Ivy which version of Ivy this file uses.
+The format of this file should pretty easy to understand, but let's give some details about what is declared here. First, the root element `ivy-module`, with the `version` attribute used to tell Ivy which version of Ivy this file uses.
-Then there is an info tag, which is used to give information about the module for which we are defining dependencies. Here we define only the organization and module name. You are free to choose whatever you want for them, but we recommend avoiding spaces for both.
+Then there is an `info` tag, which is used to give information about the module for which we are defining dependencies. Here we define only the `organization` and `module` name. You are free to choose whatever you want for them, but we recommend avoiding spaces for both.
-Finally, the dependencies section lets you define dependencies. Here this module depends on two libraries: commons-lang and commons-cli. As you can see, we use the `org` and `name` attributes to define the organization and module name of the dependencies we need. The `rev` attribute is used to specify the version of the module you depend on.
+Finally, the `dependencies` section lets you define dependencies. In this example, this module depends on two libraries: `commons-lang` and `commons-cli`. As you can see, we use the `org` and `name` attributes to define the organization and module name of the dependencies we need. The `rev` attribute is used to specify the version of the module you depend on.
-To know what to put in these attributes, you need to know the exact information for the libraries you depend on. Ivy uses the maven 2 repository by default, so we recommend you use link:http://mvnrepository.com[mvnrepository.com] to look for the module you want. Once you find it, you will have the details on how to declare the dependency in a maven POM. For instance:
+To know what to put in these attributes, you need to know the exact information for the libraries you depend on. Ivy uses the Maven 2 central repository by default, so we recommend you use link:https://mvnrepository.com[mvnrepository.com] to look for the module you want. Once you find it, you will have the details of that module in the `pom.xml` file of that module. For instance:
-[source]
+[source, xml]
----
-
-<dependency>
- <groupId>commons-lang</groupId>
- <artifactId>commons-lang</artifactId>
- <version>2.0</version>
-</dependency>
-
+ <project ....>
+ <groupId>commons-lang</groupId>
+ <artifactId>commons-lang</artifactId>
+ <version>2.0</version>
+ ...
----
-To convert this into an Ivy dependency declaration, all you have to do is use the groupId as organization, the artifactId as module name, and the version as revision. That's what we did for the dependencies in this tutorial, that is commons-lang and commons-cli. Note that having commons-lang and commons-cli as organization is not the best example of what the organization should be. It would be better to use org.apache, org.apache.commons or org.apache.commons.lang. However, this is how these modules are identified in the maven 2 repository, so the simplest way to get them is to use the details as is (you will see in link:../tutorial/build-repository.html[Building a repository] that you can use namespaces to redefine these names if you want something cleaner).
+To convert this into an Ivy dependency declaration, all you have to do is use the `groupId` as organization, the `artifactId` as module name, and the version as revision. That's what we did for the dependencies in this tutorial, that is `commons-lang` and `commons-cli`. Note that having `commons-lang` and `commons-cli` as `organization` is not the best example of what the organization should be. It would be better to use `org.apache`, `org.apache.commons` or `org.apache.commons.lang`. However, this is how these specific modules were identified in the Maven 2 repository, so the simplest way to get them is to use the details as is (you will see in link:../tutorial/build-repository.html[Building a repository] that you can use namespaces to redefine these names if you want something cleaner).
If you want more details on what you can do in Ivy files, you can have a look at the link:../ivyfile.html[Ivy files reference documentation].
== The build.xml file
The corresponding build file contains a set of targets, allowing you to resolve dependencies declared in the Ivy file, to compile and run the sample code, produce a report of dependency resolution, and clean the cache or the project.
-You can use the standard "ant -p" to get the list of available targets. Feel free to have a look at the whole file, but here is the part relevant to dependency resolution:
+You can use the standard `ant -p` to get the list of available targets. Feel free to have a look at the whole file, but here is the part relevant to dependency resolution:
-[source]
+[source, xml]
----
<project xmlns:ivy="antlib:org.apache.ivy.ant" name="hello-ivy" default="run">
@@ -93,10 +93,10 @@ Note that in this case we define a `resolve` target and call the `link:../use/re
== Running the project
-OK, now that we have seen the files involved, let's run the sample to see what happens. Open a shell (or command line) window, and enter the `hello-ivy` example directory.
+OK, now that we have seen the files involved, let's run the sample to see what happens. Open a shell (or command line) window, and go into the `hello-ivy` example directory.
Then, at the command prompt, run `ant`:
-[source,shell]
+[source, shell]
----
include::asciidoc/tutorial/log/hello-ivy-1.txt[]
@@ -107,8 +107,8 @@ include::asciidoc/tutorial/log/hello-ivy-1.txt[]
== What happened ?
-Without any settings, Ivy retrieves files from the maven 2 repository. That's what happened here.
-The resolve task has found the commons-lang and commons-cli modules in the maven 2 repository, identified that commons-cli depends on commons-logging and so resolved it as a transitive dependency. Then Ivy has downloaded all corresponding artifacts in its cache (by default in your user home, in a .ivy2/cache directory). Finally, the retrieve task copies the resolved jars from the ivy cache to the default library directory of the project: the lib dir (you can change this easily by setting the pattern attribute on the link:../use/retrieve.html[retrieve] task).
+Without any settings, Ivy retrieves files from the Maven 2 repository. That's what happened here.
+The resolve task has found the `commons-lang` and `commons-cli` modules in the Maven 2 central repository, identified that `commons-cli` depends on `commons-logging` and so resolved it as a transitive dependency. Then Ivy has downloaded all corresponding artifacts in its cache (by default in your user home, in a `.ivy2/cache` directory). Finally, the retrieve task copies the resolved jars from the ivy cache to the default library directory of the project: the `lib` dir (you can change this easily by setting the pattern attribute on the link:../use/retrieve.html[retrieve] task).
You might say that the task took a long time just to write out a "Hello Ivy!" message. But remember that a lot of time was spent downloading the required files from the web. Let's try to run it again:
@@ -124,4 +124,4 @@ Great! The cache was used, so no download was needed and the build was instantan
And now, if you want to generate a report detailing all the dependencies of your module, you can call the report target, and check the generated file in the build directory. You should obtain something looking like link:../samples/apache-hello-ivy-default.html[this].
-As you can see, using Ivy to resolve dependencies stored in the maven 2 repository is extremely easy. Now you can go on with the next tutorials to learn more about link:../tutorial/conf.html[how to use module configurations] which is a very powerful Ivy specific feature. Other tutorials are also available where you will learn how to use Ivy settings to leverage a possibly complex enterprise repository. It may also be a good time to start reading the link:../reference.html[reference documentation], and especially the introduction material which gives a good overview of Ivy. The link:../bestpractices.html[best practices] page is also a must read to start thinking about how to use Ant+Ivy to build a clean and robust build system.
+As you can see, using Ivy to resolve dependencies stored in the Maven 2 repository is extremely easy. Now you can go on with the next tutorials to learn more about link:../tutorial/conf.html[how to use module configurations] which is a very powerful Ivy specific feature. Other tutorials are also available where you will learn how to use Ivy settings to leverage a possibly complex enterprise repository. It may also be a good time to start reading the link:../reference.html[reference documentation], and especially the introduction material which gives a good overview of Ivy. The link:../bestpractices.html[best practices] page is also a must read to start thinking about how to use Ant+Ivy to build a clean and robust build system.