http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/tutorial/build-repository/advanced.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/tutorial/build-repository/advanced.adoc b/asciidoc/tutorial/build-repository/advanced.adoc index 0558797..56f745a 100644 --- a/asciidoc/tutorial/build-repository/advanced.adoc +++ b/asciidoc/tutorial/build-repository/advanced.adoc @@ -23,17 +23,17 @@ Now that you have seen how simple it is to create your own repository from an ex == On the road to a professional repository -In this section, you will learn how to build a *professional* repository. What is a *professional* repository? Our vision is to say that a good quality repository must follow clear rules about projects naming and must offer correct, usable, configurations and verified project descriptors. In order to achieve those goals, we think that you have to build your own repository. -We have seen in the previous example, that we could use some public repositories to begin to build our own repository. Nevertheless, the result is not always the expected one, especially concerning the naming rules used. +In this section, you will learn how to build a *professional* repository. What is a *professional* repository? Our vision is to say that a good quality repository must follow clear rules about project naming and must offer correct, usable configurations and verified project descriptors. In order to achieve those goals, we believe that you have to build your own repository. +We have seen in the previous example, that we could use some public repositories to begin building our own repository. Nevertheless, the result is not always the expected one, especially concerning the naming rules used. -This problem is pretty normal when you have an existing repository, and want to benefit from large public repositories which do not follow the same naming conventions. It also shows up because many public repositories do not use a consistent naming scheme. For example, why don't all the apache commons modules use the org.apache.commons organization? Well.. for historical reasons. But if you setup your own repository, you may not want to suffer from the mistakes of history. +This problem is pretty normal when you have an existing repository, and want to benefit from large public repositories which do not follow the same naming conventions. It also shows up because many public repositories do not use a consistent naming scheme. For example, why don't all the Apache commons modules use the org.apache.commons organization? Well... for historical reasons. But if you set up your own repository, you may not want to suffer from the mistakes of history. Fortunately, Ivy has a very powerful answer to this problem: link:../../settings/namespaces.html[namespaces]. == Using namespaces -If you look at the repository built with the link:../../tutorial/build-repository/basic.html[previous tutorial], you will see exactly what we were talking about: all apache commons modules use their own name as their organization. +If you look at the repository built with the link:../../tutorial/build-repository/basic.html[previous tutorial], you will see exactly what we were talking about: all Apache commons modules use their own name as their organization. So let's see what Ivy can do using namespaces (we will dig into details later): @@ -56,7 +56,7 @@ include::asciidoc/tutorial/log/myrepository-content-namespace.txt[] ---- -We can even have a look at the commons-lang ivy file in our repository: +We can even have a look at the commons-lang Ivy file in our repository: [source] ---- @@ -97,12 +97,12 @@ A namespace is defined by a set of rules. These rules are based on regular expre For the namespace we call __maven2__, we have declared several rules. Below is one of the rules: -==== rule handling the imported apache maven1 projects +==== rule handling the imported Apache Maven 1 projects [source] ---- -<rule> <!-- imported apache maven1 projects --> +<rule> <!-- imported apache maven 1 projects --> <fromsystem> <src org="apache" module=".+"/> @@ -137,7 +137,7 @@ To understand namespaces, * *fromsystem :* we define here that the projects defined in the system namespace under the organization called "apache" are transformed into the destination namespace into projects whose organization is named with the module name, whatever the revision is. For example, the project apache#commons-lang;1.0 in the system namespace will be translated into commons-lang#commons-lang;1.0 in the maven2 resolver namespace. + -* *tosystem :* we define here the reverse mapping, i.e. how to translate _apache_ projects from maven 2 repo into apache projects in the system namespace. The rule used here tells Ivy that all projects matching `commons-.+` (see it as java regular expression) for their organization name and module name are transformed into projects whose organisation is `apache` with the module name as it was found. The same kind of rule is defined for others apache projects like ant, etc. + +* *tosystem :* we define here the reverse mapping, i.e. how to translate _apache_ projects from Maven 2 repo into Apache projects in the system namespace. The rule used here tells Ivy that all projects matching `commons-.+` (see it as Java regular expression) for their organization name and module name are transformed into projects whose organisation is `apache` with the module name as it was found. The same kind of rule is defined for other Apache projects like Ant, etc. + OK, you should now get the idea behind namespaces, so go ahead and look at the `ivysettings-advanced.xml` file in this example. You can test the installation of a module and its dependencies using namespaces.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/tutorial/build-repository/basic.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/tutorial/build-repository/basic.adoc b/asciidoc/tutorial/build-repository/basic.adoc index dfe6a16..e84926c 100644 --- a/asciidoc/tutorial/build-repository/basic.adoc +++ b/asciidoc/tutorial/build-repository/basic.adoc @@ -17,12 +17,12 @@ under the License. //// -In this first step, we use the link:../../use/install.html[install] Ant task to install modules from the maven 2 repository to a file system based repository. We first install a module by itself, excluding dependencies, then again with its dependencies. +In this first step, we use the link:../../use/install.html[install] Ant task to install modules from the Maven 2 repository to a file system based repository. We first install a module by itself, excluding dependencies, then again with its dependencies. == Basic: ivysettings.xml file used -The ivy settings file that we will use is very simple here. It defines two resolvers, __libraries__ and __my-repository__. The first one is used as the source, the second one as the destination. In a typical setup, the second one would be configured using an link:../../settings/include.html[include] that included an existing settings file used by the development team. +The Ivy settings file that we will use is very simple here. It defines two resolvers, __libraries__ and __my-repository__. The first one is used as the source, the second one as the destination. In a typical setup, the second one would be configured using an link:../../settings/include.html[include] that included an existing settings file used by the development team. [source] @@ -44,7 +44,7 @@ The ivy settings file that we will use is very simple here. It defines two resol ---- -== install a simple module with no dependencies +== Install a simple module without dependencies Let's have a look at the _maven2_ target. @@ -60,7 +60,7 @@ Let's have a look at the _maven2_ target. ---- -Pretty simple, we call the [[ant:install] task with the settings we have loaded using link:../../use/settings.html[ivy:settings] as usual. We then set the source and destination repositories using the __from__ and __to__ attributes. We used Ant properties for these values here, which helps ease the maintenance of the script, but it's basically the name of our resolvers: 'libraries' for the source and 'my-repository' for the destination. +Pretty simple, we call the link:../../use/install.html[ivy:install] task with the settings we have loaded using link:../../use/settings.html[ivy:settings] as usual. We then set the source and destination repositories using the __from__ and __to__ attributes. We used Ant properties for these values here, which helps ease the maintenance of the script, but it's basically the name of our resolvers: 'libraries' for the source and 'my-repository' for the destination. Here is the Ant call output : @@ -72,7 +72,7 @@ include::asciidoc/tutorial/log/install.txt[] ---- -The trace tells us that the module definition was found using the "libraries" resolver and that the corresponding artifact was downloaded from the maven 2 repository. Then both were published to the filesystem repository (my-repository). +The trace tells us that the module definition was found using the "libraries" resolver and that the corresponding artifact was downloaded from the Maven 2 repository. Then both were published to the filesystem repository (my-repository). Let's have a look at our repository : @@ -87,9 +87,9 @@ include::asciidoc/tutorial/log/myrepository-content.txt[] We can see that we now have the commons-lang module version 1.0 in our repository, with a generated ivy.xml file, its jar, and all the md5 and sha1 checksums for future consistency checks when developers use this repository to resolve modules. -== install a module with dependencies +== Install a module with dependencies -Now let's say that we want to be sure all the dependencies of the module we install are available in our repository after the installation. We could either install without dependencies on a staging repository and check the missing dependencies (more control), or use transitive dependency management and ask Ivy to install everything for us (much simpler). +Now let's say that we want to be sure all the dependencies of the module we install are available in our repository after the installation. We could either install without dependencies in a staging repository and check the missing dependencies (more control), or use transitive dependency management and ask Ivy to install everything for us (much simpler). The `maven2-deps` target is very similar to the one described above, except that we explicitly ask for transitive installation. @@ -117,13 +117,13 @@ include::asciidoc/tutorial/log/install-deps.txt[] -As you can see the installation has failed, if you look at the log you will see that there are missing artifacts on the source repository. This means that you will need to download those artifacts manually, and copy them to your destination repository to complete the installation. Fortunately Ivy uses a best effort algorithm during install, so that everything gets installed except the missing artifacts. (Note: these missing artifacts are not in the public maven repository due to licensing issues) +As you can see the installation has failed, and if you look at the log you will see that there are missing artifacts in the source repository. This means that you will need to download those artifacts manually, and copy them to your destination repository to complete the installation. Fortunately Ivy uses a best effort algorithm during install, so that everything gets installed except the missing artifacts. (Note: these missing artifacts are not in the public Maven repository due to licensing issues.) -You may also have noticed that Ivy installed 2 different revisions of commons-logging (1.0.2, 1.0.4). This is due to the fact that we used the "no conflict" link:../../settings/conflict-managers.html[conflict manager] in the ivysettings file. +You may also have noticed that Ivy installed 2 different revisions of commons-logging (1.0.2, 1.0.4). This is due to the fact that we used the "no conflict" link:../../settings/conflict-managers.html[conflict manager] in the Ivy settings file. -We do not want to evict any modules because we are building our own repository. Indeed if we get both commons-logging 1.0.2 and 1.0.4 it's because some modules among the transitive dependencies of hibernate depend on 1.0.2 and others on 1.0.4. If we got only 1.0.4, the module depending on 1.0.2 would be inconsistent in your own repository (depending on a version you don't have installed). Thus developers using this module directly would run into a problem. +We do not want to evict any modules because we are building our own repository. Indeed, if we get both commons-logging 1.0.2 and 1.0.4, it's because some modules among the transitive dependencies of hibernate depend on 1.0.2 and others on 1.0.4. If we got only 1.0.4, the module depending on 1.0.2 would be inconsistent in your own repository (depending on a version you did not install). Thus developers using this module directly would run into a problem. -If you now have a closer look at your repository, you will probably notice that it isn't an exact replication of the original one. Let's have a look at the directory of one module: +If you now have a closer look at your repository, you will probably notice that it isn't an exact replica of the original one. Let's have a look at the directory of one module: [source,shell] ---- @@ -135,6 +135,6 @@ include::asciidoc/tutorial/log/myrepository-content-deps.txt[] -As you can see there is no pom here (pom is the module metadata format used by maven 2, available on the maven 2 repository). Instead you can see there's an ivy file, which is actually the original hibernate pom converted into an ivy file. So now you have a true Ivy repository with ivy files, where you can use the full power of Ivy if you want to adjust the module metadata (module configurations, fine grain exclusions and transitivity control, per module conflict manager, ...). +As you can see there is no POM here (POM is the module metadata format used by Maven 2, available in the Maven 2 repository). Instead you can see there's an Ivy file, which is actually the original Hibernate POM converted into an Ivy file. So now you have a true Ivy repository with Ivy files, where you can use the full power of Ivy if you want to adjust the module metadata (module configurations, fine grained exclusions and transitivity control, per module conflict manager, ...). OK, enough for this simple repository installation, the link:../../tutorial/build-repository/advanced.html[next tutorial] will show how you can deal with more complex cases where your source and destination repositories do not follow the same naming conventions. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/tutorial/conf.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/tutorial/conf.adoc b/asciidoc/tutorial/conf.adoc index 6ceee55..94803f7 100644 --- a/asciidoc/tutorial/conf.adoc +++ b/asciidoc/tutorial/conf.adoc @@ -17,7 +17,7 @@ under the License. //// -This tutorial introduces the use of module configurations in ivy files. Ivy module configurations are indeed a very important concept. Someone even told me one day that using Ivy without using configurations is like eating a good cheese without touching the glass of Chateau Margaux 1976 you have just poured :-) +This tutorial introduces the use of module configurations in Ivy files. Ivy module configurations are indeed a very important concept. Someone even told me one day that using Ivy without using configurations is like eating a good cheese without touching the glass of Chateau Margaux 1976 you have just poured :-) More seriously, configurations in Ivy can be better understood as views on your module, and you will see how they can be used effectively here. @@ -26,11 +26,13 @@ Reference documentation on configurations can be found link:../terminology.html[ == Introduction Source code is available in `src/example/configurations/multi-projects`. -We have two projects : +We have two projects: + - filter-framework is a library that defines an api to filter String arrays and two implementations of this api. - myapp is a very small app that uses filter-framework. The filter-framework library project produces 3 artifacts: + - the api jar, - an implementation jar with no external dependencies, - a second implementation jar that needs commons-collections to perform. @@ -40,7 +42,7 @@ The application only needs the api jar to compile and can use either of the two == The library project -The first project we'll look at in this tutorial is filter-framework. In order to have a fine-grained artifacts publication definition, we defined several configurations, each which maps to a set of artifacts that other projects can make use of. +The first project we'll look at in this tutorial is filter-framework. In order to have a fine-grained artifact publication definition, we defined several configurations, each of which maps to a set of artifacts that other projects can make use of. === The ivy.xml file @@ -75,7 +77,7 @@ The first project we'll look at in this tutorial is filter-framework. In order t === Explanation -As you can see, we defined 4 configurations, with 3 being public and 1 private. (the junit dependency for testing). +As you can see, we defined 4 configurations, with 3 being public and 1 private (the JUnit dependency for testing). The 2 implementation configurations, *homemade-impl* and *cc-impl* extend the *api* configuration so that all artifacts defined in *api* will also be part of the extending configuration. In the publications tag, we defined the artifacts we produce (jars in this case) and we assign them to a configuration. When others use our library they will have a flexible way to ask for what they need. @@ -140,7 +142,7 @@ We also defined a dependency on our previously built library. In this dependency . *withexternaljar->cc-impl* : here we tell Ivy that our *withexternaljar* configuration depends on the *cc-impl* configuration of the dependency + -Note that we never declare any of the dependency's artifacts we need in each configuration: it's the dependency module's ivy file which declares the published artifacts and which should be used in each configuration. +Note that we never declare any of the dependency's artifacts we need in each configuration: it's the dependency module's Ivy file that declares the published artifacts which should be used in each configuration. In the Ant `build.xml` file, we defined a 'resolve' target as follow: @@ -186,7 +188,7 @@ When we call this target, Ivy will do a resolve using our `ivy.xml` file in the ---- -As you can see, for each configuration we have now a set of jars. +As you can see, we have a set of jars for each configuration now. Let's try to launch our app. @@ -219,4 +221,4 @@ Nice! We got the same result, but we can see that the implementation classes are == Conclusion -*You should use configurations as often as possible.* Configurations are a very important concept in Ivy. They allow you to group artifacts and give the group a meaning. When you write ivy files for projects that are intended for use by others, use configurations to allow people to get only what they need, without having to specify them one by one in their own dependency list. +*You should use configurations as often as possible.* Configurations are a very important concept in Ivy. They allow you to group artifacts and give the group a meaning. When you write Ivy files for projects that are intended for use by others, use configurations to allow people to get only what they need, without having to specify them one by one in their own dependency list. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/tutorial/defaultconf.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/tutorial/defaultconf.adoc b/asciidoc/tutorial/defaultconf.adoc index 681837d..b33f7b7 100644 --- a/asciidoc/tutorial/defaultconf.adoc +++ b/asciidoc/tutorial/defaultconf.adoc @@ -36,7 +36,7 @@ The default settings include 3 types of repositories: 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 + A public repository in 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. @@ -57,17 +57,17 @@ 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. 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 the 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. +Note that modules can be split across the shared repository and the public one: for example, you can have the module descriptor in the shared repository and the artifacts in the public one. === Public -The public repository is the place where most modules can be found, but which sometimes lack the information you need. It's usually a repository available through an internet connection only, even if this is not mandatory. +The public repository is the place where most modules can be found, but which sometimes lack the information you need. It's usually a repository available through an Internet connection only, even if this is not mandatory. == Setting up the repositories -Now that we have seen the objective of each of the three repositories, let's see how they are setup and how to configure them to fit your needs. +Now that we have seen the objective of each of the three repositories, let's see how they are set up and how to configure them to fit your needs. First, several repositories use the same root in your filesystem. Referenced as `${ivy.default.ivy.user.dir}`, this is by default the directory `.ivy2` in your user home. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/tutorial/dependence.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/tutorial/dependence.adoc b/asciidoc/tutorial/dependence.adoc index 502cb3f..a418a7b 100644 --- a/asciidoc/tutorial/dependence.adoc +++ b/asciidoc/tutorial/dependence.adoc @@ -27,12 +27,12 @@ For our example, we will have two projects, depender and dependee, where the dep * that child projects can retrieve the "latest" version of the dependee project + -== projects used +== Projects used === dependee -The dependee project is very simple. It depends on the apache library commons-lang and contains only one class: `standalone.Main` which provides two services: +The dependee project is very simple. It depends on the Apache library commons-lang and contains only one class: `standalone.Main` which provides two services: * return the version of the project + @@ -42,11 +42,11 @@ The dependee project is very simple. It depends on the apache library commons-la 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 project ivy file + +* ivy.xml: the project Ivy file + -* src standalone\Main.java: the only class of the project + +* src/standalone/Main.java: the only class of the project + Take a look at the *ivy.xml* file: @@ -62,7 +62,7 @@ Take a look at the *ivy.xml* file: ---- -The ivy file declares only one dependency, that being the apache commons-lang library. +The Ivy file declares only one dependency, that being the Apache commons-lang library. === depender @@ -88,7 +88,7 @@ Take a look at the `ivy.xml` file: ---- -== settings +== Settings The Ivy settings are defined in two files located in the settings directory: @@ -136,7 +136,7 @@ The second parameter, tells Ivy to use a resolver named "libraries" as its defau This tag defines the resolvers to use. Here we have two resolvers defined: "projects" and "libraries". The filesystem resolver called "projects" is able to resolve the internal dependencies by locating them on the local filesystem. -The ibiblio resolver called "libraries" is able to find dependencies on the maven 2 repository, but doesn't use maven poms. +The ibiblio resolver called "libraries" is able to find dependencies on the Maven 2 repository, but doesn't use Maven POMs. === modules @@ -144,24 +144,24 @@ The modules tag allows you to configure which resolver should be used for which All other modules (i.e. all modules but org.apache#dependee), will use the default resolver ("libraries"). -== walkthrough +== Walkthrough -=== step 1: preparation +=== Step 1: Preparation -Open a DOS or shell window, and go to the `src/example/dependence` directory. +Open a shell (or command line) window, and go to the `src/example/dependence` directory. -=== step 2: clean directory tree +=== Step 2: Clean directory tree -On the prompt type: `ant` +At the prompt, type: `ant` This will clean up the entire project directory tree. You can do this each time you want to clean up this example. -=== step 3: publication of dependee project +=== Step 3: Publication of dependee project Go to `dependee` directory and publish the project @@ -186,17 +186,17 @@ What we see here: As you can see, the call to the publish task has resulted in two main things: -* the delivery of a resolved ivy file to `build/ivy.xml`. + -This has been done because by default, the publish task not only publishes artifacts, but also its ivy file. So it has looked to the path where the ivy file to publish should be, using the artifactspattern: `${build.dir}/[artifact].[ext]`. For an ivy file, this resolves to `build/ivy.xml`. Because this file does not exist, it automatically makes a call to the deliver task which delivers a resolved ivy file to this destination. +* the delivery of a resolved Ivy file to `build/ivy.xml`. + +This has been done because by default, the publish task not only publishes artifacts, but also its Ivy file. So it has looked to the path where the Ivy file to publish should be, using the artifactspattern: `${build.dir}/[artifact].[ext]`. For an Ivy file, this resolves to `build/ivy.xml`. Because this file does not exist, it automatically makes a call to the deliver task which delivers a resolved Ivy file to this destination. -* the publication of artifact 'dependee' and its resolved ivy file to the repository. + -Both are just copies of the files found in the current project, or more precisely, those in the `build` directory. This is because the artifactspattern has been set to `${build.dir}/[artifact].[ext]`, so the dependee artifact is found at `build/dependee.jar` and the ivy file in `build/ivy.xml`. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to `repository\dependee-1.jar` and to `repository\dependee-1.xml`, respecting the artifact and ivy patterns of our settings (see above). +* the publication of artifact 'dependee' and its resolved Ivy file to the repository. + +Both are just copies of the files found in the current project, or more precisely, those in the `build` directory. This is because the artifactspattern has been set to `${build.dir}/[artifact].[ext]`, so the dependee artifact is found at `build/dependee.jar` and the Ivy file in `build/ivy.xml`. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to `repository/dependee-1.jar` and to `repository/dependee-1.xml`, respecting the artifact and Ivy file patterns of our settings (see above). -=== step 4: running the depender project +=== Step 4: Running the depender project Go to directory depender and run `ant` @@ -222,7 +222,7 @@ What we see here: -=== step 5: new version of dependee project +=== Step 5: New version of dependee project Like we did before in step 3, publish the dependee project again. This will result in a new version of the project being published. @@ -251,7 +251,7 @@ I:\dependee> OK, now our repository contains two versions of the project *dependee*, so other projects can refer to either version. -=== step 6: get the new version in _depender_ project +=== Step 6: Get the new version in _depender_ project What should we expect if we run the depender project again? It should: @@ -270,4 +270,4 @@ include::asciidoc/tutorial/log/dependence-depending-2.txt[] ---- -OK, we got what we expected as the `run` target shows that we are using version 2 of the main class of the dependee project. If we take a look at the resolve target results, we see that one artifact has been downloaded to the ivy cache. In fact, this file is the same version 2 of the dependee project that is in the repository, but now all future retrievals will pull it from your ivy-cache directory. +OK, we got what we expected as the `run` target shows that we are using version 2 of the main class of the dependee project. If we take a look at the resolve target results, we see that one artifact has been downloaded to the Ivy cache. In fact, this file is the same version 2 of the dependee project that is in the repository, but now all future retrievals will pull it from your ivy-cache directory. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/tutorial/dual.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/tutorial/dual.adoc b/asciidoc/tutorial/dual.adoc index ba33d9c..1700fc9 100644 --- a/asciidoc/tutorial/dual.adoc +++ b/asciidoc/tutorial/dual.adoc @@ -17,38 +17,38 @@ under the License. //// -In some cases, your module descriptions (i.e. Ivy files, maven poms) are located separately from the module artifacts (i.e. jars). So what can you do about it? +In some cases, your module descriptions (i.e. Ivy files, Maven POMs) are located separately from the module artifacts (i.e. jars). So what can you do about it? Use a Dual resolver! And this tutorial will show you how. -== project description +== Project description Let's have a look at the `src/example/dual` directory in your Ivy distribution. It contains a build file and 3 directories: -* settings: contains the ivy settings file + +* settings: contains the Ivy settings file + -* repository: a sample repository of ivy files + +* repository: a sample repository of Ivy files + * project: the project making use of Ivy with dual resolver + -=== the dual project +=== The dual project -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.HelloIvy` It depends on two libraries: Apache commons-lang and Apache commons-httpclient. Here is the content of the project: -* build.xml: the ant build file for the project + +* 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/HelloIvy.java: the only class of the project + Let's have a look at the `ivy.xml` file: @@ -60,18 +60,18 @@ Let's have a look at the `ivy.xml` file: <info organisation="org.apache" module="hello-ivy"/> <dependencies> <dependency org="commons-httpclient" name="commons-httpclient" rev="2.0.2"/> - <dependency org="commons-lang" name="commons-lang" rev="2.0"/> + <dependency org="commons-lang" name="commons-lang" rev="2.6"/> </dependencies> </ivy-module> ---- -As you can see, nothing special here... Indeed, Ivy's philosophy is to keep ivy files independent of the way dependencies are resolved. +As you can see, nothing special here... Indeed, Ivy's philosophy is to keep Ivy files independent of the way dependencies are resolved. -=== the *ivy* settings +=== The *Ivy* settings -The ivy settings are defined in the `ivysettings.xml` file located in the `settings` directory. Here is what it contains, followed by an explanation. +The Ivy settings are defined in the `ivysettings.xml` file located in the `settings` directory. Here is what it contains, followed by an explanation. [source] @@ -93,22 +93,22 @@ The ivy settings are defined in the `ivysettings.xml` file located in the `setti Here we configured one resolver, the default one, which is a dual resolver. This dual resolver has two sub resolvers: the first is what is called the "ivy" or "metadata" resolver of the dual resolver, and the second one is what is called the "artifact" resolver. It is important that the dual resolver has exactly two sub resolvers in this given order. -The metadata resolver, here a filesystem one, is used only to find module descriptors, in this case Ivy files. The setting shown here tells Ivy that all ivy files are in the `repository` directory, named with the pattern: `[module]-ivy-[revision].xml`. If we check the `repository` directory, we can confirm that it contains a file named `commons-httpclient-ivy-2.0.2.xml`. This file matches the pattern, so it will be found by the resolver. +The metadata resolver, here a filesystem one, is used only to find module descriptors, in this case Ivy files. The setting shown here tells Ivy that all Ivy files are in the `repository` directory, named according to the pattern: `[module]-ivy-[revision].xml`. If we check the `repository` directory, we can confirm that it contains a file named `commons-httpclient-ivy-2.0.2.xml`. This file matches the pattern, so it will be found by the resolver. -The artifact resolver is simply an ibiblio one, configured in m2compatible mode to use the maven 2 repository, with `usepoms="false"` to make sure it won't use maven 2 metadata. Note that this isn't necessary, since the second resolver in a dual resolver (the artifact resolver) is never asked to find module metadata. +The artifact resolver is simply an ibiblio one, configured in m2compatible mode to use the Maven 2 repository, with `usepoms="false"` to make sure it won't use Maven 2 metadata. Note that this isn't necessary, since the second resolver in a dual resolver (the artifact resolver) is never asked to find module metadata. -== walkthrough +== Walkthrough -=== step 1 : preparation +=== Step 1 : Preparation -Open a DOS or shell window, and go to the `dual` directory. +Open a shell (or command line) window, and go to the `dual` directory. -=== step 2 : clean up +=== Step 2 : Clean up On the prompt type : `ant` @@ -116,7 +116,7 @@ This will clean up the entire project directory tree (compiled classes and retri -=== step 3 : run the project +=== Step 3 : Run the project Go to the project directory. And simply run `ant`. @@ -130,7 +130,7 @@ include::asciidoc/tutorial/log/dual.txt[] -As you can see, Ivy not only downloaded commons-lang and commons-httpclient, but also commons-logging. Indeed, commons-logging is a dependency of httpclient, as we can see in the httpclient ivy file found in the `repository` directory: +As you can see, Ivy not only downloaded commons-lang and commons-httpclient, but also commons-logging. Indeed, commons-logging is a dependency of httpclient, as we can see in the httpclient Ivy file found in the `repository` directory: [source] ---- @@ -151,8 +151,8 @@ As you can see, Ivy not only downloaded commons-lang and commons-httpclient, but -So everything seemed to work. The ivy file was found in the `repository` directory and the artifacts have been downloaded from ibiblio. +So everything seemed to work. The Ivy file was found in the `repository` directory and the artifacts have been downloaded from ibiblio. -This kind of setup can be useful if you don't want to rely on the maven 2 repository for metadata, or if you want to take full advantage of Ivy files for some or all modules. Combining chain and dual resolvers should give you enough flexibility to meet almost any requirement. +This kind of setup can be useful if you don't want to rely on the Maven 2 repository for metadata, or if you want to take full advantage of Ivy files for some or all modules. Combining chain and dual resolvers should give you enough flexibility to meet almost any requirement. For full details about the dual resolver, have a look at the corresponding link:../resolver/dual.html[reference documentation]. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/tutorial/multiple.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/tutorial/multiple.adoc b/asciidoc/tutorial/multiple.adoc index c9a273e..dc17530 100644 --- a/asciidoc/tutorial/multiple.adoc +++ b/asciidoc/tutorial/multiple.adoc @@ -33,7 +33,7 @@ This tutorial is an example of how modules can be retrieved by multiple resolver 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 for a local repository and one using the Maven 2 repository. == Project Description @@ -48,11 +48,11 @@ It depends on two libraries: Apache's `commons-lang` and a custom library named 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 + - * 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: @@ -63,7 +63,7 @@ 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. (in this example, it's `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 @@ -103,7 +103,7 @@ That's it, we have just configured a chain of resolvers! === Step 1: Preparation -Open a DOS or shell window, and go to the `src/example/chained-resolvers` directory. +Open a shell (or command line) window, and go to the `src/example/chained-resolvers` directory. @@ -119,7 +119,7 @@ This will clean up the entire project directory tree and Ivy cache. You can do t 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 for 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. ==== http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/tutorial/multiproject.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/tutorial/multiproject.adoc b/asciidoc/tutorial/multiproject.adoc index 9877142..e0d97e9 100644 --- a/asciidoc/tutorial/multiproject.adoc +++ b/asciidoc/tutorial/multiproject.adoc @@ -19,12 +19,12 @@ In the previous tutorial, you saw how to deal with dependencies between two simple projects. -This tutorial will guide you through the use of Ivy in a more complete environment. All of the code for this tutorial is available in the `src/example/multi-project` directory of the Ivy distribution. +This tutorial will guide you through the use of Ivy in a more complex environment. All of the code for this tutorial is available in the `src/example/multi-project` directory of the Ivy distribution. == Context -Here is a 10000ft overview of the projects involved in this tutorial: +Here is a 10000 ft overview of the projects involved in this tutorial: * version + @@ -50,7 +50,10 @@ For sure this is not aimed to demonstrate how to develop a complex app or give i But this gives a simple understanding of how Ant+Ivy can be used to develop an application divided in multiple modules. Now, here is how these modules relate to each other: -link:../samples/projects-dependencies-graph.jpg[image::../samples/projects-dependencies-graph-small.jpg[]__click to enlarge__] + +image::../samples/projects-dependencies-graph-small.jpg[] + +link:../samples/projects-dependencies-graph.jpg[__click to enlarge__] Modules in yellow are the modules described in this tutorial, and modules in blue are external dependencies (we will see how to generate this graph later in this tutorial). @@ -134,16 +137,16 @@ contains a directory per module, with each containing: ** src + - the source directory with all java sources + the source directory with all Java sources Note that this example doesn't demonstrate many good practices for software development in general, in particular you won't find any unit test in these samples, even if we think unit testing is very important. But this isn't the aim of this tutorial. -Now that you are a bit more familiar with the structure, let's have a look at the most important part of this example: the common build file. Indeed, as you have seen, all the module's build files only import the common build file, and define their dependencies in their ivy files (which you should begin to be familiar with). +Now that you are a bit more familiar with the structure, let's have a look at the most important part of this example: the common build file. Indeed, as you have seen, all the module's build files only import the common build file, and define their dependencies in their Ivy files (which you should begin to be familiar with). So, here are some aspects of this common build file: -=== ivy settings +=== Ivy settings [source] @@ -179,7 +182,7 @@ Commented out you can see how the settings would have been done if the default s ---- -You should begin to be familiar with using Ivy this way. We call __resolve__ explicitly to use the ivy file configured (the default would have been fine), and then call __retrieve__ to copy resolved dependencies artifacts from the cache to a local lib directory. The pattern is also used to name the artifacts in the lib dir with their name and extension only (without revision), this is easier to use with an IDE, as the IDE configuration won't change when the artifacts version change. +You should begin to be familiar with using Ivy this way. We call __resolve__ explicitly to use the Ivy file configured (the default would have been fine), and then call __retrieve__ to copy resolved dependencies artifacts from the cache to a local lib directory. The pattern is also used to name the artifacts in the lib dir with their name and extension only (without revision), this is easier to use with an IDE, as the IDE configuration won't change when the artifact versions change. === ivy-new-version @@ -201,7 +204,7 @@ You should begin to be familiar with using Ivy this way. We call __resolve__ exp ---- -This target is used to ask Ivy to find a new version for a module. To get details about the module we are dealing with, we pull information out of the ivy file by using the ivy:info task. Then the link:../use/buildnumber.html[buildnumber] task is used to get a new revision, based on a prefix we set with a property, by default it will be 1.0-dev-b (have a look at the default value for `module.version.target` in the `common/build.properties` file). Each module built by this common build file could easily override this by either setting a different `module.version.target` in its module specific `build.properties`, or even overriding `module.version.prefix`. To get the new revision, Ivy scans the repository to find the latest available version with the given prefix, and then increments this version by 1. +This target is used to ask Ivy to find a new version for a module. To get details about the module we are dealing with, we pull information out of the Ivy file by using the ivy:info task. Then the link:../use/buildnumber.html[buildnumber] task is used to get a new revision, based on a prefix we set with a property. By default, it will be 1.0-dev-b (have a look at the default value for `module.version.target` in the `common/build.properties` file). Each module built by this common build file could easily override this by either setting a different `module.version.target` in its module specific `build.properties`, or even overriding `module.version.prefix`. To get the new revision, Ivy scans the repository to find the latest available version with the given prefix, and then increments this version by 1. === publish @@ -270,18 +273,12 @@ This target is used when you don't want to use your local version of a module an Generates both an html report and a graphml report. -For example, to generate a graph like the one shown at the beginning of this tutorial, you just have to follow the instructions given link:../yed.html[here] with the graphml file you will find in -[source] ----- -projects/console/build/ ----- - -after having called report in the console project, and that's it, you have a clear overview of all your app dependencies! +For example, to generate a graph like the one shown at the beginning of this tutorial, you just have to follow the instructions given link:../yed.html[here] with the graphml file you will find in `projects/console/build` after having called report in the console project, and that's it, you have a clear overview of all your app dependencies! == Playing with the projects -You can play with this tutorial by using regular Ant commands. Begin in the base directory of the tutorial (src/example/multi-project), and run ant -p: +You can play with this tutorial by using regular Ant commands. Begin in the base directory of the tutorial (`src/example/multi-project`), and run `ant -p`: [source,shell] ---- @@ -294,9 +291,9 @@ include::asciidoc/tutorial/log/multi-project-general-antp.txt[] This gives you an idea of what you can do here. To make sure you have at least one version of all your modules published in your repository (required to build modules having dependencies on the others), you can run `ant publish-all` (example log link:log/multi-project-general-publishall.txt[here]). -You will see that Ivy calls the publish target on all the modules, following the order of the dependencies, so that a dependee is always built and published before its depender. Feel free to make changes in the source code of a module (changing a method name for instance) and in the module using the method, then call publish-all to see how the change in the dependee is compiled first, published, and then available to the depender which can compile successfully. +You will see that Ivy calls the publish target on all the modules, following the order of the dependencies, so that a dependee is always built and published before its depender. Feel free to make changes in the source code of a module (changing a method name, for instance) and in the module using the method, then call publish-all to see how the change in the dependee is compiled first, published, and then available to the depender which can compile successfully. -Then you can go in one of the example project directories (like projects/find for instance), and run `ant -p`: +Then you can go in one of the example project directories (like `projects/find` for instance), and run `ant -p`: [source,shell] ---- @@ -307,6 +304,6 @@ include::asciidoc/tutorial/log/multi-project-find-antp.txt[] -You can see the targets available, thanks to the import of the `common.xml` build file. Play with the project by calling resolve, and publish, and see what happens when you do the same in other projects. An interesting thing to do for instance, is to change the dependencies of a project. If the module version now depends on a new commons library, you will see that all other projects depending on that version will get this library as part of their transitive dependencies once the new revision of the version project is published. Very easy! And if a project introduces a change with which the depender isn't compatible with yet, you can easily change the dependency in the depender to move from `latest.integration` to a fixed version with which the depender is compatible (probably the latest before the change). Keeping your modules under control is now very easy! +You can see the targets available, thanks to the import of the `common.xml` build file. Play with the project by calling resolve, and publish, and see what happens when you do the same in other projects. An interesting thing to do, for instance, is to change the dependencies of a project. If the module version now depends on a new commons library, you will see that all other projects depending on that version will get this library as part of their transitive dependencies once the new revision of the version project is published. Very easy! And if a project introduces a change with which the depender isn't compatible yet, you can easily change the dependency in the depender to move from `latest.integration` to a fixed version with which the depender is compatible (probably the latest before the change). Keeping your modules under control is now very easy! -By now, you should be pretty familiar with multi-project development with Ivy. We hope you will appreciate its power and flexibility! And these tutorials are only the beginning of your journey with Ivy, browse the link:../reference.html[reference documentation] to learn more about the features, subscribe to the mailing lists to share your experience and ask questions with the community, browse the source code, open jira issues, submit patches, join in and help make Ivy the best of dependency management tools! +By now, you should be pretty familiar with multi-project development with Ivy. We hope you will appreciate its power and flexibility! And these tutorials are only the beginning of your journey with Ivy, browse the link:../reference.html[reference documentation] to learn more about the features, subscribe to the mailing lists to share your experience and ask questions with the community, browse the source code, open Jira issues, submit patches, join in and help make Ivy the best of dependency management tools! http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/tutorial/start.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/tutorial/start.adoc b/asciidoc/tutorial/start.adoc index 8fc1e94..a8a0325 100644 --- a/asciidoc/tutorial/start.adoc +++ b/asciidoc/tutorial/start.adoc @@ -21,13 +21,12 @@ 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._ +_You'll find this tutorial's sources in the Ivy distribution in the src/example/hello-ivy directory._ == The ivy.xml file -This file is used to describe the dependencies of the project on other libraries. -Here is the sample: +This file describes the dependencies of the project on other libraries. Here is the sample: [source, xml] ---- @@ -42,9 +41,9 @@ 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 be pretty easy to understand, but let's discuss some details about what is declared here. First, the root element is `ivy-module`, with the `version` attribute telling Ivy which lowest version of Ivy this file is compatible with. -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 provides information about the module for which we are defining dependencies. Here we define only the `organization` and `module` names. 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. 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. @@ -66,7 +65,7 @@ If you want more details on what you can do in Ivy files, you can have a look at == 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` command 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, xml] ---- @@ -85,7 +84,7 @@ You can use the standard `ant -p` to get the list of available targets. Feel fre ---- -As you can see, it's very easy to call Ivy to resolve and retrieve dependencies: all you need if Ivy is properly link:../install.html[installed] is to define an XML namespace in your Ant file (xmlns:ivy="antlib:org.apache.ivy.ant"). Then all the link:../ant.html[Ivy ant tasks] will be available in this namespace. +As you can see, it's very easy to call Ivy to resolve and retrieve dependencies: all you need if Ivy is properly link:../install.html[installed] is to define an XML namespace in your Ant file (xmlns:ivy="antlib:org.apache.ivy.ant"`). Then all the link:../ant.html[Ivy Ant tasks] will be available in this namespace. Here we use only one task: the link:../use/retrieve.html[retrieve] task. With no attributes, it will use default settings and look for a file named `ivy.xml` for the dependency definitions. That's exactly what we want, so we need nothing more than that. @@ -108,7 +107,7 @@ 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 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). +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 +123,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 other tutorials to learn more about link:../tutorial/conf.html[how to use module configurations] which is a very powerful Ivy specific feature. More 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. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/use/artifactproperty.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/use/artifactproperty.adoc b/asciidoc/use/artifactproperty.adoc index dd24317..6089f1f 100644 --- a/asciidoc/use/artifactproperty.adoc +++ b/asciidoc/use/artifactproperty.adoc @@ -18,15 +18,15 @@ //// *__since 1.1__* -Sets an Ant property for each dependency artifacts previously resolved. +Sets an Ant property for each dependency artifact previously resolved. *__since 2.0__* This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks. -Please prefer the use of retrieve + standard ant path creation, which make your build more independent from Ivy (once artifacts are properly retrieved, Ivy is not required any more). +Please prefer the use of retrieve + standard Ant path creation, which make your build more independent from Ivy (once artifacts are properly retrieved, Ivy is not required any more). The property name and value are generated using the classical pattern concept, all artifact tokens and Ivy variables being available. -*__since 2.0__* This tag will follow the ant usual behavior for properties. If a property of the same name already exist, it's value will be unchanged. This behavior can be changed using the `overwrite` attribute. +*__since 2.0__* This tag will follow the Ant usual behavior for properties. If a property with the same name already exists, its value will be unchanged. This behavior can be changed using the `overwrite` attribute. _WARNING_: Before 2.0, the behavior was to overwrite the properties. Since 2.0, the default is to not overwrite to properties @@ -38,10 +38,10 @@ _WARNING_: Before 2.0, the behavior was to overwrite the properties. Since 2.0, |name|a pattern used to generate the name of the properties to set|Yes |value|a pattern used to generate the value of the properties to set|Yes |conf|a comma separated list of the configurations for which properties should be set|No. Defaults to the configurations resolved by the last resolve call, or `$$*$$` if no resolve was explicitly called -|haltonfailure|`true` to halt the build on ivy failure, `false` to continue|No. Defaults to `true` -|validate|`true` to force ivy files validation against ivy.xsd, `false` to force no validation|No. Defaults to default ivy value (as configured in configuration file) -|settingsRef|A reference to the ivy settings that must be used by this task *(since 2.0)*|No, `ivy.instance` is taken by default. -|overwrite|Overwrite the value of the property if it already exist *(since 2.0)*. Before 2.0, the properties were always overwritten.|No, `false` by default. +|haltonfailure|`true` to halt the build on Ivy failure, `false` to continue|No. Defaults to `true` +|validate|`true` to force validation of Ivy files against ivy.xsd, `false` to skip validation|No. Defaults to default Ivy value (as configured in settings file) +|settingsRef|A reference to Ivy settings that must be used by this task *(since 2.0)*|No, `ivy.instance` is taken by default. +|overwrite|Overwrite the value of the property if it already exists *(since 2.0)*. Before 2.0, the properties were always overwritten.|No, `false` by default. |======= == Example http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/use/artifactreport.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/use/artifactreport.adoc b/asciidoc/use/artifactreport.adoc index 64048d8..7caf294 100644 --- a/asciidoc/use/artifactreport.adoc +++ b/asciidoc/use/artifactreport.adoc @@ -18,7 +18,7 @@ //// *__since 1.4__* -The `artifactreport` task generates an xml report of all artifacts dependencies resolved by the last link:../use/resolve.html[resolve] task call during the same build. +The `artifactreport` task generates an XML report of all artifact dependencies resolved by the last link:../use/resolve.html[resolve] task call during the same build. *__since 2.0__* This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks. @@ -28,7 +28,7 @@ It is thus easy to use to generate things like a classpath file for an IDE. See this link:http://www.jaya.free.fr/ivy/doc/articles/ease-multi-module.html[article by Johan Stuyts] (who contributed this task) to see how he uses this task. -Here is an example of generate file: +Here is an example of generated file: [source,xml] ---- @@ -66,10 +66,10 @@ Here is an example of generate file: |======= |Attribute|Description|Required |tofile|the file to which the report should be written|Yes -|pattern|the retrieve pattern to use to fill the retrieve location information about the artifacts|No. Defaults to `${ivy.retrieve.pattern}`. +|pattern|the retrieve pattern to use for adding the retrieve location information about the artifacts|No. Defaults to `${ivy.retrieve.pattern}`. |conf|a comma separated list of the configurations to use to generate the report|No. Defaults to the configurations resolved by the last resolve call -|haltonfailure|`true` to halt the build on ivy failure, `false` to continue|No. Defaults to `true` -|settingsRef|A reference to the ivy settings that must be used by this task *(since 2.0)*|No, `ivy.instance` is taken by default. +|haltonfailure|`true` to halt the build on Ivy failure, `false` to continue|No. Defaults to `true` +|settingsRef|A reference to Ivy settings that must be used by this task *(since 2.0)*|No, `ivy.instance` is taken by default. |======= == Examples http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/use/buildlist.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/use/buildlist.adoc b/asciidoc/use/buildlist.adoc index 45f47ab..96d1332 100644 --- a/asciidoc/use/buildlist.adoc +++ b/asciidoc/use/buildlist.adoc @@ -17,27 +17,27 @@ under the License. //// -The `buildlist` task enable to obtain a `filelist` of files (usually `build.xml` files) ordered according to Ivy dependency information from the least dependent to the most one, or the inverse. (*__since 1.2__*) +The `buildlist` task enables to obtain a `filelist` of files (usually `build.xml` files) ordered according to Ivy dependency information from the least dependent to the most one, or the inverse. (*__since 1.2__*) This is particularly useful combined with `subant`, to build a set of interrelated projects being sure that a dependency will be built before any module depending on it. -When the `ivy.xml` of the modules that you want to order doesn't contains a link:../ivyfile/info.html[revision] numbers, the `rev` attributes declared in the dependency is not used. -When the `ivy.xml` of the modules that you want to order contains a link:../ivyfile/info.html[revision] numbers, the revision numbers are used. If the revision number doesn't match a dependency description a warning is logged and the modules is considered as different modules. +When the `ivy.xml` of the modules that you want to order doesn't contain link:../ivyfile/info.html[revision] numbers, the `rev` attributes declared in the dependencies are not used. +When the `ivy.xml` of the modules that you want to order contains link:../ivyfile/info.html[revision] numbers, the revision numbers are used. If the revision number doesn't match a dependency description, a warning is logged and the modules are considered to be different modules. -*__since 1.3__* A `root` attribute can also be used to include, among all the modules found, only the one that are dependencies (either direct or transitive) of a root module. This can also be used with the `excluderoot` attribute, which when set to `true` will exclude the root itself from the list. +*__since 1.3__* A `root` attribute can also be used to include, among all the modules found, only the ones that are dependencies (either direct or transitive) of a root module. This can also be used with the `excluderoot` attribute, which when set to `true` will exclude the root itself from the list. -*__since 1.4.1__* A `leaf` attribute can also be used to include, among all the modules found, only the one that have dependencies (either direct or transitive) on a leaf module. This can also be used with the `excludeleaf` attribute, which when set to `true` will exclude the leaf itself from the list. +*__since 1.4.1__* A `leaf` attribute can also be used to include, among all the modules found, only the ones that have dependencies (either direct or transitive) on a leaf module. This can also be used with the `excludeleaf` attribute, which when set to `true` will exclude the leaf itself from the list. -*__since 1.4__* The `ivy.sorted.modules` property is set in the ant at the end of the task with a comma separated list of ordered modules. This can be useful for debug or information purpose. +*__since 1.4__* The `ivy.sorted.modules` property is set in Ant project at the end of the task with a comma separated list of ordered modules. This can be useful for debug or information purpose. *__since 2.0__* The `root` and `leaf` attributes can be a delimited list of modules to use as roots. These modules, and all their dependencies will be included in the build list. -*__since 2.0__* By default, all the modules included in a circular dependency are grouped together so that any dependency of any module in the loop will appear before the modules in the loop. This guarantee that if there is a dependency path between a module A and a module B (but no dependency path from B to A), B will always appear before A even if A is included in a loop in the provided set of modules to sort. -Note that circular dependency can also trigger a failure depending on the value configured in the `circularDependencyStrategy` of your link:../settings/conf.html#circularDependencyStrategy[settings] +*__since 2.0__* By default, all the modules included in a circular dependency are grouped together so that any dependency of any module in the loop will appear before the modules in the loop. This guarantees that if there is a dependency path between a module A and a module B (but no dependency path from B to A), B will always appear before A even if A is included in a loop in the provided set of modules to sort. +Note that a circular dependency can also trigger a failure depending on the value configured in the `circularDependencyStrategy` of your link:../settings/conf.html#circularDependencyStrategy[settings] -*__since 2.0__* When you are specifying `root` or `leaf` modules you can limit the resulting list to only direct dependencies of the roots modules or to modules that directly depends on your leaf modules. +*__since 2.0__* When you are specifying `root` or `leaf` modules you can limit the resulting list to only direct dependencies of the root modules or to modules that directly depends on your leaf modules. -*__since 2.0__* You can also specify a `restartFrom` modules. The difference with `root` or `leaf`, is that you get a list starting at the `restartFrom` module followed by all the modules that would be after if the parameter would not be there (even if there is no dependency between the `restartFrom` and the following module). +*__since 2.0__* You can also specify a `restartFrom` modules. The difference with `root` or `leaf` is that you get a list starting at the `restartFrom` module followed by all the modules that would be after if the parameter would not be there (even if there is no dependency between the `restartFrom` and the following module). == Attributes @@ -45,7 +45,7 @@ Note that circular dependency can also trigger a failure depending on the value |======= |Attribute|Description|Required |reference|the reference of the path to set|Yes -|ivyfilepath|the relative path from files to order to corresponding ivy files|No. Defaults to `${ivy.buildlist.ivyfilepath}` +|ivyfilepath|the relative path from files to order to corresponding Ivy files|No. Defaults to `${ivy.buildlist.ivyfilepath}` |root|*__since 2.0__* the names of the modules which should be considered as the root of the buildlist. *__since 1.3__* Was limited to only one module name before 2.0.|No. Defaults to no root (all modules are used in the build list) @@ -55,12 +55,12 @@ Note that circular dependency can also trigger a failure depending on the value |onlydirectdep|*__since 2.0__* `true` if the resulting list should be restricted to direct dependencies of root modules or modules that directly depends on the leaf modules. -This field is ignored when neither root neither leaf is filled. +This field is ignored when neither root nor leaf is filled. |No. Defaults to no `false` |delimiter|*__since 2.0__* delimiter to use when specifying multiple module names in the root and leaf properties.|No. Defaults to the comma (`,`) character. |excludeleaf|*__since 1.4.1__* `true` if the leaf defined should be excluded from the list|No. Defaults to `false` -|haltonerror|`true` to halt the build when an invalid ivy file is encountered, false to continue|No. Defaults to `true` -|skipbuildwithoutivy|Deprecated, use `onMissingDescriptor` instead. `true` to skip files of the fileset with no corresponding ivy file, `false` otherwise. If `false` the file with no corresponding ivy file will be considered as independent of the other and put at the beginning of the built filelist.|No. Defaults to `false` +|haltonerror|`true` to halt the build when an invalid Ivy file is encountered, false to continue|No. Defaults to `true` +|skipbuildwithoutivy|__Deprecated, use `onMissingDescriptor` instead.__ `true` to skip files of the fileset with no corresponding Ivy file, `false` otherwise. If `false` the file with no corresponding Ivy file will be considered as independent of the other and put at the beginning of the built filelist.|No. Defaults to `false` |onMissingDescriptor|*__since 2.0__* Specify the action to take when no module descriptor file is found for a file of the fileset. Possible values are: + * `head`: put at the head of the built filelist. + * `tail`: put at the tail of the built filelist. + @@ -71,7 +71,7 @@ This field is ignored when neither root neither leaf is filled. |reverse|`true` to obtain the list in the reverse order, i.e. from the most dependent to the least one|No. Defaults to default `false` |restartFrom|*__since 2.0__* The name of the module which should be considered as the starting point in the buildlist. This allows for the build to be started at any point in the dependency chain. |No. Defaults to `*` meaning no restart point (all modules are used in the build list). -|settingsRef|*__since 2.0__* A reference to the ivy settings that must be used by this task|No, `ivy.instance` is taken by default. +|settingsRef|*__since 2.0__* A reference to Ivy settings that must be used by this task|No, `ivy.instance` is taken by default. |======= == Parameters specified as nested elements @@ -107,7 +107,7 @@ This list can then be used like that: </ivy:buildlist> ---- -Builds a list of `build.xml` files sorted according to the `ivy.xml` files found in an ivy directory relative to those build files. The list is sorted from the most dependent to the least one. +Builds a list of `build.xml` files sorted according to the `ivy.xml` files found in an Ivy directory relative to those build files. The list is sorted from the most dependent to the least one. ''' @@ -118,7 +118,7 @@ Builds a list of `build.xml` files sorted according to the `ivy.xml` files found </ivy:buildlist> ---- -Builds a list of `build.xml` files sorted according to the `ivy.xml` files found in an ivy directory relative to those build files. Only `build.xml` files of modules which are dependencies of `myapp` (either direct or transitive) are put in the result list. +Builds a list of `build.xml` files sorted according to the `ivy.xml` files found in an Ivy directory relative to those build files. Only `build.xml` files of modules which are dependencies of `myapp` (either direct or transitive) are put in the result list. ''' @@ -129,4 +129,4 @@ Builds a list of `build.xml` files sorted according to the `ivy.xml` files found </ivy:buildlist> ---- -Builds a list of `build.xml` files sorted according to the `ivy.xml` files found in an ivy directory relative to those build files. Only `build.xml` files of modules which have dependencies (direct or transitive) on `mymodule` are put in the result list. +Builds a list of `build.xml` files sorted according to the `ivy.xml` files found in an Ivy directory relative to those build files. Only `build.xml` files of modules which have dependencies (direct or transitive) on `mymodule` are put in the result list. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/use/buildnumber.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/use/buildnumber.adoc b/asciidoc/use/buildnumber.adoc index 6560f9e..1153a47 100644 --- a/asciidoc/use/buildnumber.adoc +++ b/asciidoc/use/buildnumber.adoc @@ -20,7 +20,7 @@ *__since 1.4__* The `buildnumber` task is similar to the Ant `buildnumber` task, except that it uses Ivy repository to find what is the latest version and calculate a new one for you. -When called it sets four properties according to what has been found. These properties are: +When called, it sets four properties according to what has been found. These properties are: * `ivy.revision`: the last revision found in the repository * `ivy.new.revision`: the new revision calculated from the last one (see below) @@ -33,7 +33,7 @@ Build numbers are always numbers (composed of digit characters only). `ivy.build.number` can be not set if no revision was found or if no number was found in it. -`ivy.new.build.number` can be not set if the default new revision to use when no revision is found do not contain any number. +`ivy.new.build.number` can be not set if the default new revision to use when no revision is found does not contain some number. The new revision is calculated using a somewhat complex to explain but very easy to use algorithm, depending on which latest version you asked. @@ -50,7 +50,7 @@ Examples (suppose the latest version of the module is 1.3.1): ||1.3.1|1.3.2|1|2 |======= -Note that when asking for revision 1, you can get a revision 10.0. To avoid that you can use 1. as revision asked, but in this case ivy won't find revision 1 if its the latest one, and it will thus give 1.0 as new revision. The solution to this problem is to use versions with always the same number of parts (for instance 1.0.0 instead of 1). +Note that when asking for revision 1, you can get a revision 10.0. To avoid that you can use 1. as revision asked, but in this case Ivy won't find revision 1 if its the latest one, and it will thus give 1.0 as new revision. The solution to this problem is to use versions with always the same number of parts (for instance, 1.0.0 instead of 1). == Attributes @@ -65,13 +65,13 @@ Note that when asking for revision 1, you can get a revision 10.0. To avoid that |defaultBuildNumber|the default build number to use for the first revision|No, defaults to 0 |revSep|the revision separator to use when no matching revision is found, to separate the revision prefix from the build number|No, defaults to `.` |prefix|the prefix to use for the property names set (will be `__prefix__.revision, __prefix__.new.revision, ...)|No, defaults to `ivy` -|settingsRef|A reference to the ivy settings that must be used by this task *__(since 2.0)__*.|No, `ivy.instance` is taken by default. +|settingsRef|A reference to Ivy settings that must be used by this task *__(since 2.0)__*.|No, `ivy.instance` is taken by default. |resolver|the name of the resolver to use for build number calculation *__(since 2.1)__*|No, all available resolvers will be used by default. |======= == Examples -Here is how it can be used (suppose 1.3.1 is the latest version of ivy in the repository): +Here is how it can be used (suppose 1.3.1 is the latest version of Ivy in the repository): [source,xml] ---- http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/use/buildobr.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/use/buildobr.adoc b/asciidoc/use/buildobr.adoc index cdc0fd5..ac39557 100644 --- a/asciidoc/use/buildobr.adoc +++ b/asciidoc/use/buildobr.adoc @@ -19,14 +19,14 @@ *__since 2.3__* From a set of jar artifacts, this task generates an OBR (OSGi Bundle Repository) descriptor. It could be then used by the link:../resolver/obr.html[obr resolver]. -The set of jars which will be described by the OBR can be defined in 4 exclusive ways: +The set of jars which will be described by OBR can be defined in 4 mutually exclusive ways: * via an Ivy resolver: every jar listed by the resolver will be taken into account * by defining a root directory: every jar found recursively in that folder will be taken into account * via the name of an Ivy cache: every artifact contained in the cache will be taken into account -* *__since 2.4__* via a resolve: this task is a link:../use/postresolvetask.html[post resolve task] (with all the behaviour and attributes common to all post resolve tasks), thus ever artifact which has been resolved will be taken into account; it is especially useful for building a link:../osgi/target-platform.html[target platform] +* *__since 2.4__* via a resolve: this task is a link:../use/postresolvetask.html[post resolve task] (with all the behaviour and attributes common to all post resolve tasks), thus every artifact which has been resolved will be taken into account; it is especially useful for building a link:../osgi/target-platform.html[target platform] -NB: among every listed files or artifacts, only the actually OSGi bundles will be described by the OBR descriptor; the other files are ignored. +NB: among every listed file or artifact, only the actually OSGi bundles will be described by the OBR descriptor; the other files are ignored. == Attributes @@ -38,11 +38,11 @@ NB: among every listed files or artifacts, only the actually OSGi bundles will b |out|the location of the descriptor file to generate|Yes |resolverName|the name of the resolver from which the jars should be to gathered|No |cacheName|the name of the cache from which the jars should be to gathered|No -|baseDir|the folder into which the jars should be gather recursively|No -|sourceType|if used as a post resolve task, `sourceType` define the type of artifacts which should be considered as source artifacts|No. Defaults to `source,sources,src` -|encoding|The encoding of the resulting xml file|No. Defaults to `UTF-8` -|indent|Specify if the xml result file should be indented|No. Defaults to `true` -|quiet|Log as debug rather than warning the rejected jars as they are ill-formed|No. Defaults to `false` +|baseDir|the folder into which the jars should be gathered recursively|No +|sourceType|if used as a post resolve task, `sourceType` defines the type of artifacts which should be considered as source artifacts|No. Defaults to `source,sources,src` +|encoding|The encoding of the resulting XML file|No. Defaults to `UTF-8` +|indent|Specify if the XML result file should be indented|No. Defaults to `true` +|quiet|Log the rejected jars that are ill-formed as debug rather than warning|No. Defaults to `false` |======= == Examples @@ -62,7 +62,7 @@ Builds an indented OBR descriptor from an Eclipse install, with their path relat <ivy:buildobr resolverName="my-file-resolver" out="${basedir}/target/repo-eclipse.xml"/> ---- -Configure an Ivy settings and builds an OBR descriptor from jars resolved by the defined resolver. +Configures Ivy settings and builds an OBR descriptor from jars resolved by the defined resolver. ''' @@ -72,7 +72,7 @@ Configure an Ivy settings and builds an OBR descriptor from jars resolved by the <ivy:buildobr cacheName="my-cache" out="${basedir}/target/repo-eclipse.xml"/> ---- -Configure an Ivy settings and builds an OBR descriptor from jars contained in the defined cache. +Configures Ivy settings and builds an OBR descriptor from jars contained in the defined cache. ''' @@ -83,4 +83,4 @@ Configure an Ivy settings and builds an OBR descriptor from jars contained in th <ivy:buildobr out="${basedir}/target-platform-obr.xml"/> ---- -Launch a resolve and then build an obr.xml describing the resolved artifacts. +Launches a resolve and then builds an obr.xml describing the resolved artifacts. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/use/cachefileset.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/use/cachefileset.adoc b/asciidoc/use/cachefileset.adoc index 0e5b0af..654d717 100644 --- a/asciidoc/use/cachefileset.adoc +++ b/asciidoc/use/cachefileset.adoc @@ -17,20 +17,20 @@ under the License. //// -Constructs an Ant `fileset consisting` of artifacts in Ivy's cache for a configuration (*__since 1.2__*). +Constructs an Ant `fileset` consisting of artifacts in Ivy's cache for a configuration (*__since 1.2__*). This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks. Note that this task -does not rely on retrieve, because built fileset is made of artifacts directly in Ivy's cache. +does not rely on retrieve, because the built fileset is made of artifacts directly in Ivy's cache. -Please prefer the use of retrieve + standard ant path creation, which make your build +Please prefer the use of retrieve + standard Ant path creation, which make your build more independent from Ivy (once artifacts are properly retrieved, Ivy is not required any more). -Built `fileset` is registered in Ant with a given id, and can thus be used like any other Ant `fileset` using +Built `fileset` is registered in Ant project with a given id, and can thus be used like any other Ant `fileset` using `refid`. == Limitation -A `fileset`, in Ant, requires a base directory from within which the files are included/excluded. The `cachefileset` task, in Ivy, internally tries to determine a common base directory across all the resolved artifacts' files that have been downloaded in the Ivy repository cache(s). Given that Ivy can be configured to consist multiple repository caches and each one can potentially be on a different filesystem root, there are times, when `cachefileset` cannot determine a common base directory for these resolved artifacts. The `cachefileset` throws an exception in such cases. +A `fileset`, in Ant project, requires a base directory from within which the files are included/excluded. The `cachefileset` task, in Ivy, internally tries to determine a common base directory across all the resolved artifact files that have been downloaded in the Ivy repository cache(s). Given that Ivy can be configured to use multiple repository caches and each one can potentially be on a different filesystem root, there are times, when `cachefileset` cannot determine a common base directory for these resolved artifacts. The `cachefileset` throws an exception in such cases. == Alternative task @@ -44,5 +44,5 @@ If `cachefileset` doesn't fit the need of your use case (maybe due to the limita |setid|the id to reference the built fileset|Yes |conf|a comma separated list of the configurations to put in the created path|No. Defaults to the configurations resolved by the last resolve call, or `*` if no resolve was explicitly called |type|comma separated list of artifact types to accept in the path, `*` for all|No. Defaults to `*` -|settingsRef|*__(since 2.0)__* A reference to the ivy settings that must be used by this task|No, `ivy.instance` is taken by default. +|settingsRef|*__(since 2.0)__* A reference to Ivy settings that must be used by this task|No, `ivy.instance` is taken by default. |=======
