You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by hi...@apache.org on 2017/07/04 20:53:15 UTC
[1/2] ant-ivy git commit: review the doc about the "Introduction" and
the part for the dev
Repository: ant-ivy
Updated Branches:
refs/heads/master c87126545 -> cd8f81d0a
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/terminology.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/terminology.adoc b/asciidoc/terminology.adoc
index f5cee6f..1e009c4 100644
--- a/asciidoc/terminology.adoc
+++ b/asciidoc/terminology.adoc
@@ -19,58 +19,38 @@
Here are some terms used in Ivy, with their definitions in Ivy:
-
-* link:#organisation[Organisation] +
-
-* link:#module[Module] +
-
-* link:#descriptor[Module Descriptor] +
-
-* link:#artifact[Artifact] +
-
-* link:#type[Type of an artifact] +
-
-* link:#extension[Artifact file name extension] +
-
-* link:#revision[Module Revision] +
-
-* link:#branch[Branch] +
-
-* link:#status[Status of a revision] +
-
-* link:#configurations[Configurations of a module] +
-
-* link:#settings[Ivy Settings] +
-
-* link:#repository[Repository] +
-
-
+* link:#organisation[Organisation]
+* link:#module[Module]
+* link:#descriptor[Module Descriptor]
+* link:#artifact[Artifact]
+* link:#type[Type of an artifact]
+* link:#extension[Artifact file name extension]
+* link:#revision[Module Revision]
+* link:#branch[Branch]
+* link:#status[Status of a revision]
+* link:#configurations[Configurations of a module]
+* link:#settings[Ivy Settings]
+* link:#repository[Repository]
== Overview
The following [[illustration]]illustration shows all the key terminology in one diagram:
-
-
image::images/ivy-terminology.png[]
-
-
-
== [[organisation]]Organisation
-An organisation is either a company, an individual, or simply any group of people that produces software. In principle, Ivy handles only a single level of organisation, meaning that they have a flat namespace in Ivy module descriptors. So, with Ivy descriptors, you can only describe a tree-like organisation structure, if you use a hierarchical naming convention. The organisation name is used for keeping together software produced by the same team, just to help locate their published works.
+An `organisation` is either a company, an individual, or simply any group of people that produces software. In principle, Ivy handles only a single level of organisation, meaning that they have a flat namespace in Ivy module descriptors. So, with Ivy descriptors, you can only describe a tree-like organisation structure, if you use a hierarchical naming convention. The organisation name is used for keeping together software produced by the same team, just to help locate their published works.
Often organisations will use their inverted domain name as their organisation name in Ivy, since domain names by definition are unique. A company whose domain name is www.example.com might want to use com.example, or if they had multiple teams, all their organisation names could begin with com.example (e.g. com.example.rd, com.example.infra, com.example.services). The organisation name does neither really have to be an inverted domain name, nor even globally unique, but unique naming is highly recommended. Widely recognized trademark or trade name owners may choose to use their brand name instead.
__Examples: org.apache, ibm, jayasoft__
-Note that the Ivy "organisation" is very similar to Maven POM "groupId".
-</dd>
+Note that the Ivy `organisation` is very similar to Maven POM `groupId`.
== [[module]]Module
-A module is a self-contained, reusable unit of software that, as a whole unit, follows a revision control scheme.
+A `module` is a self-contained, reusable unit of software that, as a whole unit, follows a revision control scheme.
Ivy is only concerned about the module deliverables known as _artifacts_, and the _module descriptor_ that declares them. These deliverables, for each _revision_ of the module, are managed in _repositories_. In other words, to Ivy, a module is a chain of revisions each comprising a descriptor and one or more artifacts.
@@ -88,7 +68,7 @@ And because Ivy accepts pluggable module descriptor parsers, you can use almost
== [[artifact]]Artifact
-An artifact is _a single file_ ready for delivery with the publication of a module revision, as a product of development.
+An `artifact` is _a single file_ ready for delivery with the publication of a module revision, as a product of development.
Compressed package formats are often preferred because they are easier to manage, transfer and store. For the same reasons, only one or a few artifacts per module are commonly used. However, artifacts can be of any file type and any number of them can be declared in a single module.
@@ -98,7 +78,7 @@ __Examples: ant-1.7.0-bin.zip, apache-ant-1.7.0-src.tar.gz __
=== [[type]]Type of an artifact
-The artifact type is a category of a particular kind of artifact specimen. It is a classification based on the intended purpose of an artifact or _why_ it is provided, not a category of packaging format or _how_ the artifact is delivered.
+The artifact `type` is a category of a particular kind of artifact specimen. It is a classification based on the intended purpose of an artifact or _why_ it is provided, not a category of packaging format or _how_ the artifact is delivered.
Although the type of an artifact may (rather accidentally) imply its file format, they are two different concepts. The artifact file name extension is more closely associated with its format. For example, in the case of Java archives the artifact type "jar" indicates that it is indeed a Java archive as per the JAR File specification. The file name extension happens to be "jar" as well. On the other hand, with source code distributions, the artifact type may be "source" while the file name extensions vary from "tar.gz", "zip", "java", "c", or "xml" to pretty much anything. So, the type of an artifact is basically an abstract functional category to explain its purpose, while the artifact file name extension is a more concrete technical indication of its format and, of course, naming.
@@ -116,7 +96,6 @@ __Examples: zip, tar, tar.gz, rar, jar, war, ear, txt, doc, xml, html__
== Module [[revision]]Revision and Status
-
=== Module revision
A unique revision number or version name is assigned to each delivered unique state of a module. Ivy can help in generating revision numbers for module delivery and publishing revisions to repositories, but other aspects of revision control, especially source revisioning, must be managed with a separate version control system.
@@ -140,12 +119,14 @@ A module's status indicates how stable a module revision can be considered. It c
Three statuses are defined by default in Ivy:
+`integration`::
+revisions built by a continuous build, a nightly build, and so on, fall in this category
-* *integration*: revisions built by a continuous build, a nightly build, and so on, fall in this category +
-
-* *milestone*: revisions delivered to the public but not actually finished fall in this category +
+`milestone`::
+revisions delivered to the public but not actually finished fall in this category
-* *release*: a revision fully tested and labelled fall in this category +
+`release`::
+a revision fully tested and labelled fall in this category
*__Since 1.4__* This list is link:settings/statuses.html[configurable] in your settings file.
@@ -162,12 +143,12 @@ For more details on configurations and how they are used in ivy, please refer to
Ivy settings files are xml files used to configure ivy to indicate where the modules can be found and how.
-=== __History of settings__
-
-__Prior to Ivy 2.0, the settings files were called configuration files and usually named ivyconf.xml. This resulted in confusion between module configurations and Ivy configuration files, so they were renamed to settings files. If you happen to fall on an ivyconf file or something called a configuration file, most of the time it's only unupdated information (documentation, tutorial or article). Feel free to report any problem like this if you find such an inconsistency.__
+=== History of settings
+Prior to Ivy 2.0, the settings files were called configuration files and usually named ivyconf.xml. This resulted in confusion between module configurations and Ivy configuration files, so they were renamed to settings files. If you happen to fall on an ivyconf file or something called a configuration file, most of the time it's only unupdated information (documentation, tutorial or article). Feel free to report any problem like this if you find such an inconsistency.
== [[repository]]Repository
What is called a _repository_ in Ivy is a distribution site location where Ivy is able to find your required modules' artifacts and descriptors (i.e. Ivy files in most cases).
+
Ivy can be used with complex repositories configured very finely. You can use link:concept.html[Dependency Resolvers] to do so.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/textual.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/textual.adoc b/asciidoc/textual.adoc
index f9144ae..d67ddb7 100644
--- a/asciidoc/textual.adoc
+++ b/asciidoc/textual.adoc
@@ -23,110 +23,69 @@ The conventions have been adopted with Ivy 2.0 are the following:
[options="header"]
|=======
-
-|
-a module without revision
-|
-__[organisation]__#__[module]__
-|
-org.apache.ant#ant
-
-|
-a module with revision
-|
-__[organisation]__#__[module]__;__[revision]__
-|
-org.apache.ant#ant;1.7.0
-
-|
-a module with (some) configurations
-|
-__[organisation]__#__[module]__[ __[confs]__ ]
-|
-org.apache.ant#ant[master,compile,build]
-
-|
-a module with revision and (some) configurations
-|
-__[organisation]__#__[module]__;__[revision]__[ __[confs]__ ]
-|
-org.apache.ant#ant;1.7.0[master,compile,build]
-
-|
-a module's artifact
-|
-__[organisation]__#__[module]__!__[artifact]__.__[ext]__(__[type]__)
-|
-org.apache.ant#ant!ant.jar(source)
-
-|
-a module's artifact with revision
-|
-__[organisation]__#__[module]__;__[revision]__!__[artifact]__.__[ext]__(__[type]__)
-|
-org.apache.ant#ant;1.7.0!ant.jar(source)
-
+| what | pattern | exemple
+| a module without revision | `[organisation]`#`[module]` | `org.apache.ant#ant`
+| a module with revision | `[organisation]`#`[module]`$$;$$`[revision]` | `org.apache.ant#ant;1.7.0`
+| a module with (some) configurations | `[organisation]`#`[module]`[`[confs]`] | `org.apache.ant#ant[master,compile,build]`
+| a module with revision and (some) configurations
+| `[organisation]`#`[module]`$$;$$`[revision]`[`[confs]`]
+| `org.apache.ant#ant;1.7.0[master,compile,build]`
+| a module's artifact
+| `[organisation]`#`[module]`!`[artifact]`.`[ext]`(`[type]`)
+| `org.apache.ant#ant!ant.jar(source)`
+| a module's artifact with revision
+| `[organisation]`#`[module]`$$;$$`[revision]`!`[artifact]`.`[ext]`(`[type]`)
+| `org.apache.ant#ant;1.7.0!ant.jar(source)`
|=======
+Another usual text representation used is to represent dependencies using a dash followed by greater than sign: `$$->$$`
-
-Another usual text representation used is to represent dependencies using a dash followed by greater than sign: ->
-
-To group a set of set of modules, we recommend using curly braces { }
+To group a set of set of modules, we recommend using curly braces `{` `}`.
With these conventions, it's easy to give a concise and detailed overview of a set of modules and their dependencies.
For instance:
-
[source]
----
-
#A;2-> { #B;[1.0,1.5] #C;[2.0,2.5] }
#B;1.4->#D;1.5
#B;1.5->#D;2.0
#C;2.5->#D;[1.0,1.6]
-
----
-
In full words here is how it could be written:
[source]
----
-
module A revision 2 depends on module B with the version constraint [1.0,1.5], and on module C with the version constraint [2.0,2.5].
module B revision 1.4 depends on module D revision 1.5.
module B revision 1.5 depends on module D revision 2.0.
module C revision 2.5 depends on module D with the version constraint [1.0,1.6].
-
----
-
-
As you can see, using text conventions is much more concise.
Another benefit is that these conventions are usually used in Ivy console output, and can also be used in some cases to be parsed into Ivy objects (we use it for test cases for instance). To make sure text parsing works fine, we recommend using only a limited range of characters for each attributes of your module identifiers.
Here is the recommended characters set for each attribute:
+`organisation`::
+`a-z` `A-Z` `0-9` `-` `/` `.` `_` `+` `=`
-* organisation +
- a-z A-Z 0-9 - / . _ + =
-
-* module +
- a-z A-Z 0-9 - / . _ + =
+`module`::
+`a-z` `A-Z` `0-9` `-` `/` `.` `_` `+` `=`
-* branch +
- a-z A-Z 0-9 - / . _ + =
+`branch`::
+`a-z` `A-Z` `0-9` `-` `/` `.` `_` `+` `=`
-* revision +
- a-z A-Z 0-9 - / . _ + = , [ ] { } ( ) : @
+`revision`::
+`a-z` `A-Z` `0-9` `-` `/` `.` `_` `+` `=` `,` `[` `]` `{` `}` `(` `)` `:` `@`
-* artifact +
- a-z A-Z 0-9 - / . _ + =
+`artifact`::
+`a-z` `A-Z` `0-9` `-` `/` `.` `_` `+` `=`
-* extension +
- a-z A-Z 0-9 - / . _ + =
+`extension`::
+`a-z` `A-Z` `0-9` `-` `/` `.` `_` `+` `=`
-* type +
- a-z A-Z 0-9 - / . _ + =
+`type`::
+`a-z` `A-Z` `0-9` `-` `/` `.` `_` `+` `=`
[2/2] ant-ivy git commit: review the doc about the "Introduction" and
the part for the dev
Posted by hi...@apache.org.
review the doc about the "Introduction" and the part for the dev
Project: http://git-wip-us.apache.org/repos/asf/ant-ivy/repo
Commit: http://git-wip-us.apache.org/repos/asf/ant-ivy/commit/cd8f81d0
Tree: http://git-wip-us.apache.org/repos/asf/ant-ivy/tree/cd8f81d0
Diff: http://git-wip-us.apache.org/repos/asf/ant-ivy/diff/cd8f81d0
Branch: refs/heads/master
Commit: cd8f81d0a0eac318bba39f8e8b409a5f1fb636bb
Parents: c871265
Author: Nicolas Lalevée <ni...@hibnet.org>
Authored: Tue Jul 4 22:53:03 2017 +0200
Committer: Nicolas Lalevée <ni...@hibnet.org>
Committed: Tue Jul 4 22:53:03 2017 +0200
----------------------------------------------------------------------
asciidoc/bestpractices.adoc | 58 +++--
asciidoc/compatibility.adoc | 9 +-
asciidoc/concept.adoc | 211 +++++++-----------
asciidoc/dev.adoc | 31 +--
asciidoc/dev/makerelease.adoc | 122 +++--------
asciidoc/extend.adoc | 30 +--
asciidoc/index.adoc | 22 +-
asciidoc/install.adoc | 20 +-
asciidoc/principle.adoc | 6 +-
asciidoc/reference.adoc | 42 ++--
asciidoc/release-notes.adoc | 439 ++++++++++++-------------------------
asciidoc/standalone.adoc | 42 +---
asciidoc/style/style.css | 24 +-
asciidoc/terminology.adoc | 71 +++---
asciidoc/textual.adoc | 99 +++------
15 files changed, 410 insertions(+), 816 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/bestpractices.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/bestpractices.adoc b/asciidoc/bestpractices.adoc
index 6d7c9fc..ef86a02 100644
--- a/asciidoc/bestpractices.adoc
+++ b/asciidoc/bestpractices.adoc
@@ -19,7 +19,6 @@
Here are some recommendations and best practices we have gathered throughout our experience and consultancies with our customers.
-
== Add module descriptors for all your modules
In Ivy world, module descriptors are ivy files, which are basically simple xml files describing both what the module produces as artifacts and its dependencies.
@@ -30,38 +29,38 @@ First, it will seem like extra work and require time. But when you have several
Therefore we recommend adding ivy files for all the modules in your repository. You can even enforce this rule by setting the descriptor attribute to required on your link:settings/resolvers.html[resolvers]. Hence you shouldn't need to use the dependency artifact inclusion/exclusion/specification feature of Ivy, which should only be used in very specific cases.
-
== Use your own enterprise repository
This is usually not a valid recommendation for open source projects, but for the enterprise world we strongly suggest to avoid relying on a public repository like maven ibiblio or ivyrep. Why? Well, there are a couple of reasons:
+=== Control
+
+The main problem with these kinds of public repositories is that you don't have control over the repository. This means that if a module descriptor is broken you cannot easily fix it. Sure you can use a chain between a shared repository and the public one and put your fixed module descriptor in the shared repository so that it hides the one on the public repository, but this makes repository browsing and maintenance cumbersome.
-* control +
- The main problem with these kinds of public repositories is that you don't have control over the repository. This means that if a module descriptor is broken you cannot easily fix it. Sure you can use a chain between a shared repository and the public one and put your fixed module descriptor in the shared repository so that it hides the one on the public repository, but this makes repository browsing and maintenance cumbersome.
Even more problematic is the possible updates of the repository. We know that versions published in such repositories should be stable and not be updated, but we also frequently see that a module descriptor is buggy, or an artifact corrupted. We even see sometimes a new version published with the same name as the preceding one because the previous one was simply badly packaged. This can occur even to the best; it occurred to us with Ivy 1.2 :-) But then we decided to publish the new version with a different name, 1.2a. But if the repository manager allows such updates, this means that what worked before can break. It can thus break your build reproducibility.
-* reliability +
- The Maven repository is not particularly well known for its reliability (we often experience major slow downs or even complete failures of the site), and ivyrep is only supported by a small company (yes we are only a small company!). So slow down and site hangs occur also. And if the repository you rely on is down, this can cause major slow downs in your development or release process.
+=== Reliability
-* accuracy +
- A public repository usually contains much more than what you actually need. Is this a problem? We think so. We think that in an enterprise environment the libraries you use should step through some kind of validation process before being used in every projects of your company. And what better way to do so? Setup an enterprise repository with only the libraries you actually want to use. This will not only ensure better quality for your application dependencies, but help to have the same versions everywhere, and even help when declaring your module dependencies, if you use a tool like IvyDE, the code completion will only show relevant information about your repository, with only the libraries you actually want to see.
+The Maven repository is not particularly well known for its reliability (we often experience major slow downs or even complete failures of the site), and ivyrep is only supported by a small company (yes we are only a small company!). So slow down and site hangs occur also. And if the repository you rely on is down, this can cause major slow downs in your development or release process.
-* security +
- The artifacts you download from a module repository are often executable, and are thus a security concern. Imagine a hacker replacing commons-lang by another version containing a virus? If you rely on a public repository to build your software, you expose it to a security risk. You can read more about that in this link:http://www.fortifysoftware.com/servlet/downloads/public/fortify_attacking_the_build.pdf[Forrester article].
+=== Accuracy
-Note that using an enterprise repository doesn't mean you have to build it entirely by hand. Ivy features an link:use/install.html[install] task which can be used to install modules from one repository to another one, so it can be used to selectively install modules from a public repository to your enterprise repository, where you will then be able to ensure control, reliability and accuracy.
+A public repository usually contains much more than what you actually need. Is this a problem? We think so. We think that in an enterprise environment the libraries you use should step through some kind of validation process before being used in every projects of your company. And what better way to do so? Setup an enterprise repository with only the libraries you actually want to use. This will not only ensure better quality for your application dependencies, but help to have the same versions everywhere, and even help when declaring your module dependencies, if you use a tool like IvyDE, the code completion will only show relevant information about your repository, with only the libraries you actually want to see.
+=== Security
+
+The artifacts you download from a module repository are often executable, and are thus a security concern. Imagine a hacker replacing commons-lang by another version containing a virus? If you rely on a public repository to build your software, you expose it to a security risk. You can read more about that in this link:http://www.fortifysoftware.com/servlet/downloads/public/fortify_attacking_the_build.pdf[Forrester article].
+
+Note that using an enterprise repository doesn't mean you have to build it entirely by hand. Ivy features an link:use/install.html[install] task which can be used to install modules from one repository to another one, so it can be used to selectively install modules from a public repository to your enterprise repository, where you will then be able to ensure control, reliability and accuracy.
== Always use patterns with at least organisation and module
Ivy is very flexible and can accommodate a lot of existing repositories, using the concept of link:concept.html#pattern[patterns]. But if your repository doesn't exist yet, we strongly recommend always using the organisation and the module name in your pattern, even for a private repository where you put only your own modules (which all have the same organisation). Why? Because the Ivy listing feature relies on the token it can find in the pattern. If you have no organisation token in your pattern, Ivy won't be able to list the (only?) organisation in your repository. And this can be a problem for code completion in IvyDE, for example, but also for repository wide tasks like link:use/install.html[install] or link:use/repreport.html[repreport].
-
== Public ivysettings.xml with public repositories
If you create a public repository, provide a URL to the link:settings.html[ivysettings.xml] file. It's pretty easy to do, and if someone wants to leverage your repository, he will just have to load it with link:use/settings.html[settings] with the URL of your ivysettings.xml file, or link:settings/include.html[include] it in its own configuration file, which makes it really easy to combine several public repositories.
-
== Dealing with integration versions
Very often, especially when working in a team or with several modules, you will need to rely on intermediate, non-finalized versions of your modules. These versions are what we call integration versions, because their main objective is to be integrated with other modules to make and test an application or a framework.
@@ -72,13 +71,11 @@ So, how can you deal with these, possibly numerous, integration versions?
There are basically two ways to deal with them, both ways being supported by Ivy:
+use a naming convention like a special suffix::
+the idea is pretty simple, each time you publish a new integration of your module you give the same name to the version (in maven world this is for example 1.0-SNAPSHOT). The dependency manager should then be aware that this version is special because it changes over time, so that it does not trust its local cache if it already has the version, but checks the date of the version on the repository and sees if it has changed. In Ivy this is supported using the link:ivyfile/dependency.html[changing attribute] on a dependency or by configuring the link:settings/resolvers.html[changing pattern] to use for all your modules.
-* use a naming convention like a special suffix +
- the idea is pretty simple, each time you publish a new integration of your module you give the same name to the version (in maven world this is for example 1.0-SNAPSHOT). The dependency manager should then be aware that this version is special because it changes over time, so that it does not trust its local cache if it already has the version, but checks the date of the version on the repository and sees if it has changed. In Ivy this is supported using the link:ivyfile/dependency.html[changing attribute] on a dependency or by configuring the link:settings/resolvers.html[changing pattern] to use for all your modules.
-
-* automatically create a new version for each +
- in this case you use either a build number or a timestamp to publish each new integration version with a new version name. Then you can use one of the numerous ways in Ivy to link:ivyfile/dependency.html[express a version constraint]. Usually selecting the very latest one (using 'latest.integration' as version constraint) is enough.
-
+automatically create a new version for each::
+in this case you use either a build number or a timestamp to publish each new integration version with a new version name. Then you can use one of the numerous ways in Ivy to link:ivyfile/dependency.html[express a version constraint]. Usually selecting the very latest one (using 'latest.integration' as version constraint) is enough.
So, which way is the best? As often, it depends on your context, and if one of the two was really bad it wouldn't be supported in Ivy :-)
@@ -92,32 +89,28 @@ Unfortunately Ivy does not by its own allow you to have such reproducible builds
On the other hand, the main drawback of this solution is that it can produce a lot of intermediate versions, and you will have to run some cleaning scripts in your repository unless your company name starts with a G and ends with oogle :-)
-
== Inlining dependencies or not?
With Ivy 1.4 you can resolve a dependency without even writing an ivy file. This practice is called inlining. But what is it good for, and when should it be avoided?
Putting ivy dependencies in a separate file has the following advantages:
+separate revision cycle::
+if your dependencies may change more often than your build, it's a good idea to separate the two, to isolate the two concepts: describing how to build / describing your project dependencies
-* separate revision cycle +
- if your dependencies may change more often than your build, it's a good idea to separate the two, to isolate the two concepts: describing how to build / describing your project dependencies
-
-* possibility to publish +
+possibility to publish::
if you describe dependencies of a module which can itself be reused, you may want to use ant to publish it to a repository. In this case the publication is only possible if you have a separate ivy file
-* more flexible +
- inline dependencies can only be used to express one dependency and only one. An ivy file can be used to express much more complex dependencies
+more flexible::
+inline dependencies can only be used to express one dependency and only one. An ivy file can be used to express much more complex dependencies
On the other hand, using inline dependencies is very useful when:
+you want to use a custom task in your ant build::
+Without ivy you usually either copy the custom task jar in ant lib, which requires maintenance of your workstation installation, or use a manual copy or download and a taskdef with the appropriate classpath, which is better. But if you have several custom tasks, or if they have themselves dependencies, it can become cumbersome. Using Ivy with an inline dependency is an elegant way to solve this problem.
-* you want to use a custom task in your ant build +
- Without ivy you usually either copy the custom task jar in ant lib, which requires maintenance of your workstation installation, or use a manual copy or download and a taskdef with the appropriate classpath, which is better. But if you have several custom tasks, or if they have themselves dependencies, it can become cumbersome. Using Ivy with an inline dependency is an elegant way to solve this problem.
-
-* you want to easily deploy an application +
- If you already build your application and its modules using Ivy, it is really easy to leverage your ivy repository to download your application and all its dependencies on the local filesystem, ready to be executed. If you also put your configuration files as artifacts in your repository (maybe packaged as a zip), the whole installation process can rely on ivy, easing the automatic installation of *any* version of your application available in your repository!
-
+you want to easily deploy an application::
+If you already build your application and its modules using Ivy, it is really easy to leverage your ivy repository to download your application and all its dependencies on the local filesystem, ready to be executed. If you also put your configuration files as artifacts in your repository (maybe packaged as a zip), the whole installation process can rely on ivy, easing the automatic installation of *any* version of your application available in your repository!
== Hire an expert
@@ -125,7 +118,6 @@ Build and dependency management is often given too low a priority in the softwar
Therefore hiring a build and dependency expert to analyse and improve your build and release system is most of the time a very good choice.
-
== Feedback
These best practices reflect our own experience, but we do not pretend to own the unique truth about dependency management or even Ivy use.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/compatibility.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/compatibility.adoc b/asciidoc/compatibility.adoc
index 131fbfd..6f2881d 100644
--- a/asciidoc/compatibility.adoc
+++ b/asciidoc/compatibility.adoc
@@ -19,27 +19,20 @@
== JVM compatibility
-
Up to Ivy 2.3.x, a minimum of Java 1.4 is required.
For Ivy 2.4.0, a minimum of Java 5 is required.
Since Ivy 2.5.0, a minimum of Java 7 is required.
-
== Apache Ant
-
Ivy doesn't require a specific version of Ant as long as the Ant being used complies with the JVM compatibility requirements noted above.
-
== Other optional dependencies
-
The required versions of the Apache HttpClient, Jsch or any optional dependency are to be checked against Ivy's dependency descriptor. In Ivy's source, check for the ivy.xml file at the root. Or the pom.xml of `org.apache.ivy#ivy` in the Maven Central repository.
-
== Environment / Configuration Requirements
-
-Ivy does not at this time support multithreaded use. It thus should not be used with the ant `<parallel>` task.
+Ivy does not at this time support multithreaded use. It thus should not be used with the ant `<parallel>` task.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/concept.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/concept.adoc b/asciidoc/concept.adoc
index c9a717b..456021b 100644
--- a/asciidoc/concept.adoc
+++ b/asciidoc/concept.adoc
@@ -17,15 +17,12 @@
under the License.
////
-
== [[dependency-resolver]]Dependency Resolver
A dependency resolver is a pluggable class in ivy which is used to:
-
-* find dependencies' ivy files +
-
-* download dependencies' artifacts +
+* find dependencies' ivy files
+* download dependencies' artifacts
The notion of artifact "downloading" is large: an artifact can be on a web site, or on the local file system of your machine. The download is thus the act of bring a file from a repository to the ivy cache.
@@ -35,12 +32,10 @@ As you see, a dependency resolver can be thought of as a class responsible for d
If you want to see which resolvers are available in ivy, you can go to the link:settings/resolvers.html[resolvers configuration page].
-
== [[configurations]]Module configurations explained
Module configurations are described in the terminology page as _a way to use or construct a module_. Configurations being a central part of Ivy, they need more explanations as a concept.
-
When you define a way to use or construct a module, you are able to define which artifacts are published by this module in this configuration, and you are also able to define which dependencies are needed in this configuration.
Moreover, because dependencies in ivy are expressed on modules and not on artifacts, it is important to be able to define which configurations of the dependency are required in the configuration you define of your module. That's what is called *configuration mapping*.
@@ -49,21 +44,17 @@ If you use only simple modules and do not want to worry about configurations, yo
For details on how to declare your module configurations, how to declare in which configuration your artifacts are published, and how to declare configuration mapping, please refer to link:ivyfile.html[ivy file documentation]. The link:tutorial/conf.html[configurations tutorial] is also a good place to go to learn more about this concept.
-
== [[variables]]Variables
During configuration, ivy allows you to define what are called ivy variables. Ivy variables can be seen as ant properties, and are used in a very similar way. In particular, you use a properties tag in the configuration file to load a properties file containing ivy variables and their values.
-But the main differences between ant properties and ivy variables are that ivy variables can be overridden, whereas ant
-properties can't, and that they are defined in separate environments.
+But the main differences between ant properties and ivy variables are that ivy variables can be overridden, whereas ant properties can't, and that they are defined in separate environments.
Actually all ant properties are imported into ivy variables when the configuration is done (if you call ivy from ant).
This means that if you define an ant property after the call to configure, it will not be available as an ivy variable.
On the other hand, ivy variables are NOT exported to ant, thus if you define ivy variables in ivy, do not try to use them as ant properties.
-To use ivy variables, you just have to follow the same syntax as for ant properties:
-${__variablename__}
-where __variablename__ is the name of the variable.
+To use ivy variables, you just have to follow the same syntax as for ant properties: `${variablename}` where `variablename` is the name of the variable.
Finally, it's also important to be aware of the time of substitution of variables. This substitution is done as soon as possible. This means that when ivy encounters a reference to a variable, it tries to substitute it if such a variable is defined. Consequently, *any later modification of the variable will not alter the value already substituted*.
@@ -74,12 +65,11 @@ See the Patterns chapter below for what pattern tokens are.
== [[patterns]]Patterns
-
Ivy patterns are used in many dependency resolvers and ivy tasks, and are a simple way to structure the way ivy works.
First let's give an example. You can for instance configure the file system dependency resolver by giving it
a pattern to find artifacts. This pattern can be like this:
-myrepository/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]
+`myrepository/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]`
This pattern indicates that the repository we use is in a directory called myrepository.
@@ -91,69 +81,62 @@ Not too difficult to understand is it? That's it, you have understood the patter
To give a bit more explanation, a pattern is composed of tokens, which are replaced by actual values when evaluated for a particular artifact or module. Those tokens are different from variables because they are replaced differently for each artifact, whereas variables are usually given the same value.
You can mix variables and tokens in a pattern:
-${repository.dir}/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]
-
-
+`${repository.dir}/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]`
The tokens available depends on where the pattern is used (will it be evaluated with artifacts or modules, for instance).
But here are all the tokens currently available:
+`[organisation]`::
+the organisation name
-* [organisation] +
- the organisation name
-
-* [orgPath] *__(since 2.3)__* +
- the organisation name where '.' has been replaced by '/'. This can be used to configure maven2-like repositories.
+`[orgPath]`::
+*__(since 2.3)__* +
+the organisation name where '.' has been replaced by '/'. This can be used to configure maven2-like repositories.
-* [module] +
- the module name
+`[module]`::
+the module name
-* [branch] +
- the branch name
+`[branch]`::
+the branch name
-* [revision] +
- the revision name
+`[revision]`::
+the revision name
-* [artifact] +
- the artifact name (or id)
+`[artifact]`::
+the artifact name (or id)
-* [type] +
- the artifact type
+`[type]`::
+the artifact type
-* [ext] +
- the artifact file extension
+`[ext]`::
+the artifact file extension
-* [conf] +
- the configuration name
-
-* [originalname] *__(since 1.4)__* +
- the original artifact name (including the extension)
+`[conf]`::
+the configuration name
+`[originalname]`::
+*__(since 1.4)__* +
+the original artifact name (including the extension)
The difference between type and extension is explained in the ivy file documentation.
-*__since 1.2__* [organization] can be used instead of [organisation].
+*__since 1.2__* `[organization]` can be used instead of `[organisation]`.
*__since 1.3__* Optional parts can be used in patterns.
+
This provides the possibility to avoid some input when a token is not defined, instead of having only the token as blank. Parenthesis are used to delimit the optional part, and only one token can be found inside the parenthesis.
-So if you surround a token with '(' and ')', any other text which is between the parenthesis will be ignored if the token has no value.
-For instance, suppose the pattern: "abc(def[type]ghi)"
-type = "jar" -> the substituted pattern: abcdefjarghi
-type = null or "" -> the substituted pattern: abc
+So if you surround a token with `(` and `)`, any other text which is between the parenthesis will be ignored if the token has no value.
-A more real life example:
-The pattern
-[source]
-----
-[artifact](-[revision]).[ext]
-----
+For instance, suppose the pattern: `abc(def[type]ghi)`
-lets you accept both myartifact-1.0.jar when a revision is set, and myartifact.jar (instead of myartifact-.jar) when no revision is set.
-This is particularly useful when you need to keep control of artifact names.
+* `type` = `"jar"` -> the substituted pattern: `abcdefjarghi`
+* `type` = `null` or `""` -> the substituted pattern: `abc`
-*__since 1.4__* Extra attributes can be used as any other token in a pattern.
+A more real life example:
+The pattern `[artifact](-[revision]).[ext]` lets you accept both `myartifact-1.0.jar` when a revision is set, and `myartifact.jar` (instead of `myartifact-.jar`) when no revision is set. This is particularly useful when you need to keep control of artifact names.
+*__since 1.4__* Extra attributes can be used as any other token in a pattern.
== [[latest]]Latest Strategy
@@ -161,25 +144,23 @@ Ivy often needs to know which revision between two is considered the "latest". T
But before knowing which revision is the latest, ivy needs to be able to consider several revisions of a module. Thus ivy has to get a list of files in a directory, and it uses the dependency resolver for that. So check if the dependency resolver you use is compatible with latest revisions before wondering why ivy does not manage to get your latest revision.
-Finally, in order to get several revisions of a module, most of the time you need to use the [revision] token in your pattern so that ivy gets all the files which match the pattern, whatever the revision is. It's only then that the latest strategy is used to determine which of the revisions is the latest one.
+Finally, in order to get several revisions of a module, most of the time you need to use the `[revision]` token in your pattern so that ivy gets all the files which match the pattern, whatever the revision is. It's only then that the latest strategy is used to determine which of the revisions is the latest one.
Ivy has three built-in latest strategies:
+`latest-time`::
+This compares the revisions date to know which is the latest. While this is often a good strategy in terms of pertinence, it has the drawback of being costly to compute for distant repositories. If you use ivyrep, for example, ivy has to ask the http server what is the date of each ivy file before knowing which is the latest.
-* latest-time +
- This compares the revisions date to know which is the latest. While this is often a good strategy in terms of pertinence, it has the drawback of being costly to compute for distant repositories. If you use ivyrep, for example, ivy has to ask the http server what is the date of each ivy file before knowing which is the latest.
-
-* latest-revision +
- This compares the revisions as strings, using an algorithm close to the one used in the php version_compare function.
+`latest-revision`::
+This compares the revisions as strings, using an algorithm close to the one used in the php version_compare function.
++
This algorithm takes into account special meanings of some text. For instance, with this strategy, 1.0-dev1 is considered before 1.0-alpha1, which in turn is before 1.0-rc1, which is before 1.0, which is before 1.0.1.
-* latest-lexico +
+`latest-lexico`::
This compares the revisions as strings, using lexicographic order (the one used by the Java string comparison).
-
See also how to configure new latest strategies link:settings/latest-strategies.html[here].
-
== [[conflict]]Conflict Manager
A conflict manager is able to select, among a list of module revisions in conflict, a list of revisions to keep.
@@ -192,7 +173,6 @@ The list of available conflict managers is available on the link:settings/confli
For more details on how to setup your conflict managers by module, see the link:ivyfile/conflicts.html[conflicts] section in the ivy file reference.
-
== [[matcher]]Pattern matcher
*__since 1.3__*
@@ -200,19 +180,17 @@ In several places Ivy uses a pattern to match a set of objects. For instance, yo
Ivy uses a pluggable pattern matcher to match those object names. 3 are defined by default:
-
-* exact +
+`exact`::
This matcher matches only using strings
-* regexp +
+`regexp`::
This matcher lets you use a regular expression as supported by the Pattern class of java 1.4 or greater
-* glob +
-This matcher lets you use a Unix-like glob matcher, i.e. where the only meta characters are * which matches any sequence of characters and ? which matches exactly one character. Note that this matcher is available only with jakarta oro 2.0.8 in your classpath.
+`glob`::
+This matcher lets you use a Unix-like glob matcher, i.e. where the only meta characters are `*` which matches any sequence of characters and `?` which matches exactly one character. Note that this matcher is available only with jakarta oro 2.0.8 in your classpath.
Note also that with any matcher, the character '*' has the special meaning of matching anything. This is particularly useful with default values which do not depend on the matcher.
-
== [[extra]]Extra attributes
*__since 1.4__*
@@ -222,12 +200,10 @@ The idea is very simple: if you need some more information to define your module
*__since 2.0__*
It's possible and recommended to use xml namespaces for your extra attributes. Using an Ivy extra namespace is the easiest way to add your own extra attributes.
-Example:
-Here is an ivy file with the attribute 'color' set to blue:
+Example: here is an ivy file with the attribute `color` set to blue:
-[source]
+[source,xml]
----
-
<ivy-module version="2.0" xmlns:e="http://ant.apache.org/ivy/extra">
<info organisation="apache"
module="foo"
@@ -236,26 +212,21 @@ Here is an ivy file with the attribute 'color' set to blue:
revision="1.59"
/>
</ivy-module>
-
----
-Then you must use the extra attribute when you declare a dependency on foo. Those extra attributes
-will indeed be used as identifiers for the module like the org the name and the revision:
+Then you must use the extra attribute when you declare a dependency on `foo`. Those extra attributes
+will indeed be used as identifiers for the module like the `org`, the `name` and the `revision`:
-[source]
+[source,xml]
----
-
<dependency org="apache" name="foo" e:color="blue" rev="1.5+"/>
-
----
And you can define your repository pattern as:
[source]
----
-
${repository.dir}/[organisation]/[module]/[color]/[revision]/[artifact].[ext]
-
----
Note that in patterns you must use the unqualified attribute name (no namespace prefix).
@@ -272,27 +243,24 @@ Globally, use the ivy.checksums variable to list the check to be done.
On each resolver you can use the checksums attribute to override the global setting.
The setting is a comma separated list of checksum algorithms to use.
-During checking (at download time), the first checksum found is checked, and that's all. This means that if you have a "SHA-256, sha1, md5" setting, then if ivy finds a SHA-256 file, it will compare the downloaded file SHA-256 against this SHA-256, and if the comparison is ok, it will assume the file is ok. If no SHA-256 file is found, it will look for an sha1 file. If that isn't found, then it checks for md5 and so on. If none is found no checking is done.
+During checking (at download time), the first checksum found is checked, and that's all. This means that if you have a `"SHA-256, sha1, md5"` setting, then if ivy finds a SHA-256 file, it will compare the downloaded file SHA-256 against this SHA-256, and if the comparison is ok, it will assume the file is ok. If no SHA-256 file is found, it will look for an sha1 file. If that isn't found, then it checks for md5 and so on. If none is found no checking is done.
During publish, all listed checksum algorithms are computed and uploaded.
-By default checksum algorithms are "sha1, md5".
+By default checksum algorithms are `"sha1, md5"`.
-If you want to change this default, you can set the variable ivy.checksums. Hence, to disable checksum validation you just have to set ivy.checksums to "".
+If you want to change this default, you can set the variable `ivy.checksums`. Hence, to disable checksum validation you just have to set `ivy.checksums` to `""`.
=== Supported algorithms
*__since 1.4__*
-
-* md5 +
-
-* sha1 +
+* md5
+* sha1
*__since 2.5__*
Starting 2.5 version, in addition to md5 and sha1, Ivy supports SHA-256, SHA-512 and SHA-384 algorithms, if the Java runtime in which Ivy is running, supports those. For example, Java 6 runtime supports SHA-256 and SHA-512 as standard algorithms. If Ivy 2.5 and later versions are run under Java 6 or higher runtimes, these algorithms are supported by Ivy too.
-
== [[event]]Events and Triggers
*__since 1.4__*
@@ -302,7 +270,6 @@ This is a particularly powerful and flexible feature which allows, for example,
For more details about events and triggers, see the link:settings/triggers.html[triggers] documentation page in the configuration section of this documentation.
-
== [[circular]]Circular Dependencies
*__since 1.4__*
@@ -312,42 +279,36 @@ Prior to Ivy 1.4 circular dependencies where causing a failure in Ivy. As of Ivy
3 built-in strategies are available:
+`ignore`::
+circular dependencies are only signaled in verbose messages
-* ignore +
- circular dependencies are only signaled in verbose messages
-
-* warn +
- same as ignore, except that they are signaled as a warning (default)
-
-* error +
- halt the dependency resolution when a circular dependency is found
+`warn`::
+same as ignore, except that they are signaled as a warning (default)
+`error`::
+halt the dependency resolution when a circular dependency is found
See the link:settings/settings.html[configuration page] to see how to configure the circular dependency strategy you want to use.
-
== Cache and Change Management
Ivy heavily relies on local caching to avoid accessing remote repositories too often, thus saving a lot of network bandwidth and time.
-
=== [[cache]]Cache types
An Ivy cache is composed of two different parts:
-
-* the repository cache +
+the repository cache::
The repository cache is where Ivy stores data downloaded from module repositories, along with some meta information concerning these artifacts, like their original location.
This part of the cache can be shared if you use a well suited link:settings/lock-strategies.html[lock strategy].
-* the resolution cache +
+the resolution cache::
This part of the cache is used to store resolution data, which is used by Ivy to reuse the results of a resolve process.
++
This part of the cache is overwritten each time a new resolve is performed, and should never be used by multiple processes at the same time.
-
While there is always only one resolution cache, you can link:settings/caches.html[define multiple repository caches], each link:settings/resolvers.html[resolver] being able to use a separate cache.
-
=== [[change]]Change management
To optimize the dependency resolution and the way the cache is used, Ivy assumes by default that a revision never changes. So once Ivy has a module in its cache (metadata and artifacts), it trusts the cache and does not even query the repository. This optimization is very useful in most cases, and causes no problem as long as you respect this paradigm: a revision never changes. Besides performance, there are several link:bestpractices.html[good reasons] to follow this principle.
@@ -358,65 +319,51 @@ However, depending on your current build system and your dependency management s
Since pretty often module metadata are not considered by module providers with as much attention as their API or behavior (if they even provide module metadata), it happens more than we would like that we have to update module metadata: a dependency has been forgotten, or another one is missing, ...
-In this case, setting checkModified="true" on your dependency resolver will be the solution. This flag tells Ivy to check if module metadata has been modified compared to the cache. Ivy first checks the metadata last modified timestamp on the repository to download it only if necessary, and then updates it when needed.
+In this case, setting `checkModified="true"` on your dependency resolver will be the solution. This flag tells Ivy to check if module metadata has been modified compared to the cache. Ivy first checks the metadata last modified timestamp on the repository to download it only if necessary, and then updates it when needed.
==== Changes in artifacts
Some people, especially those coming from maven 2 land, like to use one special revision to handle often updated modules. In maven 2 this is called a SNAPSHOT version, and some argue that it helps save disk space to keep only one version for the high number of intermediary builds you can make whilst developing.
-Ivy supports this kind of approach with the notion of "changing revision". A changing revision is just that: a revision for which Ivy should consider that the artifacts may change over time. To handle this, you can either specify a dependency as changing on the link:ivyfile/dependency.html[dependency] tag, or use the changingPattern and changingMatcher attributes on your link:settings/resolvers.html[resolvers] to indicate which revision or group of revisions should be considered as changing.
+Ivy supports this kind of approach with the notion of "changing revision". A changing revision is just that: a revision for which Ivy should consider that the artifacts may change over time. To handle this, you can either specify a dependency as changing on the link:ivyfile/dependency.html[dependency] tag, or use the `changingPattern` and `changingMatcher` attributes on your link:settings/resolvers.html[resolvers] to indicate which revision or group of revisions should be considered as changing.
Once Ivy knows that a revision is changing, it will follow this principle to avoid checking your repository too often: if the module metadata has not changed, it will considered the whole module (including artifacts) as not changed. Even if the module descriptor file has changed, it will check the publication data of the module to see if this is a new publication of the same revision or not. Then if the publication date has changed, it will check the artifacts' last modified timestamps, and download them accordingly.
-So if you want to use changing revisions, use the link:use/publish.html[publish] task to publish your modules, it will take care of updating the publication date, and everything will work fine. And remember to set checkModified=true" on your resolver too!
+So if you want to use changing revisions, use the link:use/publish.html[publish] task to publish your modules, it will take care of updating the publication date, and everything will work fine. And remember to set `checkModified=true"` on your resolver too!
== [[paths]]Paths handling
As a dependency manager, Ivy has a lot of file related operations, which most of the time use paths or path patterns to locate the file on the filesystem.
-These paths can obviously be relative or absolute. We recommend to always use absolute paths, so that you don't have to worry about what is the base of your relative paths. Ivy provides some variables which can be used as the base of your absolute paths. For instance, Ivy has a concept of base directory, which is basically the same as for Ant. You have access to this base directory with the ivy.basedir variable. So if you have a path like
-[source]
-----
-${ivy.basedir}/ivy.xml
-----
-
-, you have an absolute path. In link:settings.html[settings files], you also have a variable called ivy.settings.dir which points to the directory in which your settings file is located, which makes defining paths relative to this directory very easy.
+These paths can obviously be relative or absolute. We recommend to always use absolute paths, so that you don't have to worry about what is the base of your relative paths. Ivy provides some variables which can be used as the base of your absolute paths. For instance, Ivy has a concept of base directory, which is basically the same as for Ant. You have access to this base directory with the ivy.basedir variable. So if you have a path like `${ivy.basedir}/ivy.xml`, you have an absolute path. In link:settings.html[settings files], you also have a variable called `ivy.settings.dir` which points to the directory in which your settings file is located, which makes defining paths relative to this directory very easy.
If you really want to use relative paths, the base directory used to actually locate the file depends on where the relative path is defined:
+* In an Ivy file, paths are relative to the Ivy file itself (the only possible path in an Ivy file is for configurations declaration inclusion)
-* In an Ivy file, paths are relative to the Ivy file itself (the only possible path in an Ivy file is for configurations declaration inclusion) +
-
-* In settings files, paths for file inclusion (namely properties file loading and settings inclusion) are relative to the directory in which the settings file is located. All other paths must be absolute unless explicitly noted. +
-
-* In Ivy Ant tasks and Ivy parameters or options, paths are relative to Ivy base directory, which when called from Ant is the same as your Ant basedir. +
-
+* In settings files, paths for file inclusion (namely properties file loading and settings inclusion) are relative to the directory in which the settings file is located. All other paths must be absolute unless explicitly noted.
+* In Ivy Ant tasks and Ivy parameters or options, paths are relative to Ivy base directory, which when called from Ant is the same as your Ant basedir.
== [[packaging]]Packaging
-
Most of the artifacts found in a repository are jars. They can be downloaded and used as is. But some other kind of artifacts required some __unpacking__ after being downloaded and before being used. Such artifacts can be zipped folders and packed jars. Ivy supports that kind of artifact with *packaging*.
A __packaged__ artifact needs to be declared as such in the module descriptor via the attribute link:ivyfile/artifact.html[packaging]. The value of that attribute defined which kind of unpacking algorithm must be used. Here are the list of currently supported algorithms:
+* `zip`, `jar` or `war`: the artifact will be uncompressed as a folder
-* `zip`, `jar` or `war`: the artifact will be uncompressed as a folder +
-
-* `pack200`: the artifact will be unpacked to a file via the link:http://docs.oracle.com/javase/7/docs/technotes/tools/share/pack200.html[pack200] algorithm +
-
-* `bundle`: the OSGi artifact will be uncompressed as a folder, and every embedded jar file entry which is packed via the the link:http://docs.oracle.com/javase/7/docs/technotes/tools/share/pack200.html[pack200] algorithm will be unpacked +
+* `pack200`: the artifact will be unpacked to a file via the link:http://docs.oracle.com/javase/7/docs/technotes/tools/share/pack200.html[pack200] algorithm
+* `bundle`: the OSGi artifact will be uncompressed as a folder, and every embedded jar file entry which is packed via the the link:http://docs.oracle.com/javase/7/docs/technotes/tools/share/pack200.html[pack200] algorithm will be unpacked
So, if in an `ivy.xml`, there would be declared a such artifact:
-[source]
+[source,xml]
----
-
<artifact name="mymodule" type="jar" ext="jar.pack.gz" packaging="pack200"/>
-
----
A file `mymodule-1.2.3.jar.pack.gz` would be download into the cache, and also uncompressed in the cache to `mymodule-1.2.3.jar`. Then any post resolve task which supports it, like the link:use/cachepath.html[cachepath], will use the uncompressed file instead of the original compressed file.
-It is possible to chain packing algorithm. The attribute link:ivyfile/artifact.html[packaging] of a artifact expects a comma separated list of packing types, in packing order. For instance, an artifact '`mymodule-1.2.3.jar.pack.gz`' can have the packaging '`jar,pack200`', so it would be uncompressed as a folder '`mymodule-1.2.3`'.
+It is possible to chain packing algorithm. The attribute link:ivyfile/artifact.html[packaging] of a artifact expects a comma separated list of packing types, in packing order. For instance, an artifact `mymodule-1.2.3.jar.pack.gz` can have the packaging `jar,pack200`, so it would be uncompressed as a folder `mymodule-1.2.3`.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/dev.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/dev.adoc b/asciidoc/dev.adoc
index aadf5b5..7bafddf 100644
--- a/asciidoc/dev.adoc
+++ b/asciidoc/dev.adoc
@@ -17,7 +17,6 @@
under the License.
////
-
== Building from source
To build Ivy from source it's really easy.
@@ -26,7 +25,6 @@ To build Ivy from source it's really easy.
All you need is
-
* an link:http://subversion.tigris.org/[svn] client +
_to check out Ivy sources from apache svn, not required if you build from sources packaged in a release_
@@ -39,46 +37,35 @@ _ this is not required if you use ant 1.7_
* a link:http://java.sun.com/[jdk] 1.5 or greater +
_Build instructions have been successfully tested with sun jdk 1.5.0 and 1.6.0_
-
-
=== Procedure
-
==== Get the source
You can either get the sources from a release, or get them directly from svn. For instance, to get the trunk version:
-[source]
+[source,shell]
----
-
svn co https://svn.apache.org/repos/asf/ant/ivy/core/trunk ivy
-
----
-
==== Build
Go to the directory where you get the Ivy sources (you should see a file named build.xml) and run:
-[source]
+[source,shell]
----
-
ant
-
----
-
==== Check the result
The ant build will compile the core classes of Ivy and use them to resolve the dependencies (used for some optional features). Then it will compile and run tests with coverage metrics.
-If everything goes well, you should see the message
+If everything goes well, you should see the message:
-[source]
+[source,shell]
----
-
BUILD SUCCESSFUL
-
----
Then you can check the test results in the build/doc/reports/test directory, the jars are in build/artifacts, and the test coverage report in build/doc/reports/coverage
@@ -90,7 +77,6 @@ http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
This is a work in progress though (see link:https://issues.apache.org/jira/browse/IVY-511[IVY-511]), but patches helping migration to these conventions are welcome.
-
== Developing with eclipse
Even though you can develop Ivy with your IDE of choice, we support eclipse development by providing ad hoc metadata.
@@ -104,9 +90,7 @@ First call the following ant target in your Ivy workspace:
[source]
----
-
ant eclipse-default
-
----
This will resolve the dependencies of Ivy and produce a .classpath using the resolved jars for the build path.
@@ -119,21 +103,18 @@ To do so all you need is call the following ant target in your Ivy workspace:
[source]
----
-
ant eclipse-ivyde
-
----
or if you don't have ant installed you can simply copy the file .classpath.ivyde and rename it to .classpath
Then you can import the project using "Import->Existing project into workspace" as long as you already have latest IvyDE installed.
To install latest IvyDE version compatible with the latest Ivy used to resolve Ivy dependencies, you will need to use a snapshot build, not endorsed by the ASF, available here:
-http://people.apache.org/~xavier/ivyde/snapshot/
+https://builds.apache.org/view/A/view/Ant/job/IvyDE/
Download the file and unzip its content in your eclipse installation directory.
-
-=== recommended plugins
+=== Recommended plugins
The Ivy project comes with settings for the link:http://eclipse-cs.sourceforge.net/[checkstyle plugin] we recommend to use to avoid introducing new digression to the checkstyle rules we use.
If you use this plugin, you will many errors in Ivy. As we said, following strict checkstyle rules is a work in progress and we used to have pretty different code conventions (like using _ as prefix for private attributes), so we still have things to fix. We usually use the filter in the problems view to filter out checkstyle errors from this view, which helps to know what the real compilation problem are.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/dev/makerelease.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/dev/makerelease.adoc b/asciidoc/dev/makerelease.adoc
index 4dc4849..248fa2a 100644
--- a/asciidoc/dev/makerelease.adoc
+++ b/asciidoc/dev/makerelease.adoc
@@ -17,141 +17,111 @@
under the License.
////
-
== Making a release
-
=== Requirements
-Requirements for making a release are similar to the requirements for building from source, except that JDK 1.6+ and Apache Ant 1.9+ are required.
+Requirements for making a release are similar to the requirements for building from source, except that Apache Ant 1.9+ is required.
=== Procedure
-
==== 1. Check the files which needs to be updated for the release.
On the master, check that files which require update for the release are up to date.
This includes particularly:
-doc/release-notes.html
+`asciidoc/release-notes.adoc`
==== 2. Check out a clean copy of the branch
Run the following git command to checkout the branch, revert any change and remove untracked and ignored files:
-[source]
+[source,shell]
----
-
git checkout 2.0.x
git reset --hard
git clean -d -x -f
-
----
-
==== 3. Add Ivy xsd file.
You need to store the current ivy xml schema in the documentation, so that it will later be accessible on public web site. To do so, run the following command in the directory in which you checked out the release branch:
-[source]
+[source,shell]
----
-
ant -f build-release.xml release-xsd
-
----
And commit your changes in the branch:
-[source]
+[source,shell]
----
-
-git add doc/ivy.xsd
+git add asciidoc/ivy.xsd
git commit -m "release the ivy.xsd"
-
----
-
==== 4. Launch the release script
-
[source]
----
-
ant -f build-release.xml release
-
----
The status should be release only for final releases, and milestone for any other intermediate release.
If the release script is successful, release artifacts will be waiting for you in the build/distrib directory.
-
==== 5. Verify the release
-Check that all zips can be opened correctly, and that running 'ant' after unzipping the source distribution works properly.
+Check that all zips can be opened correctly, and that running `ant` after unzipping the source distribution works properly.
You can also do a smoke test with the generated ivy.jar, to see if it is able to resolve properly a basic module (for instance you can run some tutorials provided in the src/example directory in all distributions).
-
==== 6. Sign the artifacts
It's now time to sign the release artifacts and upload them to a location accessible by other Apache committers.
Here is a simple way to sign the files using gnupg:
-[source]
+[source,shell]
----
-
gpg --armor --output file.zip.asc --detach-sig file.zip
-
----
Here is a ruby script you can use to sign the files:
-[source]
+[source,ruby]
----
-
require 'find'
Find.find('build/distrib') do |f|
`gpg --armor --output #{f}.asc --detach-sig #{f}` if File.file?(f) && ['.zip', '.gz', '.jar', '.pom'].include?(File.extname(f))
end
-
----
Be prepared to enter your passphrase several times if you use this script, gpg will ask for your passphrase for each file to sign.
-
==== 7. Prepare the Eclipse update site
-
To be able to test the release within IvyDE, it can be deployed in the IvyDE update site. See link:http://ant.apache.org/ivy/ivyde/history/trunk/dev/updatesite.html[that page] to know how to process.
-
==== 8. Publish the release candidate
-
All artifacts in `build/distrib/dist` needs to be published on the 'dist' svn of the ASF, in the *dev* part.
The following command lines should do the job:
-[source]
+[source,shell]
----
-
svn checkout -N https://dist.apache.org/repos/dist/dev/ant/ivy build/distrib/dist
svn add build/distrib/dist/*
svn commit build/distrib/dist -m 'Ivy 2.4.0 distribution'
-
----
-
==== 9. Publish the Maven artifact to Nexus
-
Having your GPG key ID, its password, your apache ID and the associated password, just launch ant and enter the information as required:
-[source]
+[source,shell]
----
-
ant -f build-release.xml upload-nexus
-
----
Once uploaded, log in https://repository.apache.org/ with your preferred web browser (use your Apache ID).
@@ -162,28 +132,22 @@ Now __close__ the staging repository, with the description "Ivy 2.0.0-beta1". Cl
Once the checks passed, you can find in the __Summary__ the URL of the staging repository. It will something like: https://repository.apache.org/content/repositories/orgapacheant-XXXX/
-
==== 10. Create a signed tag
As soon as you are happy with the artifacts to be released, it is time to tag the release
-[source]
+[source,shell]
----
-
git tag -s 2.0.0-beta1 -m 'Release Ivy 2.0.0-beta1'
-
----
And push the changes to the ASF repo
-[source]
+[source,shell]
----
-
git push --tags
-
----
-
==== 11. Call for a vote to approve the release
Cast a vote to approve the release on the dev@ant.apache.org mailing list.
@@ -192,7 +156,6 @@ Here is an example:
[source]
----
-
Subject: [VOTE] Ivy ${version} Release
I have built a release candidate for Ivy ${version}
@@ -213,84 +176,60 @@ Do you vote for the release of these binaries?
Regards,
${me}, Ivy ${version} release manager
-
----
-
==== 12. Publish the release
-
If the release is approved, it's now time to make it public. The artifacts in the __dev__ part needs to be moved into the __release__ one:
-[source]
+[source,shell]
----
-
-$ svn mv https://dist.apache.org/repos/dist/dev/ant/ivy/$VERSION https://dist.apache.org/repos/dist/release/ant/ivy/$VERSION
-
+svn mv https://dist.apache.org/repos/dist/dev/ant/ivy/$VERSION https://dist.apache.org/repos/dist/release/ant/ivy/$VERSION
----
In order to keep the main dist area of a reasonable size, old releases should be removed. They will disappear from the main dist but will still be available via the link:http://archive.apache.org/dist/ant/ivy/[archive]. To do so, just use the `svn rm` command against the artifacts or folders to remove.
-
==== 13. Promote the Maven staging repository
-
Go log in https://repository.apache.org/ with your preferred web browser (use your Apache ID).
Select the appropriate `orgapacheant-XXXX` repository and select the __Release__ action.
-
==== 14. Update the web site
-
It's time to update the download image used on the home page and the download page. Use site/images/ivy-dl.xcf as a basis if you have link:http://www.gimp.org/[gimp] installed. Then you can update the home page to refer to this image, and add a news item announcing the new version. Update also the download page with the new image and update the links to the download location (using a search/replace on the html source is recommended for this).
The just release documentation should be added to the site. To do so, you need to:
-
-. edit the toc.json file in the site component of Ivy +
-and add a piece of json with a title and an url; note that the version in the url must be the same as the tag in the git repo.
-
-[source]
+. edit the toc.json file in the site component of Ivy and add a piece of json with a title and an url; note that the version in the url must be the same as the tag in the git repo.
++
+[source,json]
----
-
{
"title":"2.0.0-beta1",
"url":"http://ant.apache.org/ivy/history/2.0.0-beta1/index.html"
}
-
----
-
-. generate the part of the site for the new version: +
-
-[source]
+. generate the part of the site for the new version:
++
+[source, shell]
----
-
ant checkout-history -Dhistory.version=2.0.0-beta1
ant generate-history -Dhistory.version=2.0.0-beta1
-
----
-
-. if the 'latest-milestone' needs to be update too, run: +
-
-[source]
+. if the 'latest-milestone' needs to be update too, run:
++
+[source,shell]
----
-
ant checkout-history -Dhistory.version=2.0.0-beta1 -Dtarget.history.folder=latest-milestone
-
----
-
-
Now let's generate the website with the new toc:
-
-[source]
+[source,shell]
----
-
ant /all generate-site
-
----
You should verify that the site generated in the production directory is OK. You can open the files with your preferred web browser like it was deployed.
@@ -299,34 +238,27 @@ And once your happy with it, commit the changes in the source directory, and in
Tip: lot's of files might need to be 'added' to svn. An handy command to `add` any file which is not yet under version control is the following one:
-[source]
+[source,shell]
----
svn add --force sources
----
-
==== 15. Deploy the Eclipse updatesite
-
If the Eclipse update site has already been prepared to include that new Ivy release, it is now needed to be deployed. Then follow the deployment instruction on link:http://ant.apache.org/ivy/ivyde/history/trunk/dev/updatesite.html[that page].
-
==== 16. Announce
-Announce the release on the dev@ant.a.o, ivy-user@ant.a.o, user@ant.apache.org and announce@apache.org mailing lists.
-You can also announce the release on popular web sites, like freshmeat.net (xavier is the owner of the Ivy project on freshmeat), javalobby.org, theserverside.com, dzone.com, ...
-
+Announce the release on the dev@ant.apache.org, ivy-user@ant.apache.org, user@ant.apache.org and announce@apache.org mailing lists. Note that announce@apache.org only accepts emails sent with an @apache.org address.
==== 17. Update this doc
If you feel like anything is missing or misleading in this release doc, update it as soon as you encounter the problem.
-
==== 18. Merge your modifications back to the master if necessary.
Modifications on the template files do not need to be merged, but if you had troubles during your release you may want to merge your fixes back to the trunk.
-
==== 19. Prepare next release
In the master branch, update the file version.properties with the version of the next release so that anyone building from the trunk will obtain jar with the correct version number.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/extend.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/extend.adoc b/asciidoc/extend.adoc
index 6bac51f..9783b03 100644
--- a/asciidoc/extend.adoc
+++ b/asciidoc/extend.adoc
@@ -21,31 +21,21 @@ Many things are configurable in Ivy, and many things are available with Ivy core
Many things are pluggable in Ivy:
-
-* module descriptor parsers +
-
-* dependency resolvers +
-
-* lock strategies +
-
-* latest strategies +
-
-* circular dependency strategies +
-
-* conflict managers +
-
-* report outputters +
-
-* version matchers +
-
-* triggers +
-
+* module descriptor parsers
+* dependency resolvers
+* lock strategies
+* latest strategies
+* circular dependency strategies
+* conflict managers
+* report outputters
+* version matchers
+* triggers
Before trying to implement your own, we encourage you to check if the solution to your problem cannot be addressed by existing features, or by contributed ones. Do not hesitate to ask for help on the mailing-lists.
If you still don't find what you need, then you'll have to develop your own plugin or find someone who could do that for you.
-All ivy plug-ins use the same code patterns as ant specific tasks for parameters. This means that if you want to have a "myattribute" of type String, you just have to declare a method called setMyattribute(String val) on your plug-in. The same applies to child tags, you just have to follow Ant specifications.
+All ivy plug-ins use the same code patterns as ant specific tasks for parameters. This means that if you want to have a `myattribute` of type `String`, you just have to declare a method called `setMyattribute(String val)` on your plug-in. The same applies to child tags, you just have to follow Ant specifications.
All pluggable code in Ivy is located in the link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=tree;f=src/java/org/apache/ivy/plugins[org.apache.ivy.plugins] package. In each package you will find an interface that you must implement to provide a new plugin. We usually also provide an abstract class easing the implementation and making your code more independent of interface changes. We heavily recommend using these abstract classes as a base class.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/index.adoc b/asciidoc/index.adoc
index da35c0b..f450274 100644
--- a/asciidoc/index.adoc
+++ b/asciidoc/index.adoc
@@ -19,32 +19,25 @@
Welcome to the official Ivy documentation.
-
== What is Ivy?
Ivy is a tool for managing (recording, tracking, resolving and reporting) project dependencies. It is characterized by the following:
+. flexibility and configurability - Ivy is essentially process agnostic and is not tied to any methodology or structure. Instead it provides the necessary flexibility and configurability to be adapted to a broad range of dependency management and build processes.
-. flexibility and configurability - Ivy is essentially process agnostic and is not tied to any methodology or structure. Instead it provides the necessary flexibility and configurability to be adapted to a broad range of dependency management and build processes. +
-
-
-. tight integration with Apache Ant - while available as a standalone tool, Ivy works particularly well with Apache Ant providing a number of powerful Ant tasks ranging from dependency resolution to dependency reporting and publication. +
+. tight integration with Apache Ant - while available as a standalone tool, Ivy works particularly well with Apache Ant providing a number of powerful Ant tasks ranging from dependency resolution to dependency reporting and publication.
-Ivy is open source and released under a very permissive link:https://ant.apache.org/ivy/license.html[Apache License].
+Ivy is open source and released under a very permissive link:http://www.apache.org/licenses/[Apache License].
Ivy has a lot of powerful link:https://ant.apache.org/ivy/features.html[features], the most popular and useful being its flexibility, integration with ant, and its strong transitive dependencies management engine.
The transitive dependencies management is a feature which lets you get dependencies of your dependencies, transitively. In order to address this general problem, ivy needs to find metadata about your modules, usually in an link:ivyfile.html[ivy file]. To find the metadata and your dependencies' artifacts (usually jars), Ivy can be configured to use a lot of different link:settings/resolvers.html[repositories].
-
== About this doc
-
[NOTE]
====
-
Tip: The menu on the left is dynamic, you can click on the arrows to browse the menu without going to each page.
-
====
This documentation has been migrated from the old Ivy web site hosted by Jayasoft, feel free to report any problem on the link:https://ant.apache.org/ivy/mailing-lists.html[mailing-lists].
@@ -59,7 +52,6 @@ Since Ivy 2.0.0-alpha-2, we keep an online history of the documentation. You can
For earlier versions, we suggest downloading the documentation to browse the documentation corresponding to the version you use. The full history of Ivy versions with corresponding links for download is available in the history menu on the web site.
-
== Other places to go
Check out Ivy link:https://ant.apache.org/ivy/features.html[features]. +
@@ -68,19 +60,17 @@ Ask for help on our link:https://ant.apache.org/ivy/mailing-lists.html[mailing l
Report a bug or feature request in our link:https://ant.apache.org/ivy/issues.html[issue tracking system]. +
Check link:https://ant.apache.org/ivy/links.html[external tools and resources]. +
-
== Overview
This documentation is composed of three main parts:
-
-* link:tutorial.html[Tutorials] +
+link:tutorial.html[Tutorials]::
The tutorials is the best way to begin to play with Ivy. You will easily and quickly learn the basics of Ivy.
-* link:reference.html[Reference] +
+link:reference.html[Reference]::
The reference documentation gives you all the details of Ivy.
The introduction part is particularly useful: it defines some vocabulary, explains main concepts such as dependency resolvers and patterns, and gives an overview of how ivy works internally.
It's also in the reference doc that you will find all you always dreamed to know about ivy settings, ivy files, and ivy use (especially with ant).
-* link:dev.html[Developer doc] +
+link:dev.html[Developer doc]::
The developers's doc is useful for users who would like to extend Ivy or build it from source. It's also the documentation used by the Ivy team, so you will also find information about how we make releases.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/install.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/install.adoc b/asciidoc/install.adoc
index 54e0887..bfa871a 100644
--- a/asciidoc/install.adoc
+++ b/asciidoc/install.adoc
@@ -21,22 +21,21 @@ There are basically two ways to install Ivy: either manually or automatically.
== Manually
-Download the version you want here, unpack the downloaded zip file wherever you want, and copy the ivy jar file into your ant lib directory (ANT_HOME/lib).
+Download the version you want here, unpack the downloaded zip file wherever you want, and copy the ivy jar file into your ant lib directory (`ANT_HOME/lib`).
-If you use ant 1.6.0 or superior, you can then simply go to the src/example/hello-ivy dir and run ant: if the build is successful, you have successfully installed Ivy!
+If you use ant 1.6.0 or superior, you can then simply go to the `src/example/hello-ivy` dir and run ant: if the build is successful, you have successfully installed Ivy!
If you use ant 1.5.1 or superior, you have to modify the build files in the examples:
-- remove the namespace section at their head: xmlns:ivy="antlib:org.apache.ivy.ant"
+
+- remove the namespace section at their head: `xmlns:ivy="antlib:org.apache.ivy.ant"`
- add taskdefs for ivy tasks:
-[source]
+[source,xml]
----
-
<taskdef name="ivy-configure" classname="org.apache.ivy.ant.IvyConfigure"/>
<taskdef name="ivy-resolve" classname="org.apache.ivy.ant.IvyResolve"/>
<taskdef name="ivy-retrieve" classname="org.apache.ivy.ant.IvyRetrieve"/>
<taskdef name="ivy-publish" classname="org.apache.ivy.ant.IvyPublish"/>
-
----
- replace ivy:xxx tasks by ivy-xxx
@@ -44,20 +43,17 @@ You can now run the build, if it is successful, you have successfully installed
If the build is not successful, check the FAQ to see what might be the problem with the ivyrep resolver.
-
=== Ivy dependencies
-
One of the two binary versions of Ivy doesn't include the optional dependencies. To download them using Ivy, all you need is to run the Ant build file provided in the distribution. This will use Ivy itself to download the dependencies. Then you should see the Ivy optional dependencies in the lib directory, organized per configuration (see the ivy.xml for details about the configurations and their use).
-
== Automatically
If you want to use Ivy only in your ant build scripts, and have an internet connection when you build, you can download Ivy from this site and use the downloaded version automatically, using this simple build snippet:
-[source]
+[source,xml]
----
-
+<project xmlns:ivy="antlib:org.apache.ivy.ant">
<property name="ivy.install.version" value="2.1.0-rc2"/>
<condition property="ivy.home" value="${env.IVY_HOME}">
<isset property="env.IVY_HOME"/>
@@ -86,7 +82,7 @@ If you want to use Ivy only in your ant build scripts, and have an internet conn
<taskdef resource="org/apache/ivy/ant/antlib.xml"
uri="antlib:org.apache.ivy.ant" classpathref="ivy.lib.path"/>
</target>
-
+</project>
----
Then the only thing to do is to add the init-ivy target in the depends attribute of your targets using Ivy, and add the ivy namespace to your build script. See the self contained link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/example/go-ivy/build.xml[go-ivy] example for details about this.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/principle.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/principle.adoc b/asciidoc/principle.adoc
index 8ff5dfb..e3066ed 100644
--- a/asciidoc/principle.adoc
+++ b/asciidoc/principle.adoc
@@ -19,12 +19,11 @@
Now that you have been introduced to the main ivy terminology and concepts, it is time to give some explanation of how ivy works.
-
== Usual cycle of modules between different locations
image::images/main-tasks.png[]
-More details on ant tasks link:ant.html[here].
+More details on ant tasks link:ant.html[here].
== Configure
@@ -52,7 +51,6 @@ Finally, an xml report is generated in the cache, which allows ivy to easily kno
After this resolve step, two main steps are possible: either build a path with artifacts in the cache, or copy them to another directory structure.
-
== Retrieve
What is called retrieve in ivy is the act of copying artifacts from the cache to another directory structure. This is done using a pattern, which indicates to ivy where the files should be copied.
@@ -67,14 +65,12 @@ In some cases, it is preferable to use artifacts directly from the cache. Ivy is
This can be particularly useful when building plug-ins for IDEs.
-
== Reports
Ivy is also able to generate readable reports describing the dependencies resolution.
This is done with a simple xsl transformation of the xml report generated at resolve time.
-
== Publish
Finally, Ivy can be used to publish a particular version of a module in your repository, so that it becomes available for future resolving. This task is usually called either manually or from a continuous integration server.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/reference.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/reference.adoc b/asciidoc/reference.adoc
index 5756a3d..c726247 100644
--- a/asciidoc/reference.adoc
+++ b/asciidoc/reference.adoc
@@ -21,37 +21,43 @@ Welcome to the Ivy reference documentation!
If you don't know Ivy at all, take a look at its features, the faq and the link:tutorial.html[tutorials] before digging into this reference documentation.
-
== Reference Overview
This documentation is broken into several parts:
+* Introduction
+** link:terminology.html[Terminology]
++
+This part gives you the meaning of some words used all over the Ivy documentation, such as organization, module, configurations, settings, ...
-* Introduction +
-
- ** link:terminology.html[Terminology] +
- This part gives you the meaning of some words used all over the Ivy documentation, such as organization, module, configurations, settings, ...
-
- ** link:concept.html[Main Concepts] +
- This part introduces the main concepts used in Ivy: dependency resolvers, variables, patterns, and also a good introduction to a central ivy concept: module configurations.
+** link:concept.html[Main Concepts]
++
+This part introduces the main concepts used in Ivy: dependency resolvers, variables, patterns, and also a good introduction to a central ivy concept: module configurations.
- ** link:principle.html[How does it work ?] +
- As the title suggests, here you will find an explanation of how Ivy does work internally, which can help to better understand and customize its use.
+** link:principle.html[How does it work ?]
++
+As the title suggests, here you will find an explanation of how Ivy does work internally, which can help to better understand and customize its use.
- ** link:install.html[Installation] +
- This part describes how to install Ivy.
+** link:install.html[Installation]
++
+This part describes how to install Ivy.
- ** Running +
- This part describes possibility to control the behavior of Ivy at run time
+** Running
++
+This part describes possibility to control the behavior of Ivy at run time
-* link:settings.html[Settings Files] +
+* link:settings.html[Settings Files]
++
This part is dedicated to the specification of the settings file of Ivy (usually called ivysettings.xml). It also gives the list of built-in dependency resolvers available in Ivy.
-* link:ivyfile.html[Ivy Files] +
+* link:ivyfile.html[Ivy Files]
++
This part is the reference for the module descriptors, the Ivy files in which you describe your dependencies. If you have any questions about what can be done or not in an ivy file, you will find the answer here.
-* link:ant.html[Ant Tasks] +
+* link:ant.html[Ant Tasks]
++
This part describes how to use Ivy from ant. It's in this section that all ant tasks provided by Ivy are specified.
-* link:standalone.html[Using standalone] +
+* link:standalone.html[Using standalone]
++
Even though Ivy is most often used from ant, it can also be used from the command line. This page describes how you can do this.
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/release-notes.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/release-notes.adoc b/asciidoc/release-notes.adoc
index 415e788..3fd2288 100644
--- a/asciidoc/release-notes.adoc
+++ b/asciidoc/release-notes.adoc
@@ -17,16 +17,11 @@
under the License.
////
-
-
=== Announcement
-
-
[source]
----
-
-December 21, 2015 - The Apache Ivy project is pleased to announce its 2.5.0 release.
+XXXX DATE XXXXXX - The Apache Ivy project is pleased to announce its 2.5.0 release.
Apache Ivy is a tool for managing (recording, tracking, resolving and
reporting) project dependencies, characterized by flexibility,
@@ -46,15 +41,10 @@ https://issues.apache.org/jira/browse/IVY
More information can be found on the website:
http://ant.apache.org/ivy/
-
----
-
-
-
=== List of Changes in this Release
-
For details about the following changes, check our JIRA install at
http://issues.apache.org/jira/browse/ivy
@@ -87,306 +77,161 @@ List of changes since Ivy 2.4.0:
- NEW: Add ivy.maven.lookup.sources and ivy.maven.lookup.javadoc variables to control the lookup of the additional artifacts. Defaults to true, for backward compatibility (link:https://issues.apache.org/jira/browse/IVY-1529[IVY-1529])
- NEW: Add (conditional) support for SHA-256 SHA-512 and SHA-384 checksum algorithms (link:https://issues.apache.org/jira/browse/IVY-1554[IVY-1554]) (Thanks to Jaikiran Pai)
-
////
Samples :
- NEW: bla bla bla (link:https://issues.apache.org/jira/browse/IVY-1234[IVY-1234]) (Thanks to Jane Doe)
- IMPROVEMENT: bla bla bla (link:https://issues.apache.org/jira/browse/IVY-1234[IVY-1234]) (Thanks to Jane Doe)
- FIX: bla bla bla (link:https://issues.apache.org/jira/browse/IVY-1234[IVY-1234]) (Thanks to Jane Doe)
- DOCUMENTATION: bla bla bla (link:https://issues.apache.org/jira/browse/IVY-1234[IVY-1234]) (Thanks to Jane Doe)
-
////
-
-
=== Committers and Contributors
-
Here is the list of people who have contributed source code and documentation up to this release. Many thanks to all of them, and also to the whole IvyDE community contributing ideas and feedback, and promoting the use of Apache Ivy !
Committers
-* Matt Benson +
-
-* Jean-Louis Boudart +
-
-* Maarten Coene +
-
-* Charles Duffy +
-
-* Xavier Hanin +
-
-* Nicolas Lalevee +
-
-* Jon Schneider +
-
-* Gilles Scokart +
-
+* Matt Benson
+* Jean-Louis Boudart
+* Maarten Coene
+* Charles Duffy
+* Xavier Hanin
+* Nicolas Lalevée
+* Jon Schneider
+* Gilles Scokart
Contributors:
-* Ingo Adler +
-
-* alex322 +
-
-* Mathieu Anquetin +
-
-* Andreas Axelsson +
-
-* Stephane Bailliez +
-
-* Karl Baum +
-
-* Andrew Bernhagen +
-
-* Mikkel Bjerg +
-
-* Per Arnold Blaasmo +
-
-* Jeffrey Blattman +
-
-* Jasper Blues +
-
-* Jim Bonanno +
-
-* Joseph Boyd +
-
-* Dave Brosius +
-
-* Matthieu Brouillard +
-
-* Carlton Brown +
-
-* Mirko Bulovic +
-
-* Ed Burcher +
-
-* Jamie Burns +
-
-* Wei Chen +
-
-* Chris Chilvers +
-
-* Kristian Cibulskis +
-
-* Andrea Bernardo Ciddio +
-
-* Archie Cobbs +
-
-* Flavio Coutinho da Costa +
-
-* Stefan De Boey +
-
-* Mykhailo Delegan +
-
-* Charles Duffy +
-
-* Martin Eigenbrodt +
-
-* Stephen Evanchik +
-
-* Robin Fernandes +
-
-* Gregory Fernandez +
-
-* Danno Ferrin +
-
-* Riccardo Foschia +
-
-* Benjamin Francisoud +
-
-* Wolfgang Frank +
-
-* Jacob Grydholt Jensen +
-
-* John Gibson +
-
-* Mitch Gitman +
-
-* Evgeny Goldin +
-
-* Scott Goldstein +
-
-* Gintautas Grigelionis +
-
-* Pierre Hägnestrand +
-
-* Scott Hebert +
-
-* Tobias Himstedt +
-
-* Aaron Hachez +
-
-* Ben Hale +
-
-* Stephen Haberman +
-
-* Peter Hayes +
-
-* Scott Hebert +
-
-* Payam Hekmat +
-
-* Achim Huegen +
-
-* Ilya +
-
-* Matt Inger +
-
-* Anders Jacobsson +
-
-* Anders Janmyr +
-
-* Steve Jones +
-
-* Christer Jonsson +
-
-* Michael Kebe +
-
-* Matthias Kilian +
-
-* Alexey Kiselev +
-
-* Gregory Kisling +
-
-* Stepan Koltsov +
-
-* Heschi Kreinick +
-
-* Sebastian Krueger +
-
-* Thomas Kurpick +
-
-* Tat Leung +
-
-* Costin Leau +
-
-* Antoine Levy-Lambert +
-
-* Tony Likhite +
-
-* Andrey Lomakin +
-
-* William Lyvers +
-
-* Sakari Maaranen +
-
-* Jan Materne +
-
-* Markus M. May +
-
-* Abel Muino +
-
-* J. Lewis Muir +
-
-* Stephen Nesbitt +
-
-* Joshua Nichols +
-
-* Bernard Niset +
-
-* Ales Nosek +
-
-* David Maplesden +
-
-* Glen Marchesani +
-
-* Phil Messenger +
-
-* Steve Miller +
-
-* Mathias Muller +
-
-* Randy Nott +
-
-* Peter Oxenham +
-
-* Jaikiran Pai +
-
-* Douglas Palmer +
-
-* Jesper Pedersen +
-
-* Emmanuel Pellereau +
-
-* Carsten Pfeiffer +
-
-* Yanus Poluektovich +
-
-* Roshan Punnoose +
-
-* Jean-Baptiste Quenot +
-
-* Carl Quinn +
-
-* Damon Rand +
-
-* Geoff Reedy +
-
-* Torkild U. Resheim +
-
-* Christian Riege +
-
-* Frederic Riviere +
-
-* Jens Rohloff +
-
-* Andreas Sahlbach +
-
-* Brian Sanders +
-
-* Adrian Sandor +
-
-* Michael Scheetz +
-
-* Ben Schmidt +
-
-* Ruslan Shevchenko +
-
-* John Shields +
-
-* Nihal Sinha +
-
-* Gene Smith +
-
-* Michal Srb +
-
-* Colin Stanfill +
-
-* Simon Steiner +
-
-* Johan Stuyts +
-
-* John Tinetti +
-
-* Erwin Tratar +
-
-* Jason Trump +
-
-* David Turner +
-
-* Ernestas Vaiciukevičius +
-
-* Tjeerd Verhagen +
-
-* Richard Vowles +
-
-* Sven Walter +
-
-* James P. White +
-
-* Tom Widmer +
-
-* John Williams +
-
-* Chris Wood +
-
-* Patrick Woodworth +
-
-* Jaroslaw Wypychowski +
-
-* Sven Zethelius +
-
-* Aleksey Zhukov +
-
-* Zhong Wang +
+* Ingo Adler
+* alex322
+* Mathieu Anquetin
+* Andreas Axelsson
+* Stéphane Bailliez
+* Karl Baum
+* Andrew Bernhagen
+* Mikkel Bjerg
+* Per Arnold Blaasmo
+* Jeffrey Blattman
+* Jasper Blues
+* Jim Bonanno
+* Joseph Boyd
+* Dave Brosius
+* Matthieu Brouillard
+* Carlton Brown
+* Mirko Bulovic
+* Ed Burcher
+* Jamie Burns
+* Wei Chen
+* Chris Chilvers
+* Kristian Cibulskis
+* Andrea Bernardo Ciddio
+* Archie Cobbs
+* Flavio Coutinho da Costa
+* Stefan De Boey
+* Mykhailo Delegan
+* Charles Duffy
+* Martin Eigenbrodt
+* Stephen Evanchik
+* Robin Fernandes
+* Gregory Fernandez
+* Danno Ferrin
+* Riccardo Foschia
+* Benjamin Francisoud
+* Wolfgang Frank
+* Jacob Grydholt Jensen
+* John Gibson
+* Mitch Gitman
+* Evgeny Goldin
+* Scott Goldstein
+* Gintautas Grigelionis
+* Pierre Hägnestrand
+* Scott Hebert
+* Tobias Himstedt
+* Aaron Hachez
+* Ben Hale
+* Stephen Haberman
+* Peter Hayes
+* Scott Hebert
+* Payam Hekmat
+* Achim Huegen
+* Ilya
+* Matt Inger
+* Anders Jacobsson
+* Anders Janmyr
+* Steve Jones
+* Christer Jonsson
+* Michael Kebe
+* Matthias Kilian
+* Alexey Kiselev
+* Gregory Kisling
+* Stepan Koltsov
+* Heschi Kreinick
+* Sebastian Krueger
+* Thomas Kurpick
+* Tat Leung
+* Costin Leau
+* Antoine Levy-Lambert
+* Tony Likhite
+* Andrey Lomakin
+* William Lyvers
+* Sakari Maaranen
+* Jan Materne
+* Markus M. May
+* Abel Muino
+* J. Lewis Muir
+* Stephen Nesbitt
+* Joshua Nichols
+* Bernard Niset
+* Ales Nosek
+* David Maplesden
+* Glen Marchesani
+* Phil Messenger
+* Steve Miller
+* Mathias Muller
+* Randy Nott
+* Peter Oxenham
+* Jaikiran Pai
+* Douglas Palmer
+* Jesper Pedersen
+* Emmanuel Pellereau
+* Carsten Pfeiffer
+* Yanus Poluektovich
+* Roshan Punnoose
+* Jean-Baptiste Quenot
+* Carl Quinn
+* Damon Rand
+* Geoff Reedy
+* Torkild U. Resheim
+* Christian Riege
+* Frederic Riviere
+* Jens Rohloff
+* Andreas Sahlbach
+* Brian Sanders
+* Adrian Sandor
+* Michael Scheetz
+* Ben Schmidt
+* Ruslan Shevchenko
+* John Shields
+* Nihal Sinha
+* Gene Smith
+* Michal Srb
+* Colin Stanfill
+* Simon Steiner
+* Johan Stuyts
+* John Tinetti
+* Erwin Tratar
+* Jason Trump
+* David Turner
+* Ernestas Vaiciukevičius
+* Tjeerd Verhagen
+* Richard Vowles
+* Sven Walter
+* James P. White
+* Tom Widmer
+* John Williams
+* Chris Wood
+* Patrick Woodworth
+* Jaroslaw Wypychowski
+* Sven Zethelius
+* Aleksey Zhukov
+* Zhong Wang
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/standalone.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/standalone.adoc b/asciidoc/standalone.adoc
index 6eac03b..cc5abe0 100644
--- a/asciidoc/standalone.adoc
+++ b/asciidoc/standalone.adoc
@@ -23,11 +23,9 @@ Ivy can be used as a standalone program very easily. All you need is a Java 1.7+
Then here is how to call it:
-[source]
+[source,shell]
----
-
java -jar ivy.jar -?
-
----
It will display usage text as follows:
@@ -94,39 +92,29 @@ usage: ivy
-? display this help
-deprecated show deprecated options
-version displays version information
-
----
*__since 1.3__* System properties are included as ivy variables, so you can easily define an ivy variable like this:
-[source]
+[source,shell]
----
-
java -Dmyivyvar=myvalue org.apache.ivy.Main [parameters]
-
----
-
== Examples
-
-[source]
+[source,shell]
----
-
java -jar ivy.jar
-
----
calls ivy with default configuration using ivy.xml in the current dir
'''
-
-[source]
+[source,shell]
----
-
java -jar ivy.jar -settings path/to/myivysettings.xml -ivy path/to/myivy.xml
-
----
calls ivy with given ivysettings file using given ivy file
@@ -135,29 +123,24 @@ calls ivy with given ivysettings file using given ivy file
*__since 1.3__*
-[source]
+[source,shell]
----
-
java -jar ivy.jar -settings path/to/myivysettings.xml -dependency apache commons-lang 2.0
-
----
calls ivy with given ivysettings file and resolve apache `commons-lang 2.0`.
This is equivalent to:
-[source]
+[source,shell]
----
-
java -jar ivy.jar -settings path/to/myivysettings.xml -ivy ivy.xml
-
----
with `ivy.xml` like this:
-[source]
+[source,xml]
----
-
<ivy-module version="1.0">
<info organisation="org"
module="standalone"
@@ -166,33 +149,26 @@ with `ivy.xml` like this:
<dependency org="apache" name="commons-lang" rev="2.0" conf="default->*"/>
</dependencies>
</ivy-module>
-
----
-
'''
*__since 1.3__*
-[source]
+[source,shell]
----
-
java -jar ivy.jar -settings path/to/myivysettings.xml -ivy path/to/myivy.xml -cachepath mycachefile.txt
-
----
calls ivy with given ivysettings file and resolves the dependencies found in the given ivy file, and then outputs the classpath of resolved artifacts in cache in a file. This file can then be used to define a classpath corresponding to all the resolved dependencies for any java program.
-
'''
*__since 1.4__*
-[source]
+[source,shell]
----
-
java -jar ivy.jar -settings path/to/myivysettings.xml -dependency bar foo 2.0 -main org.bar.foo.FooMain
-
----
calls ivy with given ivysettings file and resolves the dependency `bar` `foo` `2.0`, and then runs `org.foo.FooMain` class with the resolved artifacts as classpath
http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/cd8f81d0/asciidoc/style/style.css
----------------------------------------------------------------------
diff --git a/asciidoc/style/style.css b/asciidoc/style/style.css
index 3d0948e..cb83451 100644
--- a/asciidoc/style/style.css
+++ b/asciidoc/style/style.css
@@ -36,9 +36,6 @@ body, p, td, li, ul, ol {
font-family: Verdana, Helvetica, Arial, sans-serif;
font-size: small;
}
-li p {
- margin: 0;
-}
h1, h2, h3, h4, h5, h6 {
color: #7a9438;font-family: "Trebuchet MS", Geneva, Arial, Helvetica, SunSans-Regular, Verdana, sans-serif;
}
@@ -81,10 +78,6 @@ a:hover, a:active {
text-decoration: underline;
color: #7a9438;
}
-p {
- margin: 0 0 1.3em 0;
- padding: 0;
-}
blockquote {
padding: 0 15px 0 15px;
margin: 15px 50px 15px 50px;
@@ -103,6 +96,23 @@ pre {
code {
background-color: #EEE;
}
+dt {
+ font-weight: bold;
+}
+p {
+ margin: 0;
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+ul {
+ margin: 0;
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+li p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
#home img {
padding: 5px 20px 10px 10px;
}