Documentation review (partly inspired by IVY-1089) Project: http://git-wip-us.apache.org/repos/asf/ant-ivy/repo Commit: http://git-wip-us.apache.org/repos/asf/ant-ivy/commit/614bf1ad Tree: http://git-wip-us.apache.org/repos/asf/ant-ivy/tree/614bf1ad Diff: http://git-wip-us.apache.org/repos/asf/ant-ivy/diff/614bf1ad
Branch: refs/heads/master Commit: 614bf1ad51082c3f6eabe68e23faabe85107d225 Parents: 9e1b089 Author: Gintas Grigelionis <[email protected]> Authored: Wed Sep 6 04:22:35 2017 +0200 Committer: Gintas Grigelionis <[email protected]> Committed: Wed Sep 6 04:22:35 2017 +0200 ---------------------------------------------------------------------- asciidoc/ant.adoc | 42 +++++----- asciidoc/bestpractices.adoc | 8 +- asciidoc/compatibility.adoc | 4 +- asciidoc/concept.adoc | 38 +++++---- asciidoc/dev.adoc | 30 +++---- asciidoc/dev/makerelease.adoc | 6 +- asciidoc/extend.adoc | 6 +- asciidoc/index.adoc | 10 +-- asciidoc/install.adoc | 14 ++-- asciidoc/ivyfile.adoc | 24 +++--- asciidoc/ivyfile/artifact-exclude.adoc | 9 +-- asciidoc/ivyfile/artifact.adoc | 6 +- asciidoc/ivyfile/conf.adoc | 2 +- asciidoc/ivyfile/configurations.adoc | 10 +-- asciidoc/ivyfile/conflict.adoc | 10 +-- asciidoc/ivyfile/conflicts.adoc | 28 ++++--- asciidoc/ivyfile/dependencies.adoc | 10 +-- asciidoc/ivyfile/dependency-artifact.adoc | 10 +-- asciidoc/ivyfile/dependency-include.adoc | 8 +- asciidoc/ivyfile/dependency.adoc | 22 +++--- asciidoc/ivyfile/description.adoc | 4 +- asciidoc/ivyfile/exclude.adoc | 4 +- asciidoc/ivyfile/include.adoc | 4 +- asciidoc/ivyfile/ivyauthor.adoc | 4 +- asciidoc/ivyfile/license.adoc | 2 +- asciidoc/ivyfile/manager.adoc | 4 +- asciidoc/ivyfile/override.adoc | 4 +- asciidoc/ivyfile/repository.adoc | 6 +- asciidoc/js/jquery.treeview.js | 2 +- asciidoc/moreexamples.adoc | 20 ++--- asciidoc/osgi.adoc | 2 +- asciidoc/osgi/eclipse-plugin.adoc | 8 +- asciidoc/osgi/osgi-mapping.adoc | 6 +- asciidoc/osgi/sigil.adoc | 4 +- asciidoc/osgi/standard-osgi.adoc | 2 +- asciidoc/osgi/target-platform.adoc | 4 +- asciidoc/reference.adoc | 8 +- asciidoc/release-notes.adoc | 10 +-- asciidoc/resolver/chain.adoc | 6 +- asciidoc/resolver/dual.adoc | 6 +- asciidoc/resolver/filesystem.adoc | 10 +-- asciidoc/resolver/ibiblio.adoc | 16 ++-- asciidoc/resolver/ivyrep.adoc | 6 +- asciidoc/resolver/jar.adoc | 8 +- asciidoc/resolver/mirrored.adoc | 10 +-- asciidoc/resolver/obr.adoc | 4 +- asciidoc/resolver/osgiagg.adoc | 4 +- asciidoc/resolver/packager.adoc | 55 +++++-------- asciidoc/resolver/sftp.adoc | 29 ++++--- asciidoc/resolver/ssh.adoc | 13 ++-- asciidoc/resolver/updatesite.adoc | 6 +- asciidoc/resolver/url.adoc | 10 +-- asciidoc/resolver/vfs.adoc | 10 +-- asciidoc/samples/build.xml | 82 ++++++++++---------- asciidoc/samples/eclipse-plugin/build.xml | 2 +- asciidoc/samples/standard-osgi/build.xml | 2 +- asciidoc/settings.adoc | 38 +++++---- asciidoc/settings/caches.adoc | 7 +- asciidoc/settings/caches/cache.adoc | 8 +- asciidoc/settings/caches/ttl.adoc | 4 +- asciidoc/settings/classpath.adoc | 2 +- asciidoc/settings/conflict-managers.adoc | 4 +- asciidoc/settings/latest-strategies.adoc | 8 +- asciidoc/settings/macrodef.adoc | 4 +- asciidoc/settings/module.adoc | 4 +- asciidoc/settings/namespace.adoc | 2 +- asciidoc/settings/namespace/src.adoc | 2 +- asciidoc/settings/outputters.adoc | 4 +- asciidoc/settings/parsers.adoc | 12 +-- asciidoc/settings/properties.adoc | 4 +- asciidoc/settings/property.adoc | 2 +- asciidoc/settings/resolvers.adoc | 38 ++++----- asciidoc/settings/settings.adoc | 12 +-- asciidoc/settings/signers.adoc | 4 +- asciidoc/settings/statuses.adoc | 8 +- asciidoc/settings/timeout-constraint.adoc | 8 +- asciidoc/settings/triggers.adoc | 12 +-- asciidoc/settings/typedef.adoc | 2 +- asciidoc/standalone.adoc | 12 +-- asciidoc/terminology.adoc | 4 +- asciidoc/textual.adoc | 4 +- asciidoc/toc.json | 49 +++++------- asciidoc/tutorial.adoc | 8 +- asciidoc/tutorial/build-repository.adoc | 10 +-- .../tutorial/build-repository/advanced.adoc | 16 ++-- asciidoc/tutorial/build-repository/basic.adoc | 24 +++--- asciidoc/tutorial/conf.adoc | 16 ++-- asciidoc/tutorial/defaultconf.adoc | 10 +-- asciidoc/tutorial/dependence.adoc | 44 +++++------ asciidoc/tutorial/dual.adoc | 46 +++++------ asciidoc/tutorial/multiple.adoc | 12 +-- asciidoc/tutorial/multiproject.adoc | 37 ++++----- asciidoc/tutorial/start.adoc | 17 ++-- asciidoc/use/artifactproperty.adoc | 14 ++-- asciidoc/use/artifactreport.adoc | 10 +-- asciidoc/use/buildlist.adoc | 36 ++++----- asciidoc/use/buildnumber.adoc | 10 +-- asciidoc/use/buildobr.adoc | 22 +++--- asciidoc/use/cachefileset.adoc | 12 +-- asciidoc/use/cachepath.adoc | 6 +- asciidoc/use/checkdepsupdate.adoc | 4 +- asciidoc/use/cleancache.adoc | 4 +- asciidoc/use/configure.adoc | 14 ++-- asciidoc/use/convertpom.adoc | 6 +- asciidoc/use/deliver.adoc | 26 +++---- asciidoc/use/dependencytree.adoc | 6 +- asciidoc/use/findrevision.adoc | 8 +- asciidoc/use/fixdeps.adoc | 6 +- asciidoc/use/info.adoc | 42 +++++----- asciidoc/use/install.adoc | 10 +-- asciidoc/use/listmodules.adoc | 8 +- asciidoc/use/makepom.adoc | 28 +++---- asciidoc/use/postresolvetask.adoc | 24 +++--- asciidoc/use/publish.adoc | 22 +++--- asciidoc/use/report.adoc | 24 +++--- asciidoc/use/repreport.adoc | 28 +++---- asciidoc/use/resolve.adoc | 48 ++++++------ asciidoc/use/resources.adoc | 2 +- asciidoc/use/retrieve.adoc | 18 ++--- asciidoc/use/settings.adoc | 18 ++--- asciidoc/use/var.adoc | 10 +-- asciidoc/yed.adoc | 8 +- 122 files changed, 806 insertions(+), 840 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ant.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ant.adoc b/asciidoc/ant.adoc index bbb3291..7975537 100644 --- a/asciidoc/ant.adoc +++ b/asciidoc/ant.adoc @@ -17,11 +17,11 @@ under the License. //// -The main and most frequent way to use Ivy is from an Ant build file. However, Ivy can also be called as a standalone application +The main and most frequent way to use Ivy is from an Ant build file. However, Ivy can also be run as a standalone application. -If you use ant version *1.6.0* or superior, you just have to add Ivy's namespace to your project (`xmlns:ivy="antlib:org.apache.ivy.ant"` attribute of your project tag), and you can call Ivy tasks. +If you use Ant version *1.6.0* or superior, you just have to add Ivy's namespace to your project (`xmlns:ivy="antlib:org.apache.ivy.ant"` attribute of your project tag), and you can call Ivy tasks. -If you want to make your build handle ivy.jar in either ant lib dir or a local lib dir, you can use a taskdef like this: +If you want to make your build handle ivy.jar in either Ant lib dir or a local lib dir, you can use a taskdef like this: [source,xml] ---- @@ -32,9 +32,9 @@ If you want to make your build handle ivy.jar in either ant lib dir or a local l uri="antlib:org.apache.ivy.ant" classpathref="ivy.lib.path"/> ---- -Combined with the antlib definition in the project namespace, it will load Ivy classes either from your ant lib or a local directory (`path/to/dir/with/ivy/jar` in this example). +Combined with the antlib definition in the project namespace, it will load Ivy classes either from your Ant lib or a local directory (`path/to/dir/with/ivy/jar` in this example). -If you use ant *1.5.1* or superior, you have to define the tasks you use in your build file. For instance: +If you use Ant *1.5.1* or superior, you have to define the tasks you use in your build file. For instance: [source,xml] ---- @@ -45,22 +45,22 @@ If you use ant *1.5.1* or superior, you have to define the tasks you use in your <taskdef name="ivy-publish" classname="org.apache.ivy.ant.IvyPublish"/> ---- -_Note_: the tasks listed above are non exhaustive. For a complete list of tasks with the corresponding classes, see the link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/java/org/apache/ivy/ant/antlib.xml[antlib.xml] file in git or the version you use. +_Note_: the tasks listed above are non exhaustive. For a complete list of tasks with the corresponding classes, see the link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/java/org/apache/ivy/ant/antlib.xml[antlib.xml] file in Git repository or the jar file you use. -Then you can use the tasks, but check their name, following samples assume you use the ivy namespace (ivy:xxx tasks), whereas with ant 1.5 you cannot use namespace, and should therefore use ivy-xxx tasks if you have followed the taskdefs above. +Then you can use the tasks, but check their name, following samples assume you use the Ivy namespace (ivy:xxx tasks), whereas with Ant 1.5 you cannot use namespace, and should therefore use ivy-xxx tasks if you have added the taskdefs as above. -If you use an ant version lower than 1.5.1, you can not use the ivy tasks... you should then call ivy as any external program. +If you use an Ant version lower than 1.5.1, you can not use the Ivy tasks... you should then run Ivy as any external program. -== Calling ivy from ant: first steps +== Calling Ivy from Ant: first steps -Once your build file is ok to call ivy tasks, the simplest way to use ivy is to call the ivy retrieve task with no parameters: +Once your build file is ok to call Ivy tasks, the simplest way to use Ivy is to call the Ivy retrieve task with no parameters: [source,xml] ---- <ivy:retrieve/> ---- -This calls ivy with default values, which might be ok in several projects. In fact, it is equivalent to: +This calls Ivy with default values, which might be ok in several projects. In fact, it is equivalent to: [source,xml] ---- @@ -73,13 +73,13 @@ This calls ivy with default values, which might be ok in several projects. In fa </target> ---- -Those 3 tasks follow the 3 main steps of the 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 link:settings.html[xml settings file]. -* Then the resolve task actually resolves dependencies described by an link:ivyfile.html[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. +* First the configure task tells it how it can find dependencies giving it a path to an link:settings.html[settings XML file]. +* Then the resolve task actually resolves dependencies described by an link:ivyfile.html[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. -To understand more accurately the behaviour of ivy tasks, one should know that a property file is loaded in ant by ivy at the beginning of the configure call. This property file contains the following properties: +To understand more accurately the behaviour of Ivy tasks, one should know that a property file is loaded in Ant by Ivy at the beginning of the configure call. This property file contains the following properties: [source] ---- @@ -107,22 +107,22 @@ ivy.buildlist.ivyfilepath = ivy.xml ivy.checksums=sha1,md5 ---- -_For the latest version of these properties, you can check the link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/java/org/apache/ivy/core/settings/ivy.properties[git version]._ +_For the latest version of these properties, you can check the link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/java/org/apache/ivy/core/settings/ivy.properties[Git version]._ *__since 2.0__* After calling the first Ivy task, the property `ivy.version` will be available and contains the version of the used Ivy library. == Ivy tasks attributes : generalities -Some tasks attributes values may be given through different places. The three possible places are : +Some tasks attributes values may be set in different places. The three possible places are : . task attribute -. ivy instance +. Ivy instance . project property -The places are queried in this order, so anything set in task attribute will overwrite what would have been found in ivy instance, for example. +The places are queried in this order, so anything set in task attribute will override what would have been found in Ivy instance, for example. -The Ivy instance considered here is an instance of the class `Ivy`, which is setup by a call to the configure task, and then reused for other tasks. Because most of the tasks need an Ivy instance, they first check if one is available (i.e. configure has been called), and if none is available, then a default configure is called and the resulting Ivy instance is used in the remaining tasks (unless another configure is called). +The Ivy instance considered here is an instance of the class `Ivy`, which is set up by a call to the configure task, and then reused for other tasks. Because most of the tasks need an Ivy instance, they first check if one is available (i.e. configure has been called), and if none is available, then a default configure is called and the resulting Ivy instance is used in the remaining tasks (unless another configure is called). It isn't generally necessary to understand this, but it can lead to some issues if you forget to call configure before another task and if the configure step was required in your environment. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/bestpractices.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/bestpractices.adoc b/asciidoc/bestpractices.adoc index ef86a02..47eb959 100644 --- a/asciidoc/bestpractices.adoc +++ b/asciidoc/bestpractices.adoc @@ -31,7 +31,7 @@ Therefore we recommend adding ivy files for all the modules in your repository. == 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: +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 @@ -59,7 +59,7 @@ Ivy is very flexible and can accommodate a lot of existing repositories, using t == 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. +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, (s)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 settings file, which makes it really easy to combine several public repositories. == Dealing with integration versions @@ -72,7 +72,7 @@ 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. +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. @@ -110,7 +110,7 @@ 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! +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 settings 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 http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/compatibility.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/compatibility.adoc b/asciidoc/compatibility.adoc index 6f2881d..f51b96d 100644 --- a/asciidoc/compatibility.adoc +++ b/asciidoc/compatibility.adoc @@ -31,8 +31,8 @@ Ivy doesn't require a specific version of Ant as long as the Ant being used comp == 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. +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/614bf1ad/asciidoc/concept.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/concept.adoc b/asciidoc/concept.adoc index 02aaeaa..37801c3 100644 --- a/asciidoc/concept.adoc +++ b/asciidoc/concept.adoc @@ -46,29 +46,28 @@ For details on how to declare your module configurations, how to declare in whic == [[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. +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 settings 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. +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*. +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 link:ant.html[Ant Tasks]), 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, 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 link:ant.html[Ant Tasks]), 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. +Moreover, it's also important to understand the difference between Ivy variables and Ivy pattern tokens. 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. +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: +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]` This pattern indicates that the repository we use is in a directory called myrepository. @@ -118,7 +117,7 @@ the configuration name *__(since 1.4)__* + the original artifact name (including the extension) -The difference between type and extension is explained in the 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]`. @@ -142,7 +141,7 @@ The pattern `[artifact](-[revision]).[ext]` lets you accept both `myartifact-1.0 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 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. +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. @@ -184,7 +183,7 @@ Ivy uses a pluggable pattern matcher to match those object names. 3 are defined 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 +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. @@ -194,13 +193,13 @@ Note also that with any matcher, the character '*' has the special meaning of ma == [[extra]]Extra attributes *__since 1.4__* -Several tags in ivy xml files are extensible with what is called extra attributes. +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. *__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,xml] ---- @@ -214,8 +213,7 @@ Example: here is an ivy file with the attribute `color` set to blue: </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,xml] ---- @@ -323,7 +321,7 @@ In this case, setting `checkModified="true"` on your dependency resolver will be ==== 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. +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. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/dev.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/dev.adoc b/asciidoc/dev.adoc index 7bafddf..52ae1ae 100644 --- a/asciidoc/dev.adoc +++ b/asciidoc/dev.adoc @@ -26,13 +26,13 @@ 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_ +_to check out Ivy sources from Apache svn, not required if you build from sources packaged in a release_ * link:http://ant.apache.org/[Apache Ant] 1.6.0 or greater + -_We recommend either ant 1.6.5 or 1.7.0_ +_We recommend either Ant 1.6.5 or 1.7.0_ -* link:http://junit.org[junit] 3.8.2 jar in your ant lib + -_ this is not required if you use ant 1.7_ +* link:http://junit.org[junit] 3.8.2 jar in your Ant lib + +_ 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_ @@ -59,7 +59,7 @@ 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. +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: @@ -72,21 +72,21 @@ Then you can check the test results in the build/doc/reports/test directory, the == Coding conventions -The Ivy code base is supposed to follow the standard java conventions: +The Ivy code base is supposed to follow the standard Java conventions: 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. +Even though you can develop Ivy with your IDE of choice, we support Eclipse development by providing ad hoc metadata. We currently provide two options: === Eclipse alone -To develop with a simple eclipse install all you need is eclipse 3.1 or greater, with no particular plugin. -First call the following ant target in your Ivy workspace: +To develop with a simple Eclipse install all you need is Eclipse 4.2 or greater, with no particular plugin. +First call the following Ant target in your Ivy workspace: [source] ---- @@ -98,25 +98,25 @@ Then you can use the "Import->Existing project into workspace" eclipse feature t === Eclipse + IvyDE -You can also leverage the latest IvyDE version to be able to easily resolve the ivy dependencies from Eclipse. -To do so all you need is call the following ant target in your Ivy workspace: +You can also leverage the latest IvyDE version to be able to easily resolve the Ivy dependencies from Eclipse. +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 +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: https://builds.apache.org/view/A/view/Ant/job/IvyDE/ -Download the file and unzip its content in your eclipse installation directory. +Download the file and unzip its content in your Eclipse installation directory. === 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. +The Ivy project comes with settings for the link:http://eclipse-cs.sourceforge.net/[Checkstyle plugin] we recommend to use to avoid introducing a new digression to the Checkstyle rules we use. +If you use this plugin, you will see 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. Besides this plugin we also recommend to use a subversion plugin, link:http://www.eclipse.org/subversive/[subversive] or link:http://subclipse.tigris.org[subclipse] being the two options currently available in the open source landscape. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/dev/makerelease.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/dev/makerelease.adoc b/asciidoc/dev/makerelease.adoc index 248fa2a..e44a075 100644 --- a/asciidoc/dev/makerelease.adoc +++ b/asciidoc/dev/makerelease.adoc @@ -72,7 +72,7 @@ If the release script is successful, release artifacts will be waiting for you i ==== 5. Verify the release 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). +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 @@ -117,7 +117,7 @@ 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: +Having your GPG key ID, its password, your apache ID and the associated password, just launch Ant and enter the information as required: [source,shell] ---- @@ -164,7 +164,7 @@ The svn tag of this release is: https://git-wip-us.apache.org/repos/asf?p=ant-iv The artifacts has been published to: https://dist.apache.org/repos/dist/dev/ant/ivy/$VERSION at revision ${svn-rev-of-the-check-in} -The staging maven repository is availble there: https://repository.apache.org/content/repositories/orgapacheant-XXXX +The staging Maven repository is available there: https://repository.apache.org/content/repositories/orgapacheant-XXXX The Eclipse updatesite has been build there: https://dist.apache.org/repos/dist/dev/ant/ivyde/updatesite/ivy-2.0.0.beta1_20141213170938/ http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/extend.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/extend.adoc b/asciidoc/extend.adoc index 9783b03..0077ebf 100644 --- a/asciidoc/extend.adoc +++ b/asciidoc/extend.adoc @@ -17,7 +17,7 @@ under the License. //// -Many things are configurable in Ivy, and many things are available with Ivy core. But when you want to do something not built in ivy core, you can still plug your own code. +Many things are configurable in Ivy, and many things are available with Ivy core. But when you want to do something not built in Ivy core, you can still plug your own code. Many things are pluggable in Ivy: @@ -31,11 +31,11 @@ Many things are pluggable in Ivy: * 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. +Before trying to implement your own, we encourage you to check if the solution to your problem can 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/614bf1ad/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/index.adoc b/asciidoc/index.adoc index f450274..60d14c5 100644 --- a/asciidoc/index.adoc +++ b/asciidoc/index.adoc @@ -29,9 +29,9 @@ Ivy is a tool for managing (recording, tracking, resolving and reporting) projec 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. +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]. +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 @@ -69,8 +69,8 @@ The tutorials is the best way to begin to play with Ivy. You will easily and qui 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). +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]:: -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. +The developer 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/614bf1ad/asciidoc/install.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/install.adoc b/asciidoc/install.adoc index bfa871a..f6af73d 100644 --- a/asciidoc/install.adoc +++ b/asciidoc/install.adoc @@ -21,11 +21,11 @@ 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: +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"` - add taskdefs for ivy tasks: @@ -49,7 +49,7 @@ One of the two binary versions of Ivy doesn't include the optional dependencies. == 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: +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,xml] ---- @@ -71,10 +71,10 @@ If you want to use Ivy only in your ant build scripts, and have an internet conn </target> <target name="init-ivy" depends="download-ivy"> - <!-- try to load ivy here from ivy home, in case the user has not already dropped - it into ant's lib dir (note that the latter copy will always take precedence). + <!-- try to load Ivy here from Ivy home, in case the user has not already dropped + it into Ant's lib dir (note that the latter copy will always take precedence). We will not fail as long as local lib dir exists (it may be empty) and - ivy is in at least one of ant's lib dir or the local lib dir. --> + Ivy is in at least one of Ant's lib dir or the local lib dir. --> <path id="ivy.lib.path"> <fileset dir="${ivy.jar.dir}" includes="*.jar"/> http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile.adoc b/asciidoc/ivyfile.adoc index 9bc46ab..0585076 100644 --- a/asciidoc/ivyfile.adoc +++ b/asciidoc/ivyfile.adoc @@ -17,9 +17,9 @@ under the License. //// -Ivy use is entirely based on _module descriptors_ known as "ivy files". Ivy files are xml files, usually called ivy.xml, containing the description of the dependencies of a module, its published artifacts and its configurations. +Ivy use is entirely based on _module descriptors_ known as "Ivy files". Ivy files are XML files, usually called ivy.xml, containing the description of the dependencies of a module, its published artifacts and its configurations. -Here is the simplest ivy file you can write: +Here is the simplest Ivy file you can write: [source,xml] ---- @@ -29,11 +29,11 @@ Here is the simplest ivy file you can write: </ivy-module> ---- -If you want to see a sample module descriptor using almost all possibilities of ivy files, check this one, link:samples/ivy-sample-xslt.xml[with] or link:samples/ivy-sample.xml[without] xslt. +If you want to see a sample module descriptor using almost all possibilities of Ivy files, check this one, link:samples/ivy-sample-xslt.xml[with] or link:samples/ivy-sample.xml[without] XSLT. Before beginning the reference itself, it is required to have in mind the terminology defined in the link:reference.html[main page] of this reference documentation. -For those familiar with xml schema, the schema used to validate ivy files can be found link:http://ant.apache.org/ivy/schemas/ivy.xsd[here]. For those using xsd aware IDE, you can declare the xsd in your ivy files to benefit from code completion / validation: +For those familiar with XML schema, the schema used to validate Ivy files can be found link:http://ant.apache.org/ivy/schemas/ivy.xsd[here]. For those using XSD aware IDE, you can declare the XSD in your Ivy files to benefit from code completion / validation: [source,xml] ---- @@ -47,21 +47,21 @@ For those familiar with xml schema, the schema used to validate ivy files can be </ivy-module> ---- -== Dynamic and [[resolved]]resolved ivy files +== Dynamic and [[resolved]]resolved Ivy files -A module descriptor (ivy file) is needed both before and after the publication of each revision of the module. Depending on the case, a module descriptor can be either _dynamic_ or _resolved_. +A module descriptor (Ivy file) is needed both before and after the publication of each revision of the module. Depending on the case, a module descriptor can be either _dynamic_ or _resolved_. === Dynamic descriptor for module development -During the module development time, between publications, the descriptor helps in managing all the possibly changing dependencies of the module. For that purpose, development time ivy files can declare dynamic dependencies to allow for a greater flexibility of use. link:ivyfile/dependency.html#revision[Dynamic revision] references like `latest.integration` or `1.0.+` are possible and may resolve to different artifacts at different times. Variables can be used for even more flexibility. Development time ivy files are hence called _dynamic_, because they can produce different results over time. The dynamic ivy files are normally considered source files and kept with them (under SCM control). +During the module development time, between publications, the descriptor helps in managing all the possibly changing dependencies of the module. For that purpose, development time Ivy files can declare dynamic dependencies to allow for a greater flexibility of use. link:ivyfile/dependency.html#revision[Dynamic revision] references like `latest.integration` or `1.0.+` are possible and may resolve to different artifacts at different times. Variables can be used for even more flexibility. Development time Ivy files are hence called _dynamic_, because they can produce different results over time. The dynamic Ivy files are normally considered source files and kept with them (under SCM control). === Resolved descriptors for publishing -At each publication, another kind of a module descriptor is needed to document the dependencies of the particular published revision of the module. For that purpose, the descriptor usually needs to be fixed as its dependencies should no longer change. In doing so, the published module revision gets fixed, explicitly resolved dependencies. No variables are allowed either. Such publication-friendly, static ivy files are called _resolved_, because they should always produce the same results. The resolved ivy files are comparable to published artifacts and are kept with them in a repository. +At each publication, another kind of a module descriptor is needed to document the dependencies of the particular published revision of the module. For that purpose, the descriptor usually needs to be fixed as its dependencies should no longer change. In doing so, the published module revision gets fixed, explicitly resolved dependencies. No variables are allowed either. Such publication-friendly, static Ivy files are called _resolved_, because they should always produce the same results. The resolved Ivy files are comparable to published artifacts and are kept with them in a repository. -Resolved ivy files are generated from their original dynamic ivy files via the link:use/deliver.html[deliver] task. +Resolved Ivy files are generated from their original dynamic Ivy files via the link:use/deliver.html[deliver] task. -Note that although it is technically possible to publish module revisions with dynamic ivy files, it is not a generally recommended practice. +Note that although it is technically possible to publish module revisions with dynamic Ivy files, it is not a generally recommended practice. == Hierarchical Index @@ -96,14 +96,14 @@ Note that although it is technically possible to publish module revisions with d *Tag:* ivy-module -The root tag of any ivy file (module descriptor). +The root tag of any Ivy file (module descriptor). === Attributes [options="header",cols="15%,50%,35%"] |======= |Attribute|Description|Required -|version|the version of the ivy file specification - should be '2.0' with current version of ivy|Yes +|version|the version of the Ivy file specification - should be '2.0' with current version of Ivy|Yes |======= === Child elements http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile/artifact-exclude.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/artifact-exclude.adoc b/asciidoc/ivyfile/artifact-exclude.adoc index 7269c6d..772535c 100644 --- a/asciidoc/ivyfile/artifact-exclude.adoc +++ b/asciidoc/ivyfile/artifact-exclude.adoc @@ -19,15 +19,14 @@ *Tag:* exclude *Parent:* link:../ivyfile/dependency.html[dependency] -This feature gives you more control on a dependency for which you do not control its ivy file. -It enables to restrict the artifacts required, by excluding artifacts being published by the dependency or any of its transitive dependencies, -even if configuration does not a good separation of published artifacts +This feature gives you more control on a dependency for which you do not control its Ivy file. +It enables to restrict the artifacts required, by excluding artifacts being published by the dependency or any of its transitive dependencies, even if configuration does not provide a good separation of published artifacts. The same principle concerning configuration as for include applies to this exclude feature (see the link:../ivyfile/dependency-include.html[include] feature). Note that exclusion is always done AFTER inclusion has been done. -*__since 1.3__* This exclude feature can also be used not only to exclude artifacts but also to exclude whole modules. Indeed when you exclude artifacts, it doesn't avoid ivy to search for the module itself, and to resolve the dependencies of the module. But you can also exclude the whole module, which means that the module will not be downloaded at all, and so its own dependencies will not be resolved. For sure, this is usually done to exclude not a direct dependency but an indirect one. To exclude a whole module, you just have to not specify any artifact name, type and ext in your exclude rule. For instance: +*__since 1.3__* This exclude feature can also be used not only to exclude artifacts but also to exclude whole modules. Indeed when you exclude artifacts, it doesn't prevent Ivy from searching for the module itself, and resolving the dependencies of the module. But you can also exclude the entire module, which means that the module will not be downloaded at all, and so its own dependencies will not be resolved. For sure, this is usually done to exclude not a direct dependency but an indirect one. To exclude a whole module, you just have to not specify any artifact name, type and ext in your exclude rule. For instance: [source,xml] ---- @@ -48,7 +47,7 @@ Note that exclusion is always done AFTER inclusion has been done. |name|the name of an artifact of the dependency module to add to the exclude list, or an expression matching this name (see `matcher` attribute below)|No, defaults to `$$*$$` |type|the type of the artifact of the dependency module to add to the exclude list, or a regexp matching this name|No, defaults to `$$*$$` |ext|the extension of the artifact of the dependency module to add to the exclude list, or an expression matching this name (see `matcher` attribute below)|No, defaults to the value of `type` -|matcher|the link:../concept.html#matcher[matcher] to use to match the modules to excludes *__since 1.3__*|No, defaults to `exactOrRegexp` in pre 1.3 ivy files, and `exact` in 1.3 and superior +|matcher|the link:../concept.html#matcher[matcher] to use to match the modules to excludes *__since 1.3__*|No, defaults to `exactOrRegexp` in pre 1.3 Ivy files, and `exact` in 1.3 and superior |conf|comma separated list of the master configurations in which this artifact should be excluded. `$$*$$` wildcard can be used to designate all configurations of this module|No, defaults to `$$*$$`, unless nested conf are specified http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile/artifact.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/artifact.adoc b/asciidoc/ivyfile/artifact.adoc index e4ebb2e..931aa34 100644 --- a/asciidoc/ivyfile/artifact.adoc +++ b/asciidoc/ivyfile/artifact.adoc @@ -48,12 +48,12 @@ If this is the only artifact declared, then it's equivalent to having no publica |======= |Attribute|Description|Required |name|the name of the published artifact. This name must not include revision.|No, defaults to the name of the module -|type|the type of the published artifact. It's usually its extension, but not necessarily. For instance, ivy files are of type `ivy` but have `xml` extension|No, defaults to `jar` +|type|the type of the published artifact. It's usually its extension, but not necessarily. For instance, Ivy files are of type `ivy` but have `xml` extension|No, defaults to `jar` |ext|the extension of the published artifact|No, defaults to the value of `type` |conf|comma separated list of public configurations in which this artifact is published. `$$*$$` wildcard can be used to designate all public configurations of this module|No, defaults to `defaultconf` attribute value on parent publications element. -|url|a url at which this artifact can be found if it isn't located at the standard location in the repository *__since 1.4__*|No, defaults to no url +|url|an URL at which this artifact can be found if it isn't located at the standard location in the repository *__since 1.4__*|No, defaults to no URL |packaging|a comma separated list of link:../concept.html#packaging[packaging] types *__since 2.4__*|No, defaults to no packaging |======= @@ -90,4 +90,4 @@ Declares an artifact `foo-src`, of type `source` with extension `zip`, and publi <artifact name="foo" url="http://www.acme.com/repository/barbaz/foo-1.2-bar.jar"/> ---- -Declares an artifact `foo`, of type and extension `jar'` located at the url `$$http://www.acme.com/repository/barbaz/foo-1.2-bar.jar$$`. This url will only be used if the artifact cannot be found at its standard location. +Declares an artifact `foo`, of type and extension `jar'` located at the URL `$$http://www.acme.com/repository/barbaz/foo-1.2-bar.jar$$`. This URL will only be used if the artifact cannot be found at its standard location. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile/conf.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/conf.adoc b/asciidoc/ivyfile/conf.adoc index abe1067..1d7aa01 100644 --- a/asciidoc/ivyfile/conf.adoc +++ b/asciidoc/ivyfile/conf.adoc @@ -19,7 +19,7 @@ *Tag:* conf *Parent:* link:../ivyfile/configurations.html[configurations] -Declares a configuration of this module. As described in the reference page, a configuration is a way to use or construct a module. 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 different ways to use or build a module are called in Ivy module configurations. +Declares a configuration of this module. As described in the reference page, a configuration is a way to use or construct a module. 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 different ways to use or build a module are called module configurations in Ivy. The `conf` element in the configurations section declares one configuration. This declaration gives the name of the configuration declared, its visibility and the other configurations of the module it extends. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile/configurations.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/configurations.adoc b/asciidoc/ivyfile/configurations.adoc index 6409062..f979688 100644 --- a/asciidoc/ivyfile/configurations.adoc +++ b/asciidoc/ivyfile/configurations.adoc @@ -21,13 +21,13 @@ A container for configuration elements. If this container is not present, it is assumed that the module has one public configuration called `default`. -*__since 2.2__* You can define the default conf on this container by specifying the `defaultconf` attribute. This attribute defines the conf mapping to use when no conf mapping is specified for a dependency in this ivy file. +*__since 2.2__* You can define the default conf on this container by specifying the `defaultconf` attribute. This attribute defines the conf mapping to use when no conf mapping is specified for a dependency in this Ivy file. *__since 1.3__* You can define a default conf mapping on this container by specifying the `defaultconfmapping` attribute. This attribute modifies the way Ivy interprets conf mapping with no mapped conf. In this case, Ivy will look in the default conf mapping and use the conf mapping defined in the default conf mapping for the conf for which there is no mapped conf. -In order to maintain backwards compatibility with Ivy 2.1.0 and earlier, the `defaultconfmapping` also provides one additional function. If no `defaultconf` is specified (on either the configurations tag or the dependencies tag), the `defaultconfmapping` becomes the default configuration for dependencies in this ivy file when no configuration is specified. In other words, in addition to altering the interpretation of individual configurations with no mapping, `defaultconfmapping` also performs exactly like `defaultconf` in the absence of a definition for `defaultconf`. +In order to maintain backwards compatibility with Ivy 2.1.0 and earlier, the `defaultconfmapping` also provides one additional function. If no `defaultconf` is specified (on either the configurations tag or the dependencies tag), the `defaultconfmapping` becomes the default configuration for dependencies in this Ivy file when no configuration is specified. In other words, in addition to altering the interpretation of individual configurations with no mapping, `defaultconfmapping` also performs exactly like `defaultconf` in the absence of a definition for `defaultconf`. If several `defaultconfmapping` or `defaultconf` attributes are defined (in the configurations tag, one or several in an included configurations file, and/or in the dependency tag, then it's only the last definition of each property which is taken into account. The others will have no effect at all. @@ -40,8 +40,8 @@ See link:#defaultconfmapping[examples below] to clarify the behavior of these tw [options="header",cols="15%,50%,35%"] |======= |Attribute|Description|Required -|defaultconf|the default conf to use in this ivy file *__since 2.2__*|No, defaults to no default conf -|defaultconfmapping|the default conf mapping to use in this ivy file *__since 1.3__*|No, defaults to no default conf mapping +|defaultconf|the default conf to use in this Ivy file *__since 2.2__*|No, defaults to no default conf +|defaultconfmapping|the default conf mapping to use in this Ivy file *__since 1.3__*|No, defaults to no default conf mapping |confmappingoverride|`true` to activate configuration mapping override, `false` otherwise *__since 1.4__*|No, defaults to `false` |======= @@ -95,7 +95,7 @@ The table below indicates how Ivy interprets the conf attribute according to how [options="header",cols="15%,40%,15%,30%"] |======= -|defaultconf|defaultconfmapping|conf|ivy interpretation +|defaultconf|defaultconfmapping|conf|Ivy interpretation | | | |`$$*->*$$` | | |`runtime`|`$$runtime->runtime$$` | | |`test`|`$$test->test$$` http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile/conflict.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/conflict.adoc b/asciidoc/ivyfile/conflict.adoc index f2dd7a1..04cb0ba 100644 --- a/asciidoc/ivyfile/conflict.adoc +++ b/asciidoc/ivyfile/conflict.adoc @@ -26,14 +26,12 @@ The way to specify a conflict manager is by giving indication to which dependenc The list of built-in conflict managers available is listed on the link:../settings/conflict-managers.html[conflict manager configuration page]. -Conflicts manager are used during the resolve operation, i.e. when ivy analyse the graph of dependencies and download corresponding ivy files and artifacts. The fact to manage conflict at resolve time enables to minimize downloads: when a module is evicted by a conflict manager, it is not downloaded. +Conflicts manager are used during the resolve operation, i.e. when Ivy analyse the graph of dependencies and download corresponding Ivy files and artifacts. The fact to manage conflict at resolve time enables to minimize downloads: when a module is evicted by a conflict manager, it is not downloaded. -There are two things optimized during conflict resolution: download of artifacts and download of ivy files. The first is always ensured by ivy, i.e. artifacts of a module evicted will never be downloaded. The second is not as simple to handle because to know what are the conflicts ivy needs to know the dependency graph, and to know the dependency graph, it has to download ivy files. But ivy is highly optimized on this too, and it tries to evict modules as soon as possible. -That's why the order of dependencies is important for download optimization. Indeed ivy traverses the dependency graph in the order in which dependencies are declared in the ivy files, and each time it encounters a dependency on a module, it first check if there is a conflict on this module, and if this is the case, it asks the conflict manager to resolve the conflict. Then if the module is evicted, it does not download its ivy file, and the whole branch is not traversed, which can saves a lot of time. +There are two things optimized during conflict resolution: download of artifacts and download of Ivy files. The first is always ensured by Ivy, i.e. artifacts of a module evicted will never be downloaded. The second is not as simple to handle because in order to know what the conflicts are, Ivy needs to know the dependency graph, and in order to know the dependency graph, it has to download Ivy files. But Ivy is highly optimized for this too, and it tries to evict modules as soon as possible. +That's why the order of dependencies is important for download optimization. Indeed, Ivy traverses the dependency graph in the order in which dependencies are declared in the Ivy files, and each time it encounters a dependency on a module, it first checks if there is a conflict on this module, and if this is the case, it asks the conflict manager to resolve the conflict. Then if the module is evicted, it does not download its Ivy file, and the whole branch is not traversed, which can saves a lot of time. -If no specific conflict manager is defined, a default conflict manager is used for all modules. - -The current default conflict manager is the `latest-revision` conflict manager. +If no specific conflict manager is defined, a default conflict manager is used for all modules. The current default conflict manager is the `latest-revision` conflict manager. == Attributes http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile/conflicts.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/conflicts.adoc b/asciidoc/ivyfile/conflicts.adoc index d0622fd..e917875 100644 --- a/asciidoc/ivyfile/conflicts.adoc +++ b/asciidoc/ivyfile/conflicts.adoc @@ -19,32 +19,30 @@ *Tag:* conflicts *Parent:* link:../ivyfile.html[ivy-module] -*__(since 2.0)__* the conflicts section is deprecated. Use the link:../ivyfile/conflict.html[conflict] instead. +*__(since 2.0)__* the conflicts section is deprecated. Use link:../ivyfile/conflict.html[conflict] instead. -Container for conflict manager elements, used to indicate how conflicts should be resolved -for this module. +Container for conflict manager elements, used to indicate how conflicts should be resolved for this module. -The list of built-in conflict managers available is listed on the link:../settings/conflict-managers.html[conflict manager configuration page]. +The list of built-in conflict managers available is listed on the link:../settings/conflict-managers.html[conflict manager settings page]. -Conflicts manager are used during the resolve operation, i.e. when ivy analyse the graph of dependencies -and download corresponding ivy files and artifacts. The fact to manage conflict at resolve time +Conflicts manager are used during the resolve operation, i.e. when Ivy analyses the graph of dependencies +and download corresponding Ivy files and artifacts. The fact to manage conflict at resolve time enables to minimize downloads: when a module is evicted by a conflict manager, it is not downloaded. There are two things optimized during conflict resolution: download of artifacts and download -of ivy files. The first is always ensured by ivy, i.e. artifacts of a module evicted will never -be downloaded. The second is not as simple to handle because to know what are the conflicts -ivy needs to know the dependency graph, and to know the dependency graph, it has to download -ivy files. But ivy is highly optimized on this too, and it tries to evict modules as soon as possible. +of Ivy files. The first is always ensured by Ivy, i.e. artifacts of a module evicted will never +be downloaded. The second is not as simple to handle because in order to know what the conflicts are +Ivy needs to know the dependency graph, and in order to know the dependency graph, it has to download +Ivy files. But Ivy is highly optimized for this too, and it tries to evict modules as soon as possible. -That's why the order of dependencies is important for download optimization. Indeed ivy -traverses the dependency graph in the order in which dependencies are declared in the ivy files, +That's why the order of dependencies is important for download optimization. Indeed Ivy +traverses the dependency graph in the order in which dependencies are declared in the Ivy files, and each time it encounters a dependency on a module, it first check if there is a conflict on this module, and if this is the case, it asks the conflict manager to resolve the conflict. Then if the module is evicted, -it does not download its ivy file, and the whole branch is not traversed, which can saves +it does not download its Ivy file, and the whole branch is not traversed, which can saves a lot of time. -If this container is not present, a default conflict manager is used for all modules. -The current default conflict manager is the `latest-revision` conflict manager. +If this container is not present, a default conflict manager is used for all modules. The current default conflict manager is the `latest-revision` conflict manager. == Child elements http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile/dependencies.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/dependencies.adoc b/asciidoc/ivyfile/dependencies.adoc index 7085ac9..5c4b30f 100644 --- a/asciidoc/ivyfile/dependencies.adoc +++ b/asciidoc/ivyfile/dependencies.adoc @@ -22,7 +22,7 @@ Container for dependency elements, used to describe the dependencies of this module. If this container is not present, it is assumed that the module has no dependency at all. -This container provides for two similar behaviors. An overview is given here. (See link:../ivyfile/configurations.html[configurations doc page] for more details about these behaviors). +This container provides two similar behaviors described below. (See link:../ivyfile/configurations.html[configurations doc page] for more details about these behaviors). *__since 1.1__* `defaultconf` defines the `conf` attribute to use when no conf is defined for a dependency in this ivy file. It is only used when no conf mapping is defined, and has no influence in other cases. @@ -36,14 +36,14 @@ In Ivy 2.1.0 and earlier, if both `defaultconf` and `defaultconfmapping` are def |======= |Attribute|Description|Required |defaultconf|the default configuration to use when none is specified in a dependency. *__since 1.1__*|No, defaults to `$$*->*$$` -|defaultconfmapping|the default configuration mapping to use in this ivy file. *__since 1.3__*|No, defaults to no default conf mapping +|defaultconfmapping|the default configuration mapping to use in this Ivy file. *__since 1.3__*|No, defaults to no default conf mapping |======= == Child elements -Note: as specified by the ivy.xsd, the children elements are ordered; must come first the `link:../ivyfile/dependency.html[dependency]` elements, then the `link:../ivyfile/exclude.html[exclude]` elements, then the `link:../ivyfile/override.html[override]` elements, and then the `link:../ivyfile/conflict.html[conflict]` elements. +Note: as specified by the ivy.xsd, the children elements are ordered; first must come the `link:../ivyfile/dependency.html[dependency]` elements, then the `link:../ivyfile/exclude.html[exclude]` elements, then the `link:../ivyfile/override.html[override]` elements, and then the `link:../ivyfile/conflict.html[conflict]` elements. [options="header",cols="20%,60%,20%"] @@ -51,6 +51,6 @@ Note: as specified by the ivy.xsd, the children elements are ordered; must come |Element|Description|Cardinality |link:../ivyfile/dependency.html[dependency]|declares a dependency for this module|0..n |link:../ivyfile/exclude.html[exclude]|excludes artifacts, modules or whole organizations from the set of dependencies of this module *__since 2.0__*|0..n -|link:../ivyfile/override.html[override]|specify an override mediation rule, overriding the revision and/or branch requested for a transitive dependency *__since 2.0__*|0..n -|link:../ivyfile/conflict.html[conflict]|specify a a conflict manager for one or several dependencies *__since 2.0__*|0..n +|link:../ivyfile/override.html[override]|specifies an override mediation rule, overriding the revision and/or branch requested for a transitive dependency *__since 2.0__*|0..n +|link:../ivyfile/conflict.html[conflict]|specifies a conflict manager for one or several dependencies *__since 2.0__*|0..n |======= http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile/dependency-artifact.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/dependency-artifact.adoc b/asciidoc/ivyfile/dependency-artifact.adoc index 5006963..8a6ffd2 100644 --- a/asciidoc/ivyfile/dependency-artifact.adoc +++ b/asciidoc/ivyfile/dependency-artifact.adoc @@ -19,10 +19,10 @@ *Tag:* artifact *Parent:* link:../ivyfile/dependency.html[dependency] -This feature gives you more control on a dependency for which you do not control its ivy file. -It enables to specify the artifacts required, if the dependency has no ivy file. +This feature gives you more control on a dependency for which you do not control its Ivy file. +It enables to specify the artifacts required, if the dependency has no Ivy file. -Indeed, when a module has no ivy file, it is assumed that it publishes exactly one artifact having the same name as the module itself. But when this module publishes more artifacts, or simply does not respect the name rule, and if you cannot deliver an ivy file for it (because you do not control the repository, for instance - think about maven ibiblio repository, to give no name), then this feature let you specify the artifacts names you want to get. +Indeed, when a module has no Ivy file, it is assumed that it publishes exactly one artifact having the same name as the module itself. But when this module publishes more artifacts, or simply does not respect the name rule, and if you cannot deliver an Ivy file for it (because you do not control the repository, for instance - think about Maven ibiblio repository, to give no name), then this feature let you specify the artifacts names you want to get. Each artifact specification can be given in the context of particular master configurations. By default, if no configuration is specified, artifacts specification apply to all master configurations. But you can specify that a specification applies only to one or several master configurations, using either inline or nested conf specification. In this case, do not forget that if you do not specify any specification for a particular configuration, then no specification will apply for this configuration and it will be resolved not taking into account any specification. @@ -37,7 +37,7 @@ Example: </dependency> ---- -*__since 1.4__* It's possible to indicate the url at which the artifact can be found. This is not mandatory, and even not recommended with an enterprise repository. Note that Ivy will always look at the location where the artifact should be and only use the url if it cannot be found at the standard location in the repository. +*__since 1.4__* It's possible to indicate the URL at which the artifact can be found. This is not mandatory, and even not recommended with an enterprise repository. Note that Ivy will always look at the location where the artifact should be and only use the URL if it cannot be found at the standard location in the repository. *__since 1.4__* This tag supports link:../concept.html#extra[extra attributes]. @@ -54,7 +54,7 @@ Example: |conf|comma separated list of the master configurations in which this artifact should be included. `$$*$$` wildcard can be used to designate all configurations of this module|No, defaults to `$$*$$`, unless nested conf are specified -|url|an url where this artifact can be found if it isn't present at the standard location in the repository *__since 1.4__*|No, defaults to no url +|url|an URL where this artifact can be found if it isn't present at the standard location in the repository *__since 1.4__*|No, defaults to no URL |======= == Child elements http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/614bf1ad/asciidoc/ivyfile/dependency-include.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/dependency-include.adoc b/asciidoc/ivyfile/dependency-include.adoc index 70de200..22e015b 100644 --- a/asciidoc/ivyfile/dependency-include.adoc +++ b/asciidoc/ivyfile/dependency-include.adoc @@ -19,10 +19,10 @@ *Tag:* include *Parent:* link:../ivyfile/dependency.html[dependency] -This feature gives you more control on a dependency for which you do not control its ivy file. -It enables to restrict the artifacts required by including only the artifacts given here, even if configuration does not a good separation of published artifacts. +This feature gives you more control on a dependency for which you do not control its Ivy file. +It enables to restrict the artifacts required by including only the artifacts given here, even if configuration does not provide a good separation of published artifacts. -Each artifact restriction can be given in the context of particular master configurations. By default, if no configuration is specified, artifacts restriction apply to all master configurations. But you can specify that a restriction applies only to one or several master configurations, using either inline or nested conf specification. In this case, do not forget that if you do not specify any restriction for a particular configuration, then no restriction will apply for this configuration and it will be resolved not taking into account any restriction. +Each artifact restriction can be given in the context of particular master configurations. By default, if no configuration is specified, artifact restrictions apply to all master configurations. But you can specify that a restriction applies only to one or several master configurations, using either inline or nested conf specification. In this case, do not forget that if you do not specify any restriction for a particular configuration, then no restriction will apply for this configuration and it will be resolved not taking any restriction into account. For instance, imagine you have A, B & C master configurations. If you restrict to art1 in A & B and art2 in A, then C will not be restricted at all, and will thus get all artifacts of all dependency configurations if you do not specify a configuration mapping. To prevent this, you have to specify a configuration mapping for the dependency, mapping only A & B to some or all dependency configurations. @@ -44,7 +44,7 @@ Example: |name|the name of an artifact of the dependency module to add to the include list, or an expression matching this name (see `matcher` attribute below)|No, defaults to `$$.*$$` |type|the type of the artifact of the dependency module to add to the include list, or an expression matching this name (see `matcher` attribute below)|No, defaults to `$$.*$$` |ext|the extension of the artifact of the dependency module to add to the include list, or an expression matching this name (see `matcher` attribute below)|No, defaults to the value of `type` -|matcher|the link:../concept.html#matcher[matcher] to use to match the modules to include *__since 2.0__*|No, defaults to `exactOrRegexp` in pre 1.3 ivy files, and `exact` in 1.3 and superior +|matcher|the link:../concept.html#matcher[matcher] to use to match the modules to include *__since 2.0__*|No, defaults to `exactOrRegexp` in pre 1.3 Ivy files, and `exact` in 1.3 and superior |conf|comma separated list of the master configurations in which this artifact should be included. `$$*$$` wildcard can be used to designate all configurations of this module|No, defaults to `$$*$$`, unless nested conf are specified
