Index: reference.html
===================================================================
--- reference.html (revision 910652)
+++ reference.html (working copy)
@@ -25,32 +25,32 @@
Index: tutorial/defaultconf.html
===================================================================
--- tutorial/defaultconf.html (revision 910652)
+++ tutorial/defaultconf.html (working copy)
@@ -111,7 +111,7 @@
Going further
OK, so we have seen how to easily change the settings of the three main repositories. But what if my shared repository is on a web server? What if you don't want to use maven 2 repository as public repository? What if ...
-No problem, Ivy is very flexible and be configured with very specific settings to match your needs and environment. But before considering writing your own settings from scratch, we suggest reading the following where you will learn how to leverage a part of the default settings and adjust the rest.
+No problem, Ivy is very flexible and can be configured with very specific settings to match your needs and environment. But before considering writing your own settings from scratch, we suggest reading the following where you will learn how to leverage a part of the default settings and adjust the rest.
But before explaining how, you will need to have a quick overview of how ivy is configured by default.
Index: install.html
===================================================================
--- install.html (revision 910652)
+++ install.html (working copy)
@@ -25,11 +25,11 @@
Index: ant.html
===================================================================
--- ant.html (revision 910652)
+++ ant.html (working copy)
@@ -68,10 +68,10 @@
-Those 3 tasks follow the 3 main steps of ivy retrieving dependencies process:
+Those 3 tasks follow the 3 main steps of the ivy retrieving dependencies process:
-- First the configure task tells it how it can find dependencies giving it a path to an xml configuration file.
-- Then the resolve task actually resolve dependencies described by an ivy file, and put those dependencies in the ivy cache (a directory configured in the configuration file).
+- First the configure task tells it how it can find dependencies giving it a path to an xml settings file.
+- Then the resolve task actually resolves dependencies described by an ivy file, and puts those dependencies in the ivy cache (a directory configured in the settings file).
- Finally the retrieve task copies dependencies from the cache to anywhere you want in your file system. You can then use those dependencies to make your classpath with standard ant paths.
Index: principle.html
===================================================================
--- principle.html (revision 910652)
+++ principle.html (working copy)
@@ -25,45 +25,45 @@
Index: textual.html
===================================================================
--- textual.html (revision 910652)
+++ textual.html (working copy)
@@ -119,7 +119,7 @@
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.
+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.
Index: concept.html
===================================================================
--- concept.html (revision 910652)
+++ concept.html (working copy)
@@ -28,16 +28,16 @@
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: artifact can be on a web site, or on the local file system of your machine. The download is thus the fact to bring a file from a repository to ivy cache.
+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.
-Moreover, the fact that it is the responsibility of the resolver to find ivy files and download artifacts help to implement various resolving strategies.
+Moreover, the fact that it is the responsibility of the resolver to find ivy files and download artifacts helps to implement various resolving strategies.
-As you see, a dependency resolver can be thought as a class responsible of describing a repository.
+As you see, a dependency resolver can be thought of as a class responsible for describing a repository.
-If you want to see which resolvers are available in ivy, you can go to the corresponding configuration section
+If you want to see which resolvers are available in ivy, you can go to the corresponding configuration section.
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.
@@ -46,30 +46,30 @@
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.
-If you use only simple modules and do not want to worry about configurations, you don't have to worry about them. They're still there under the hood, cause ivy can't work without configuration. But most of the time if you declare nothing, ivy assumes that the artifacts of your module are published in all configurations, and that all the dependencies configurations are required in all configurations. And it works in simple cases. But whenever you want to separate things within a module, or get more control over things published and got through dependencies resolution, configuration may answer most of your needs.
+If you use only simple modules and do not want to worry about configurations, you don't have to worry about them. They're still there under the hood because ivy can't work without configurations. But most of the time if you declare nothing, ivy assumes that the artifacts of your module are published in all configurations, and that all the dependencies' configurations are required in all configurations. And it works in simple cases. But whenever you want to separate things within a module, or get more control over things published and get better dependencies resolution, configurations will meet most of your needs.
-For details on how to declare your module configurations, how declare in which configuration your artifacts are published, and how to declare configuration mapping, please refer to ivy file documentation. The configurations tutorial is also a good place to go to learn more about this concept.
+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 ivy file documentation. The configurations tutorial is also a good place to go to learn more about this concept.
Variables
-During configuration, ivy allows 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.
+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 overriden, whereas ant
-properties can't, and that they are defined in separate environment.
+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 that same syntax as for 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.
-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 encounter 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.
+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.
-Moreover, in an ant environment, a bunch of variables are going to be set by default via the ant property file loading mechanism (actually they are first loaded as ant properties and then imported as ivy variables, see [[ant]]), and even in the ant properties themselves there is going to be eager substitution on loading, effectively making it impossible to override some variable purely via the ivysettings.properties file. Some variables will really only be able to be overriden via ant properties because of this.
+Moreover, in an ant environment, a bunch of variables are going to be set by default via the ant property file loading mechanism (actually they are first loaded as ant properties and then imported as ivy variables, see [[ant]]), and even in the ant properties themselves there is going to be eager substitution on loading, effectively making it impossible to override some variable purely via the ivysettings.properties file. Some variables will really only be able to be overridden via ant properties because of this.
Moreover, it's also important to understand the difference between ivy variables and ivy pattern tokens.
-See Patterns chapter below to see what pattern tokens are.
+See the Patterns chapter below for what pattern tokens are.
Patterns
Ivy patterns are used in many dependency resolvers and ivy tasks, and are a simple way to structure the way ivy works.
@@ -82,8 +82,8 @@
In this directory we have directories having for name the name of the organisation of the module we look for.
Then we have a directory per module, each having for name the name of the module.
-Then in module directories we find a directory per artifact type (jars, wars, ivys, ...), in which we find artifacts named by the artifact id, followed by an hyphen, then the revision, a dot, and the artifact extension.
-Not too difficult to understand, isn't it ? That's it, you have understood the pattern concept !
+Then in module directories we find a directory per artifact type (jars, wars, ivys, ...), in which we find artifacts named by the artifact id, followed by a hyphen, then the revision, a dot, and the artifact extension.
+Not too difficult to understand is it? That's it, you have understood the pattern concept!
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.
@@ -104,12 +104,12 @@
[originalname] (since 1.4) the original artifact name (including the extension)
-Difference between type and extension are explained in ivy file documentation.
+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.3 Optinal parts can be used in patterns.
-This let 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.
+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)"
@@ -117,56 +117,55 @@
type = null or "" -> the substitued pattern: abc
A more real life example:
-The pattern [artifact](-[revision]).[ext] let 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 on artifact names.
+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 the patterns.
+since 1.4 Extra attributes can be used as any other token in a pattern.
-Ivy often needs to know which revision between two has to be considered the "latest". For knowing that, it uses the concept of latest strategy. Indeed, there are several way to consider a revision to be the latest.
-You can choose an existing one or plug your own.
+Ivy often needs to know which revision between two is considered the "latest". To know that, it uses the concept of latest strategy. Indeed, there are several ways to consider a revision to be the latest. You can choose an existing one or plug in your own.
-But before knowing which revision is the latest, ivy needs to be able to consider several revision 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 do not manage to get your latest revision.
+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 this 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
it 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 to be costful to compute with 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
it compares the revisions as string, using an algorithm close to the one used in the php version_compare function.
-This algorithm takes into account special meaning 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
: it compares the revisions as string, using lexicographic order (the one used by java string comparison).
+- 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.
+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
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 here.
A conflict manager is able to select, among a list of module revisions in conflict, a list of revisions to keep.
-Yes, it can selects a list of revision, even if most conflicts manager select only one revision.
+Yes, it can select a list of revisions, even if most conflict managers select only one revision.
But in some cases you will need to keep several revisions, and load in separate class loaders, for example.
A list of revisions is said to be in conflict if they correspond to the same module, i.e. the same organisation/module name couple.
The list of available conflict managers is available on the conflict manager configuration page.
-To have more details on how to setup your conflict managers by module, see conflicts section in ivy file reference.
+For more details on how to setup your conflict managers by module, see the conflicts section in the ivy file reference.
since 1.3
-At several places Ivy let uses pattern to match a set of objects. For instance, you can exclude several modules at once when declaring a dependency by using a pattern matching all the modules to exclude.
+In several places Ivy uses a pattern to match a set of objects. For instance, you can exclude several modules at once when declaring a dependency by using a pattern matching all the modules to exclude.
-Ivy uses pluggable pattern matcher to match those object names. 3 are defined by default:
+Ivy uses a pluggable pattern matcher to match those object names. 3 are defined by default:
-- exact
This matcher matches only string when they are equal to the pattern one
-- regexp
This matcher let you use regular expression as supported by the Pattern class of java 1.4 or greater
-- glob
This matcher let you use 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.
+- exact
This matcher matches only using strings
+- 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.
-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.
+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.
since 1.4
Several tags in ivy xml files are extensible with what is called extra attributes.
-The idea is very simple: if you need some more information to define your modules, you can add the attribute you want and you will then be able to access it as any other attribute in your patterns for example.
+The idea is very simple: if you need some more information to define your modules, you can add the attribute you want and you will then be able to access it as any other attribute in your patterns.
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.
@@ -184,7 +183,7 @@
Then you must use the extra attribute when you declare a dependency on foo. Those extra attributes
-will indeed be used as identifier for the module like the org the name and the revision:
+will indeed be used as identifiers for the module like the org the name and the revision:
@@ -198,50 +197,50 @@
If you don't want to use xml namespaces, it's possible but you will need to disable ivy file validation, since your files won't fulffill anymore the official ivy xsd. See the settings documentation to see how to disable validation.
since 1.4
-Ivy allow to use checksums, also known as digester, to verify the correctness of a downloaded file.
+Ivy allows the use of checksums, also known as digests, to verify the correctness of a downloaded file.
-For the moment Ivy supports md5 and sha1 algorithm.
+For the moment Ivy supports the md5 and sha1 algorithms.
The configuration of using md5 and/or sha1 can be done globally or by dependency resolver.
Globally, use the ivy.checksums variable to list the check to be done (only md5 and sha1 are supported).
On each resolver you can use the checksums attribute to override the global setting.
-The setting is a comma separated list of checksum algorithm to use.
-During checking (at download time), the first checksum found is checked, and that's all. This means that if you have a "sha1, md5" setting, then if ivy finds a sha1 file, it will compare the downloaded file sha1 against this sha1, and if the comparison is ok, it will assume the file is ok. If no sha1 file is found, it will look for a md5 file. If none is found no checking is done.
+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 "sha1, md5" setting, then if ivy finds a sha1 file, it will compare the downloaded file sha1 against this sha1, and if the comparison is ok, it will assume the file is ok. If no sha1 file is found, it will look for an md5 file. 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".
-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 "".
since 1.4
When Ivy performs the dependency resolution and some other tasks, it fires events before and after the most important steps. You can listen to these events using Ivy API, or you can even register a trigger to perform a particular action when a particular event occur.
-This is a particularly powerful and flexible feature which allow for example to perform a build of a dependency just before it is resolved, or follow what's happening during the dependency resolution process accuratly, and so on.
+This is a particularly powerful and flexible feature which allows, for example, you to perform a build of a dependency just before it is resolved, or follow what's happening during the dependency resolution process accuratly, and so on.
-For more details about event and triggers, see the triggers documentation page in the configuration section of this documentation.
+For more details about events and triggers, see the triggers documentation page in the configuration section of this documentation.
since 1.4
-Circular dependencies can be either direct or indirect. For instance, if A depends on A it's a circular dependency, and if A depends on B which itself depends on A, this is also a circular dependency.
+Circular dependencies can be either direct or indirect. For instance, if A depends on A, it's a circular dependency, and if A depends on B which itself depends on A, this is also a circular dependency.
Prior to Ivy 1.4 circular dependencies where causing a failure in Ivy. As of Ivy 1.4, the behaviour of Ivy when it finds a circular dependency is configurable through a circular dependency strategy.
3 built-in strategies are available:
- ignore
circular dependencies are only signaled in verbose messages
-- warn
same as ignore, except that they are signaled as 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 configuration page to see how to configure the circular dependency strategy you want to use.
Cache and Change Management
-Ivy heavily relies on local cache(s) to avoid accessing remote repositories too often, thus saving a low of network bandwidth and time.
+Ivy heavily relies on local caching to avoid accessing remote repositories too often, thus saving a lot of network bandwidth and time.
-Ivy cache is composed of two different parts:
+An Ivy cache is composed of two different parts:
- 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.
@@ -254,19 +253,19 @@
While there is always only one resolution cache, you can [[settings/caches define multiple repository caches]], each [[settings/resolvers resolver]] being able to use a separate cache.
-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 do 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 [[bestpractices good reasons]] to follow this principle.
+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 [[bestpractices good reasons]] to follow this principle.
-However, depending on your current build system and your dependency management strategy, you may prefer to update sometimes your modules. There are two kind of changes to consider:
+However, depending on your current build system and your dependency management strategy, you may prefer to update your modules sometimes. There are two kinds of changes to consider:
Changes in module metadata
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 to 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 update 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 saves disk space to keep only one version for the high number of intermediary builds you can make whilst developing.
+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 [[ivyfile/dependency]] tag, or use the changingPattern and changingMatcher attributes on your [[settings/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 [[ivyfile/dependency]] tag, or use the changingPattern and changingMatcher attributes on your [[settings/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.
+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 [[ant: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!
Index: bestpractices.html
===================================================================
--- bestpractices.html (revision 910652)
+++ bestpractices.html (working copy)
@@ -28,33 +28,33 @@
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 produce as artifact and its dependencies.
+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.
-It is a good practice to write or download module descriptors for all the modules involved in your development, even for your third party dependencies, and even if they don't provide themselves such module descriptors.
+It is a good practice to write or download module descriptors for all the modules involved in your development, even for your third party dependencies, and even if they don't provide such module descriptors themselves.
-First it will seem like an extra work, and require time. But when you will have several modules using the same third party library, and than you will only need to add one line to your ivy file to get this library and all its own dependencies that you really need (if you have good module descriptors in your repository, especially with the use of module configurations). It will also be very helpful when you want to upgrade a dependency. One single change in your module ivy file and you will get the updated version with its updated (or not) dependencies.
+First, it will seem like extra work and require time. But when you have several modules using the same third party library, then you will only need to add one line to your ivy file to get this library and all its own dependencies that you really need (if you have good module descriptors in your repository, especially with the use of module configurations). It will also be very helpful when you want to upgrade a dependency. One single change in your module ivy file and you will get the updated version with its updated (or not) dependencies.
-Therefore we recommend to add ivy files for all the modules in your repository, you can even enforce this rule by setting the allownomd attribute to false on your 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.
+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 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 this kind 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 fixed 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 hide 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 allow such updates, this means that what worked before can break. It can thus break your build reproducibility.
-- reliability
Maven repository is not particularly well known for its reliability (we often experience major slow down or even complete break of the site), and ivyrep is only supported by a small company (yes we are only a small company!). So slow down and site hang occurs also. And if the repository you rely on is down, this can cause major slow down in your development or release process.
-- accuracy
a public repository usually contains much more than what you actually need. Is it 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 a better quality of 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 involved in security concerns. 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 Forrester article.
+- 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.
+- 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 Forrester article.
-Note that it's not because you use an enterprise repository that you have to build it entirely by hand. Ivy features an [[ant:install]] task which can be used to install modules from a 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.
+Note that using an enterprise repository doesn't mean you have to build it entirely by hand. Ivy features an [[ant: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 accomodate a lot of existing repositories, using the concept of patterns. But if your repository doesn't exist yet, we strongly recommend to always use the organisation and the module name in your pattern, even for private repository where you put only your own modules (which all the same organisation). Why? Because Ivy listing feature rely 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 [[ant:install]] or [[ant:repreport]].
+Ivy is very flexible and can accomodate a lot of existing repositories, using the concept of 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 [[ant:install]] or [[ant:repreport]].
Public ivysettings.xml with public repositories
-If you create a public repository, provide an url to corresponding ivysettings.xml. It's pretty easy to do, and if someone want to leverage your repository, he will just have to load it with [[ant:settings]] with the url of your ivysettings.xml, or include it in its own configuration file, which makes it really easy to combine several public repositories.
+If you create a public repository, provide a URL to the 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 [[ant:settings]] with the URL of your ivysettings.xml file, or 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.
+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.
If you follow the continuous integration paradigm across modules, these integration versions can be produced by a continuous integration server, very frequently.
@@ -62,19 +62,19 @@
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 check the date of the version on the repository and see if it hass changed. In Ivy this is supported using the changing attribute on a dependency or by configuring the changing pattern to use for all your modules.
-- create automatically 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 express a version constraint. Usually selecting the very latest one (using 'latest.integration' as version constraint) is enough.
+- 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 changing attribute on a dependency or by configuring the 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 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 :-)
-But usually we recommend to use the second one, because using a new version each time you publish a new version better fits the version identity paradigm, and can make all your builds reproducible, even integration one. And this is interesting because it enables, with some work in your build system, to introduce a mechanism to promote an integration build to a more stable status, like a milestone or a release.
+But usually we recommend using the second one, because using a new version each time you publish a new version better fits the version identity paradigm, and can make all your builds reproducible, even integration ones. And this is interesting because it enables, with some work in your build system, the ability to introduce a mechanism to promote an integration build to a more stable status, like a milestone or a release.
-Imagine you have a customer which comes on a monday morning and asks your latest version of your software, for testing or demonstration purpose. Obviously he needs it for the afternoon :-) Now if you have a continuous integration process and a good tracking of your changes and your artifacts, it may occur that you are actually able to fulfill his request without needing the use of a dolorean to give you some more time :-) But it may occur also that your latest version stable enough to be used for the purpose of the customer was actually built a few days ago, because the very latest just break a feature or introduce a new one you don't want to deliver. In this case, you can deliver this 'stable' integration build if you want, but be sure that a few days, or weeks, or even months later, the customer will ask for a bug fix on this demo only version. Why? Because it's a customer, and we all know how they are :-)
+Imagine you have a customer who comes on a Monday morning and asks for the latest version of your software, for testing or demonstration purposes. Obviously he needs it for the afternoon :-) Now if you have a continuous integration process and good tracking of your changes and your artifacts, it may occur to you that you are actually able to fulfill his request without needing the use of a DeLorean to give you some more time :-) But it may also occur to you that your latest version is stable enough to be used for the purpose of the customer, but was actually built a few days ago, because the very latest just broke a feature or introduced a new one you don't want to deliver. You can deliver this 'stable' integration build if you want, but rest assured that a few days, or weeks, or even months later, the customer will ask for a bug fix on this demo only version. Why? Because it's a customer, and we all know how they are :-)
-So, with a build promotion feature of any build in your repository, the solution would be pretty easy: when the customer ask for the version, you not only deliver the integration build, but you also promote it to a milestone status, for example. this promotion indicates that you should keep track of this version in a long period, to be able to come back to it and create a branch if needed.
+So, with a build promotion feature of any build in your repository, the solution would be pretty easy: when the customer asks for the version, you not only deliver the integration build, but you also promote it to a milestone status, for example. This promotion indicates that you should keep track of this version for a long period, to be able to come back to it and create a branch if needed.
-Unfortunately Ivy does not by its own allow to have such reproducible builds out of the box, simply because Ivy is a dependency manager, not a build tool. But if you publish only versions with a distinct name and use Ivy features like versions constraint replacement during the publication or recursive delivery of modules, it can really help.
+Unfortunately Ivy does not by its own allow you to have such reproducible builds out of the box, simply because Ivy is a dependency manager, not a build tool. But if you publish only versions with a distinct name and use Ivy features like versions constraint replacement during the publication or recursive delivery of modules, it can really help.
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 :-)
@@ -84,7 +84,7 @@
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
-- possibility to publish
if you describe dependencies of a module which can itself be reused, you will ant to publish it to a repository. In this case the publication is only possible if you have a separate ivy file
+- 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
On the other hand, using inline dependencies is very useful when:
@@ -93,12 +93,12 @@
- 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 (maybee 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
-Build and dependency management is often considered with a too low level priority in the software development world. We often see build management implemented by developers when they have time. Even if this may seem like a time and money saving in the short term, it often turns out to be a very bad choice in the long term. Building software is not a simple task, when you want to ensure automatic, tested, fully reproducible builds, releases and installations. On the other hand, once a good build system fitting your very specific needs is setup, it can then only rely on a few people with a good understanding of what is going on, with a constant quality ensured.
+Build and dependency management is often given too low a priority in the software development world. We often see build management implemented by developers when they have time. Even if this may seem like a time and money savings in the short term, it often turns out to be a very bad choice in the long term. Building software is not a simple task, when you want to ensure automatic, tested, fully reproducible builds, releases and installations. On the other hand, once a good build system fitting your very specific needs is setup, it can then only rely on a few people with a good understanding of what is going on, with a constant quality ensured.
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 are the reflect of our own experience, but we do not pretend to own the unique truth about dependency management or even Ivy use.
+These best practices reflect our own experience, but we do not pretend to own the unique truth about dependency management or even Ivy use.
So feel free to comment on this page to add your own experience feedback, suggestions or opinion.
Index: settings.html
===================================================================
--- settings.html (revision 910652)
+++ settings.html (working copy)
@@ -25,11 +25,11 @@
Index: index.html
===================================================================
--- index.html (revision 910652)
+++ index.html (working copy)
@@ -38,7 +38,7 @@
Ivy has a lot of powerful [[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 let you get dependencies of your dependencies, transitively. In order to address this problematic ivy needs to find metadata about your modules, usually in an ivy file. To find these metadata and your dependencies artifacts (usually jars), Ivy can be configured to use a lot of different repositories.
+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 ivy file. To find the metadata and your dependencies' artifacts (usually jars), Ivy can be configured to use a lot of different repositories.
About this doc
@@ -46,9 +46,9 @@
This documentation has been migrated from the old Ivy web site hosted by Jayasoft, feel free to report any problem on the [[mailing-lists]].
-If you browse this documentation from your installation of Ivy, you can also check the online version for latest updates.
+If you browse this documentation from your installation of Ivy, you can also check the online version for the latest updates.
-You can also browse this documentation offline either by downloading the documentation distribution, or by checking out the doc directory from svn. This documentation uses xooki as documentation engine, so you can very easily [[get-involved edit it and submit patches]] when you browse it from source.
+You can also browse this documentation offline either by downloading the documentation distribution, or by checking out the doc directory from svn. This documentation uses xooki as its documentation engine, so you can very easily [[get-involved edit it and submit patches]] when you browse it from source.
A printer-friendly version of this whole documentation is also provided for your convenience.
@@ -57,20 +57,20 @@
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 Ivy [[features features]].
+Check out Ivy [[features features]].
Read our [[faq FAQ]].
Ask for help on our [[mailing-lists mailing lists]].
-Report bug or feature request in our [[issues issue tracking system]].
+Report a bug or feature request in our [[issues issue tracking system]].
Check [[links external tools and resources]].
Overview
-This documentation is decomposed in 3 main parts:
+This documentation is composed of three main parts:
- [[tutorial]]
-The tutorials is the best way to begin to play with ivy. You will easily and quickly learn the basics of Ivy.
+The tutorials is the best way to begin to play with Ivy. You will easily and quickly learn the basics of Ivy.
- [[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 give an overview on how ivy works internally.
+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).
- [[dev]]
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.
Index: terminology.html
===================================================================
--- terminology.html (revision 910652)
+++ terminology.html (working copy)
@@ -47,9 +47,9 @@
-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.
+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
@@ -66,19 +66,19 @@
The most common module descriptors in Ivy are [[ivyfile]], xml files with an Ivy specific syntax, and usually called ivy.xml.
-But since Ivy is also compatible with maven 2 metadata format (called pom, for Project Object Model), pom files falls into the category of module descriptors.
+But since Ivy is also compatible with maven 2 metadata format (called pom, for Project Object Model), pom files fall into the category of module descriptors.
And because Ivy accepts pluggable module descriptor parsers, you can use almost whatever you want as module descriptors.
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 storage. 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.
+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.
In the Java world, common artifacts are Java archives or JAR files. In many cases, each revision of a module publishes only one artifact (like jakarta-log4j-1.2.6.tar.gz, for instance), but some of them publish many artifacts dependending on the use of the module (like apache-ant binary and source distributions in zip, gz and bz2 package formats, for instance).
Examples: ant-1.7.0-bin.zip, apache-ant-1.7.0-src.tar.gz
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 is it provided, not a category of packaging format or how is the artifact 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.
@@ -117,13 +117,13 @@
A module configuration is a way to use or construct a module. If the same module has different dependencies based on how it's used, those distinct dependency-sets are called its configurations in Ivy.
Some modules may be used in different ways (think about hibernate which can be used inside or outside an application server), and this way may alter the artifacts you need (in the case of hibernate, jta.jar is needed only if it is used outside an application server).
-Moreover, a module may need some other modules and artifacts only at build time, and some others at runtime. All those differents ways to use or build a module are called module configurations in ivy.
+Moreover, a module may need some other modules and artifacts only at build time, and some others at runtime. All those different ways to use or build a module are called module configurations in ivy.
For more details on configurations and how they are used in ivy, please refer to the main concepts page.
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 a 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 inconsistencies in this documentation.
+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.
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).