Fix asciidoc navigation on GitHub Project: http://git-wip-us.apache.org/repos/asf/ant-ivy/repo Commit: http://git-wip-us.apache.org/repos/asf/ant-ivy/commit/d7ddccdc Tree: http://git-wip-us.apache.org/repos/asf/ant-ivy/tree/d7ddccdc Diff: http://git-wip-us.apache.org/repos/asf/ant-ivy/diff/d7ddccdc
Branch: refs/heads/master Commit: d7ddccdc6ceceb8a42c81a4e1a4cf95e8d7dc939 Parents: 44d800e Author: Gintas Grigelionis <gin...@apache.org> Authored: Tue Mar 13 22:49:17 2018 +0100 Committer: Gintas Grigelionis <gin...@apache.org> Committed: Tue Mar 13 22:49:17 2018 +0100 ---------------------------------------------------------------------- asciidoc/ant.adoc | 4 +- asciidoc/bestpractices.adoc | 14 +-- asciidoc/concept.adoc | 36 ++++---- asciidoc/configuration.adoc | 2 +- asciidoc/index.adoc | 10 +-- asciidoc/ivyfile.adoc | 66 +++++++------- asciidoc/ivyfile/configurations.adoc | 8 +- asciidoc/ivyfile/dependencies.adoc | 16 ++-- asciidoc/ivyfile/dependency.adoc | 32 +++---- asciidoc/ivyfile/include.adoc | 6 +- asciidoc/osgi.adoc | 8 +- asciidoc/osgi/sigil.adoc | 2 +- asciidoc/principle.adoc | 4 +- asciidoc/reference.adoc | 18 ++-- asciidoc/resolver/packager.adoc | 8 +- asciidoc/settings.adoc | 114 ++++++++++++------------- asciidoc/settings/caches.adoc | 10 +-- asciidoc/settings/resolvers.adoc | 46 +++++----- asciidoc/settings/timeout-constraint.adoc | 2 +- asciidoc/terminology.adoc | 8 +- asciidoc/tutorial.adoc | 18 ++-- asciidoc/use/info.adoc | 20 ++--- 22 files changed, 226 insertions(+), 226 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/ant.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ant.adoc b/asciidoc/ant.adoc index 325e2a1..02c3260 100644 --- a/asciidoc/ant.adoc +++ b/asciidoc/ant.adoc @@ -75,8 +75,8 @@ This calls Ivy with default values, which might be ok in several projects. In fa 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[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). +* First the configure task tells it how it can find dependencies giving it a path to an link:settings{outfilesuffix}[settings XML file]. +* Then the resolve task actually resolves dependencies described by an link:ivyfile{outfilesuffix}[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: http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/bestpractices.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/bestpractices.adoc b/asciidoc/bestpractices.adoc index 3402252..f511d5a 100644 --- a/asciidoc/bestpractices.adoc +++ b/asciidoc/bestpractices.adoc @@ -25,9 +25,9 @@ In Ivy world, module descriptors are Ivy files, which are basically simple XML f 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 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 link:concept.html#configurations[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 link:concept{outfilesuffix}#configurations[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 adding Ivy files for all the modules in your repository. You can even enforce this rule by setting the descriptor attribute to required on your link:settings/resolvers.html[resolvers]. Hence you shouldn't need to use the dependency artifact inclusion/exclusion/specification feature of Ivy, which should only be used in very specific cases. +Therefore we recommend adding Ivy files for all the modules in your repository. You can even enforce this rule by setting the descriptor attribute to required on your link:settings/resolvers{outfilesuffix}[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 @@ -51,15 +51,15 @@ A public repository usually contains much more than what you actually need. Is t The artifacts you download from a module repository are often executable, and are thus a security concern. Imagine a hacker replacing commons-lang by another version containing a virus? If you rely on a public repository to build your software, you expose it to a security risk. You can read more about that in this link:https://www.helpnetsecurity.com/dl/articles/fortify_attacking_the_build.pdf[Forrester article]. -Note that using an enterprise repository doesn't mean you have to build it entirely by hand. Ivy features an link:use/install.html[install] task which can be used to install modules from one repository to another one, so it can be used to selectively install modules from a public repository to your enterprise repository, where you will then be able to ensure control, reliability and accuracy. +Note that using an enterprise repository doesn't mean you have to build it entirely by hand. Ivy features an link:use/install{outfilesuffix}[install] task which can be used to install modules from one repository to another one, so it can be used to selectively install modules from a public repository to your enterprise repository, where you will then be able to ensure control, reliability and accuracy. == Always use patterns with at least organisation and module -Ivy is very flexible and can accommodate a lot of existing repositories, using the concept of link:concept.html#pattern[patterns]. But if your repository doesn't exist yet, we strongly recommend always using the organisation and the module name in your pattern, even for a private repository where you put only your own modules (which all have the same organisation). Why? Because the Ivy listing feature relies on the token it can find in the pattern. If you have no organisation token in your pattern, Ivy won't be able to list the (only?) organisation in your repository. And this can be a problem for code completion in IvyDE, for example, but also for repository wide tasks like link:use/install.html[install] or link:use/repreport.html[repreport]. +Ivy is very flexible and can accommodate a lot of existing repositories, using the concept of link:concept{outfilesuffix}#pattern[patterns]. But if your repository doesn't exist yet, we strongly recommend always using the organisation and the module name in your pattern, even for a private repository where you put only your own modules (which all have the same organisation). Why? Because the Ivy listing feature relies on the token it can find in the pattern. If you have no organisation token in your pattern, Ivy won't be able to list the (only?) organisation in your repository. And this can be a problem for code completion in IvyDE, for example, but also for repository wide tasks like link:use/install{outfilesuffix}[install] or link:use/repreport{outfilesuffix}[repreport]. == Public ivysettings.xml with public repositories -If you create a public repository, provide a URL to the link:settings.html[ivysettings.xml] file. It's pretty easy to do, and if someone wants to leverage your repository, (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. +If you create a public repository, provide a URL to the link:settings{outfilesuffix}[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{outfilesuffix}[settings] with the URL of your ivysettings.xml file, or link:settings/include{outfilesuffix}[include] it in its own settings file, which makes it really easy to combine several public repositories. == Dealing with integration versions @@ -72,10 +72,10 @@ 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{outfilesuffix}[changing attribute] on a dependency or by configuring the link:settings/resolvers{outfilesuffix}[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. +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{outfilesuffix}[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 :-) http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/concept.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/concept.adoc b/asciidoc/concept.adoc index 2ce1b0b..c76c094 100644 --- a/asciidoc/concept.adoc +++ b/asciidoc/concept.adoc @@ -30,7 +30,7 @@ Moreover, the fact that it is the responsibility of the resolver to find Ivy fil 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 link:settings/resolvers.html[resolvers configuration page]. +If you want to see which resolvers are available in Ivy, you can go to the link:settings/resolvers{outfilesuffix}[resolvers configuration page]. == [[configurations]]Module configurations explained @@ -42,7 +42,7 @@ Moreover, because dependencies in Ivy are expressed on modules and not on artifa 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 to declare in which configuration your artifacts are published, and how to declare configuration mapping, please refer to link:ivyfile.html[Ivy file documentation]. The link:tutorial/conf.html[configurations tutorial] is also a good place to go to learn more about this concept. +For details on how to declare your module configurations, how to declare in which configuration your artifacts are published, and how to declare configuration mapping, please refer to link:ivyfile{outfilesuffix}[Ivy file documentation]. The link:tutorial/conf{outfilesuffix}[configurations tutorial] is also a good place to go to learn more about this concept. == [[variables]]Variables @@ -58,7 +58,7 @@ To use Ivy variables, you just have to follow the same syntax as for Ant propert 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{outfilesuffix}[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. See the Patterns chapter below for what pattern tokens are. @@ -158,7 +158,7 @@ This algorithm takes into account special meanings of some text. For instance, w `latest-lexico`:: This compares the revisions as strings, using lexicographic order (the one used by the Java string comparison). -See also how to configure new latest strategies link:settings/latest-strategies.html[here]. +See also how to configure new latest strategies link:settings/latest-strategies{outfilesuffix}[here]. == [[conflict]]Conflict Manager @@ -168,9 +168,9 @@ But in some cases you will need to keep several revisions, and load in separate 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 link:settings/conflict-managers.html[conflict manager configuration page]. +The list of available conflict managers is available on the link:settings/conflict-managers{outfilesuffix}[conflict manager configuration page]. -For more details on how to setup your conflict managers by module, see the link:ivyfile/conflicts.html[conflicts] section in the Ivy file reference. +For more details on how to setup your conflict managers by module, see the link:ivyfile/conflicts{outfilesuffix}[conflicts] section in the Ivy file reference. == [[matcher]]Pattern matcher @@ -227,7 +227,7 @@ ${repository.dir}/[organisation]/[module]/[color]/[revision]/[artifact].[ext] Note that in patterns you must use the unqualified attribute name (no namespace prefix). -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 fulfill anymore the official Ivy XSD. See the link:settings/settings.html[settings documentation] to see how to disable validation. +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 fulfill anymore the official Ivy XSD. See the link:settings/settings{outfilesuffix}[settings documentation] to see how to disable validation. == [[checksum]]Checksums @@ -262,7 +262,7 @@ If you want to change this default, you can set the variable `ivy.checksums`. He 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 accurately, and so on. -For more details about events and triggers, see the link:settings/triggers.html[triggers] documentation page in the configuration section of this documentation. +For more details about events and triggers, see the link:settings/triggers{outfilesuffix}[triggers] documentation page in the configuration section of this documentation. == [[circular]]Circular Dependencies @@ -281,7 +281,7 @@ same as ignore, except that they are signaled as a warning (default) `error`:: halt the dependency resolution when a circular dependency is found -See the link:settings/settings.html[configuration page] to see how to configure the circular dependency strategy you want to use. +See the link:settings/settings{outfilesuffix}[configuration page] to see how to configure the circular dependency strategy you want to use. == Cache and Change Management @@ -293,18 +293,18 @@ 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. -This part of the cache can be shared if you use a well suited link:settings/lock-strategies.html[lock strategy]. +This part of the cache can be shared if you use a well suited link:settings/lock-strategies{outfilesuffix}[lock strategy]. the resolution cache:: This part of the cache is used to store resolution data, which is used by Ivy to reuse the results of a resolve process. + This part of the cache is overwritten each time a new resolve is performed, and should never be used by multiple processes at the same time. -While there is always only one resolution cache, you can link:settings/caches.html[define multiple repository caches], each link:settings/resolvers.html[resolver] being able to use a separate cache. +While there is always only one resolution cache, you can link:settings/caches{outfilesuffix}[define multiple repository caches], each link:settings/resolvers{outfilesuffix}[resolver] being able to use a separate cache. === [[change]]Change management -To optimize the dependency resolution and the way the cache is used, Ivy assumes by default that a revision never changes. So once Ivy has a module in its cache (metadata and artifacts), it trusts the cache and does not even query the repository. This optimization is very useful in most cases, and causes no problem as long as you respect this paradigm: a revision never changes. Besides performance, there are several link:bestpractices.html[good reasons] to follow this principle. +To optimize the dependency resolution and the way the cache is used, Ivy assumes by default that a revision never changes. So once Ivy has a module in its cache (metadata and artifacts), it trusts the cache and does not even query the repository. This optimization is very useful in most cases, and causes no problem as long as you respect this paradigm: a revision never changes. Besides performance, there are several link:bestpractices{outfilesuffix}[good reasons] to follow this principle. 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: @@ -318,17 +318,17 @@ In this case, setting `checkModified="true"` on your dependency resolver will be Some people, especially those coming from Maven 2 land, like to use one special revision to handle often updated modules. In Maven 2, this is called a SNAPSHOT version, and some argue that it helps save disk space to keep only one version for the high number of intermediary builds you can make whilst developing. -Ivy supports this kind of approach with the notion of "changing revision". A changing revision is just that: a revision for which Ivy should consider that the artifacts may change over time. To handle this, you can either specify a dependency as changing on the link:ivyfile/dependency.html[dependency] tag, or use the `changingPattern` and `changingMatcher` attributes on your link:settings/resolvers.html[resolvers] to indicate which revision or group of revisions should be considered as changing. +Ivy supports this kind of approach with the notion of "changing revision". A changing revision is just that: a revision for which Ivy should consider that the artifacts may change over time. To handle this, you can either specify a dependency as changing on the link:ivyfile/dependency{outfilesuffix}[dependency] tag, or use the `changingPattern` and `changingMatcher` attributes on your link:settings/resolvers{outfilesuffix}[resolvers] to indicate which revision or group of revisions should be considered as changing. Once Ivy knows that a revision is changing, it will follow this principle to avoid checking your repository too often: if the module metadata has not changed, it will considered the whole module (including artifacts) as not changed. Even if the module descriptor file has changed, it will check the publication data of the module to see if this is a new publication of the same revision or not. Then if the publication date has changed, it will check the artifacts' last modified timestamps, and download them accordingly. -So if you want to use changing revisions, use the link:use/publish.html[publish] task to publish your modules, it will take care of updating the publication date, and everything will work fine. And remember to set `checkModified=true"` on your resolver too! +So if you want to use changing revisions, use the link:use/publish{outfilesuffix}[publish] task to publish your modules, it will take care of updating the publication date, and everything will work fine. And remember to set `checkModified=true"` on your resolver too! == [[paths]]Paths handling As a dependency manager, Ivy has a lot of file related operations, which most of the time use paths or path patterns to locate the file on the filesystem. -These paths can obviously be relative or absolute. We recommend to always use absolute paths, so that you don't have to worry about what is the base of your relative paths. Ivy provides some variables which can be used as the base of your absolute paths. For instance, Ivy has a concept of base directory, which is basically the same as for Ant. You have access to this base directory with the ivy.basedir variable. So if you have a path like `${ivy.basedir}/ivy.xml`, you have an absolute path. In link:settings.html[settings files], you also have a variable called `ivy.settings.dir` which points to the directory in which your settings file is located, which makes defining paths relative to this directory very easy. +These paths can obviously be relative or absolute. We recommend to always use absolute paths, so that you don't have to worry about what is the base of your relative paths. Ivy provides some variables which can be used as the base of your absolute paths. For instance, Ivy has a concept of base directory, which is basically the same as for Ant. You have access to this base directory with the ivy.basedir variable. So if you have a path like `${ivy.basedir}/ivy.xml`, you have an absolute path. In link:settings{outfilesuffix}[settings files], you also have a variable called `ivy.settings.dir` which points to the directory in which your settings file is located, which makes defining paths relative to this directory very easy. If you really want to use relative paths, the base directory used to actually locate the file depends on where the relative path is defined: @@ -342,7 +342,7 @@ If you really want to use relative paths, the base directory used to actually lo Most of the artifacts found in a repository are jars. They can be downloaded and used as is. But some other kind of artifacts required some __unpacking__ after being downloaded and before being used. Such artifacts can be zipped folders and packed jars. Ivy supports that kind of artifact with *packaging*. -A __packaged__ artifact needs to be declared as such in the module descriptor via the attribute link:ivyfile/artifact.html[packaging]. The value of that attribute defined which kind of unpacking algorithm must be used. Here are the list of currently supported algorithms: +A __packaged__ artifact needs to be declared as such in the module descriptor via the attribute link:ivyfile/artifact{outfilesuffix}[packaging]. The value of that attribute defined which kind of unpacking algorithm must be used. Here are the list of currently supported algorithms: * `zip`, `jar` or `war`: the artifact will be uncompressed as a folder @@ -357,6 +357,6 @@ So, if in an `ivy.xml`, there would be declared a such artifact: <artifact name="mymodule" type="jar" ext="jar.pack.gz" packaging="pack200"/> ---- -A file `mymodule-1.2.3.jar.pack.gz` would be download into the cache, and also uncompressed in the cache to `mymodule-1.2.3.jar`. Then any post resolve task which supports it, like the link:use/cachepath.html[cachepath], will use the uncompressed file instead of the original compressed file. +A file `mymodule-1.2.3.jar.pack.gz` would be download into the cache, and also uncompressed in the cache to `mymodule-1.2.3.jar`. Then any post resolve task which supports it, like the link:use/cachepath{outfilesuffix}[cachepath], will use the uncompressed file instead of the original compressed file. -It is possible to chain packing algorithm. The attribute link:ivyfile/artifact.html[packaging] of a artifact expects a comma separated list of packing types, in packing order. For instance, an artifact `mymodule-1.2.3.jar.pack.gz` can have the packaging `jar,pack200`, so it would be uncompressed as a folder `mymodule-1.2.3`. +It is possible to chain packing algorithm. The attribute link:ivyfile/artifact{outfilesuffix}[packaging] of a artifact expects a comma separated list of packing types, in packing order. For instance, an artifact `mymodule-1.2.3.jar.pack.gz` can have the packaging `jar,pack200`, so it would be uncompressed as a folder `mymodule-1.2.3`. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/configuration.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/configuration.adoc b/asciidoc/configuration.adoc index 7b54895..2310f79 100644 --- a/asciidoc/configuration.adoc +++ b/asciidoc/configuration.adoc @@ -18,4 +18,4 @@ //// This page has moved. If your browser doesn't automatically redirect to its new location, click -link:settings.html[here]. +link:settings{outfilesuffix}[here]. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/index.adoc b/asciidoc/index.adoc index b930408..e8bed0d 100644 --- a/asciidoc/index.adoc +++ b/asciidoc/index.adoc @@ -31,7 +31,7 @@ Ivy is open source and released under a very permissive link:https://www.apache. 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{outfilesuffix}[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{outfilesuffix}[repositories]. == About this doc @@ -46,7 +46,7 @@ If you browse this documentation from your installation of Ivy, you can also che You can also browse this documentation offline either by downloading the documentation distribution, or by checking out the doc directory from git. This documentation uses link:http://asciidoctor.org/[asciidoc] as its documentation engine, so you can very easily link:https://ant.apache.org/ivy/get-involved.html[edit it and submit patches] when you browse it from source. -A link:book.html[printer-friendly version] of this whole documentation is also provided for your convenience. +A link:book{outfilesuffix}[printer-friendly version] of this whole documentation is also provided for your convenience. Since Ivy 2.0.0-alpha-2, we keep an online history of the documentation. You can thus browse history versions online (in the history menu in the web site) and even check the trunk version documentation currently in development. @@ -64,13 +64,13 @@ Check link:https://ant.apache.org/ivy/links.html[external tools and resources]. This documentation is composed of three main parts: -link:tutorial.html[Tutorials]:: +link:tutorial{outfilesuffix}[Tutorials]:: The tutorials is the best way to begin to play with Ivy. You will easily and quickly learn the basics of Ivy. -link:reference.html[Reference]:: +link:reference{outfilesuffix}[Reference]:: The reference documentation gives you all the details of Ivy. The introduction part is particularly useful: it defines some vocabulary, explains main concepts such as dependency resolvers and patterns, and gives an overview of how Ivy works internally. It's also in the reference doc that you will find all you always dreamed to know about Ivy settings, Ivy files, and Ivy use (especially with Ant). -link:dev.html[Developer doc]:: +link:dev{outfilesuffix}[Developer doc]:: 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/d7ddccdc/asciidoc/ivyfile.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile.adoc b/asciidoc/ivyfile.adoc index 0585076..b046f5f 100644 --- a/asciidoc/ivyfile.adoc +++ b/asciidoc/ivyfile.adoc @@ -31,7 +31,7 @@ Here is the simplest Ivy file you can write: 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. +Before beginning the reference itself, it is required to have in mind the terminology defined in the link:reference{outfilesuffix}[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: @@ -53,44 +53,44 @@ A module descriptor (Ivy file) is needed both before and after the publication o === 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{outfilesuffix}#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. -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{outfilesuffix}[deliver] task. Note that although it is technically possible to publish module revisions with dynamic Ivy files, it is not a generally recommended practice. == Hierarchical Index * *ivy-module* - ** link:ivyfile/info.html[info] - *** link:ivyfile/license.html[license] - *** link:ivyfile/ivyauthor.html[ivyauthor] - *** link:ivyfile/repository.html[repository] - *** link:ivyfile/description.html[description] - ** link:ivyfile/configurations.html[configurations] - *** link:ivyfile/conf.html[conf] - ** link:ivyfile/publications.html[publications] - *** link:ivyfile/artifact.html[artifact] - **** link:ivyfile/artifact-conf.html[conf] - ** link:ivyfile/dependencies.html[dependencies] - *** link:ivyfile/dependency.html[dependency] - **** link:ivyfile/dependency-conf.html[conf] - ***** link:ivyfile/mapped.html[mapped] - **** link:ivyfile/dependency-artifact.html[artifact] - ***** link:ivyfile/dependency-artifact-conf.html[conf] - **** link:ivyfile/dependency-artifact.html[include] - ***** link:ivyfile/dependency-artifact-conf.html[conf] - **** link:ivyfile/artifact-exclude.html[exclude] - ***** link:ivyfile/artifact-exclude-conf.html[conf] - *** link:ivyfile/exclude.html[exclude] - *** link:ivyfile/override.html[override] - *** link:ivyfile/conflict.html[conflict] - ** link:ivyfile/conflicts.html[conflicts] - *** link:ivyfile/manager.html[manager] + ** link:ivyfile/info{outfilesuffix}[info] + *** link:ivyfile/license{outfilesuffix}[license] + *** link:ivyfile/ivyauthor{outfilesuffix}[ivyauthor] + *** link:ivyfile/repository{outfilesuffix}[repository] + *** link:ivyfile/description{outfilesuffix}[description] + ** link:ivyfile/configurations{outfilesuffix}[configurations] + *** link:ivyfile/conf{outfilesuffix}[conf] + ** link:ivyfile/publications{outfilesuffix}[publications] + *** link:ivyfile/artifact{outfilesuffix}[artifact] + **** link:ivyfile/artifact-conf{outfilesuffix}[conf] + ** link:ivyfile/dependencies{outfilesuffix}[dependencies] + *** link:ivyfile/dependency{outfilesuffix}[dependency] + **** link:ivyfile/dependency-conf{outfilesuffix}[conf] + ***** link:ivyfile/mapped{outfilesuffix}[mapped] + **** link:ivyfile/dependency-artifact{outfilesuffix}[artifact] + ***** link:ivyfile/dependency-artifact-conf{outfilesuffix}[conf] + **** link:ivyfile/dependency-artifact{outfilesuffix}[include] + ***** link:ivyfile/dependency-artifact-conf{outfilesuffix}[conf] + **** link:ivyfile/artifact-exclude{outfilesuffix}[exclude] + ***** link:ivyfile/artifact-exclude-conf{outfilesuffix}[conf] + *** link:ivyfile/exclude{outfilesuffix}[exclude] + *** link:ivyfile/override{outfilesuffix}[override] + *** link:ivyfile/conflict{outfilesuffix}[conflict] + ** link:ivyfile/conflicts{outfilesuffix}[conflicts] + *** link:ivyfile/manager{outfilesuffix}[manager] == ivy-module @@ -111,9 +111,9 @@ The root tag of any Ivy file (module descriptor). [options="header"] |======= |Element|Description|Cardinality -|link:ivyfile/info.html[info]|contains information about the described module|1 -|link:ivyfile/configurations.html[configurations]|container for configuration elements|0..1 -|link:ivyfile/publications.html[publications]|container for published artifact elements|0..1 -|link:ivyfile/dependencies.html[dependencies]|container for dependency elements|0..1 -|link:ivyfile/conflicts.html[conflicts]|section to configure the conflict managers to use|0..1 +|link:ivyfile/info{outfilesuffix}[info]|contains information about the described module|1 +|link:ivyfile/configurations{outfilesuffix}[configurations]|container for configuration elements|0..1 +|link:ivyfile/publications{outfilesuffix}[publications]|container for published artifact elements|0..1 +|link:ivyfile/dependencies{outfilesuffix}[dependencies]|container for dependency elements|0..1 +|link:ivyfile/conflicts{outfilesuffix}[conflicts]|section to configure the conflict managers to use|0..1 |======= http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/ivyfile/configurations.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/configurations.adoc b/asciidoc/ivyfile/configurations.adoc index 88f6801..623663c 100644 --- a/asciidoc/ivyfile/configurations.adoc +++ b/asciidoc/ivyfile/configurations.adoc @@ -17,7 +17,7 @@ under the License. //// -*Tag:* configurations *Parent:* link:../ivyfile.html[ivy-module] +*Tag:* configurations *Parent:* link:../ivyfile{outfilesuffix}[ivy-module] A container for configuration elements. If this container is not present, it is assumed that the module has one public configuration called `default`. @@ -35,7 +35,7 @@ See link:#defaultconfmapping[examples below] to clarify the behavior of these tw (*__since 1.4__*) You can activate a `confmappingoverride` mode for all configurations, in which case the extending configurations will override the mappings of the configurations they extend from. -(*__since 2.5__*) Attributes inherited via link:extends.html[`extends`] are added to both `configurations` and `dependencies` on link:../use/deliver.html[delivery]. If the latter element has attributes, their values override values of the corresponding attributes of the former element. +(*__since 2.5__*) Attributes inherited via link:extends{outfilesuffix}[`extends`] are added to both `configurations` and `dependencies` on link:../use/deliver{outfilesuffix}[delivery]. If the latter element has attributes, their values override values of the corresponding attributes of the former element. == [[attributes]]Attributes @@ -52,8 +52,8 @@ See link:#defaultconfmapping[examples below] to clarify the behavior of these tw [options="header",cols="20%,60%,20%"] |======= |Element|Description|Cardinality -|link:conf.html[conf]|declares a configuration of this module|0..n -|link:include.html[include]|include configurations from another file|0..n +|link:conf{outfilesuffix}[conf]|declares a configuration of this module|0..n +|link:include{outfilesuffix}[include]|include configurations from another file|0..n |======= == Configuration mappings details http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/ivyfile/dependencies.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/dependencies.adoc b/asciidoc/ivyfile/dependencies.adoc index 6d36a8f..ea4c07b 100644 --- a/asciidoc/ivyfile/dependencies.adoc +++ b/asciidoc/ivyfile/dependencies.adoc @@ -17,11 +17,11 @@ under the License. //// -*Tag:* dependencies *Parent:* link:../ivyfile.html[ivy-module] +*Tag:* dependencies *Parent:* link:../ivyfile{outfilesuffix}[ivy-module] 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 dependencies at all. -This container provides two similar behaviors described below. (See link:configurations.html[configurations doc page] for more details about these behaviors). +This container provides two similar behaviors described below. (See link:configurations{outfilesuffix}[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. @@ -31,7 +31,7 @@ This container provides two similar behaviors described below. (See link:configu (*__since 1.4__*) You can activate a `confmappingoverride` mode for all configurations, in which case the extending configurations will override the mappings of the configurations they extend from. -(*__since 2.5__*) Attributes inherited via link:extends.html[`extends`] are added to `dependencies` only on link:../use/deliver.html[delivery] and override attributes inherited from `configurations`. +(*__since 2.5__*) Attributes inherited via link:extends{outfilesuffix}[`extends`] are added to `dependencies` only on link:../use/deliver{outfilesuffix}[delivery] and override attributes inherited from `configurations`. == Attributes @@ -47,14 +47,14 @@ This container provides two similar behaviors described below. (See link:configu == Child elements -Note: as specified by the ivy.xsd, the children elements are ordered; first must come the `link:dependency.html[dependency]` elements, then the `link:exclude.html[exclude]` elements, then the `link:override.html[override]` elements, and then the `link:conflict.html[conflict]` elements. +Note: as specified by the ivy.xsd, the children elements are ordered; first must come the `link:dependency{outfilesuffix}[dependency]` elements, then the `link:exclude{outfilesuffix}[exclude]` elements, then the `link:override{outfilesuffix}[override]` elements, and then the `link:conflict{outfilesuffix}[conflict]` elements. [options="header",cols="20%,60%,20%"] |======= |Element|Description|Cardinality -|link:dependency.html[dependency]|declares a dependency for this module|0..n -|link:exclude.html[exclude]|excludes artifacts, modules or whole organizations from the set of dependencies of this module (*__since 2.0__*)|0..n -|link: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:conflict.html[conflict]|specifies a conflict manager for one or several dependencies (*__since 2.0__*)|0..n +|link:dependency{outfilesuffix}[dependency]|declares a dependency for this module|0..n +|link:exclude{outfilesuffix}[exclude]|excludes artifacts, modules or whole organizations from the set of dependencies of this module (*__since 2.0__*)|0..n +|link:override{outfilesuffix}[override]|specifies an override mediation rule, overriding the revision and/or branch requested for a transitive dependency (*__since 2.0__*)|0..n +|link:conflict{outfilesuffix}[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/d7ddccdc/asciidoc/ivyfile/dependency.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/dependency.adoc b/asciidoc/ivyfile/dependency.adoc index 8a189fc..f900163 100644 --- a/asciidoc/ivyfile/dependency.adoc +++ b/asciidoc/ivyfile/dependency.adoc @@ -17,7 +17,7 @@ under the License. //// -*Tag:* dependency *Parent:* link:dependencies.html[dependencies] +*Tag:* dependency *Parent:* link:dependencies{outfilesuffix}[dependencies] Declares a dependency for this module. A dependency is described by the module on which the current module depends (identified by its name, organisation and revision), and a mapping of configurations. @@ -31,7 +31,7 @@ selects the latest revision of the dependency module. * `latest.[any status]` (*__since 1.4__*) + selects the latest revision of the dependency module with at least the specified status. + For instance, `latest.milestone` will select the latest version being either a `milestone` or a `release`, and `latest.release` will only select the latest `release`. Note that in order to find the latest revision with the appropriate status Ivy has to parse all the Ivy files in your repository from the last one until it finds such a revision. Hence don't be surprised if the resolution slow down. -See also link:../settings/statuses.html[statuses] to see how to configure module statuses. +See also link:../settings/statuses{outfilesuffix}[statuses] to see how to configure module statuses. * end the revision with a `+` + selects the latest sub-revision of the dependency module. For instance, @@ -49,8 +49,8 @@ Examples: + `(,2.0]` matches all versions lower or equal to 2.0 + `(,2.0[` matches all versions lower than 2.0 + -(*__since 1.4__*) If you don't find a way to expression your dependency version constraint among these, you can link:../settings/version-matchers.html[plug your own]. -The way to determine which revision is the "latest" between two is configurable through the use of pluggable LatestStrategy. See link:../reference.html[Ivy main concepts] for details about this. +(*__since 1.4__*) If you don't find a way to expression your dependency version constraint among these, you can link:../settings/version-matchers{outfilesuffix}[plug your own]. +The way to determine which revision is the "latest" between two is configurable through the use of pluggable LatestStrategy. See link:../reference{outfilesuffix}[Ivy main concepts] for details about this. == [[revision-constraint]]Revision constraint @@ -58,7 +58,7 @@ The way to determine which revision is the "latest" between two is configurable The `dependency` tag supports two revision attributes: `rev`, corresponding to the default required dependency revision, and `revConstraint`, corresponding to a dynamic revision constraint applied on this dependency. -Depending on the link:../use/resolve.html[resolve mode] used, the actual revision used during dependency resolution may vary. These revisions usually differ only for modules published in a repository. When link:../use/deliver.html[deliver] is used, dynamic version constraints are replaced by a static version constraint, to help build reproducibility. However, the information of the original version constraint is not lost, but rather put in the `revConstraint` attribute. This ensures better metadata in the repository while still allowing easier build reproducibility. +Depending on the link:../use/resolve{outfilesuffix}[resolve mode] used, the actual revision used during dependency resolution may vary. These revisions usually differ only for modules published in a repository. When link:../use/deliver{outfilesuffix}[deliver] is used, dynamic version constraints are replaced by a static version constraint, to help build reproducibility. However, the information of the original version constraint is not lost, but rather put in the `revConstraint` attribute. This ensures better metadata in the repository while still allowing easier build reproducibility. == Configurations mapping @@ -70,11 +70,11 @@ The first way to declare this mapping is called the inline mapping. It is maybe === Specify one configuration name -This means that in this master configuration the same dependency configuration is needed (except if a `defaultconfmapping` has been specified in this Ivy file, see link:../ivyfile/configurations.html[configurations] for details, or table below for examples). +This means that in this master configuration the same dependency configuration is needed (except if a `defaultconfmapping` has been specified in this Ivy file, see link:../ivyfile/configurations{outfilesuffix}[configurations] for details, or table below for examples). For instance, if the current module has defined a configuration named '`runtime`', and the dependency too, then having an inline mapping configuration set to '`runtime`' means that in the runtime master configuration the runtime dependency configuration is required. -The link:../ivyfile/configurations.html#defaultconfmapping[examples on the dependency on the configurations page] explain how Ivy interprets the conf attribute according to how link:../ivyfile/configurations.html[defaultconfmapping] and link:../ivyfile/configurations.html[defaultconf] is set. +The link:../ivyfile/configurations{outfilesuffix}#defaultconfmapping[examples on the dependency on the configurations page] explain how Ivy interprets the conf attribute according to how link:../ivyfile/configurations{outfilesuffix}[defaultconfmapping] and link:../ivyfile/configurations{outfilesuffix}[defaultconf] is set. === Specify a configuration mapping using the `$$->$$` operator @@ -108,7 +108,7 @@ For instance, `$$test->runtime(default)$$` means that in the test configuration It is also possible to define dependencies on configuration intersections. A configuration intersection is defined using a `+` sign to separate the configuration (eg `A+B` means the intersection of configuration A and B). In that case only artifacts and dependencies defined in both configurations in the dependency will be part of the master configuration defining the dependency on the configuration intersection. -Configuration intersections can also be used when specifying the confs to link:../use/resolve.html[resolve]. +Configuration intersections can also be used when specifying the confs to link:../use/resolve{outfilesuffix}[resolve]. Moreover, the mapping `$$*->@$$` is handled as a specific case with configuration intersections: it maps also the intersections. So if one resolve conf `A+B` in a module which defines a dependency with mapping `$$*->@$$`, the mapping `$$*->@$$` is interpreted as `$$A+B->A+B$$` so the intersection of A and B will be resolved in the dependency. @@ -146,15 +146,15 @@ If you prefer more verbose mapping declaration, everything is also possible with == Artifact restriction Moreover, the dependency element also supports an artifact restriction feature (since 0.6). -See link:../ivyfile/dependency-artifact.html[dependency artifact] for details. +See link:../ivyfile/dependency-artifact{outfilesuffix}[dependency artifact] for details. == Forcing revision Finally, the dependency element also supports an a force attribute (since 0.8), which gives an indication to conflict manager to force the revision of a dependency to the one given here. -See link:../ivyfile/conflicts.html[conflict manager] for details. +See link:../ivyfile/conflicts{outfilesuffix}[conflict manager] for details. -(*__since 1.4__*) This tag supports link:../concept.html#extra[extra attributes] +(*__since 1.4__*) This tag supports link:../concept{outfilesuffix}#extra[extra attributes] == Attributes @@ -166,10 +166,10 @@ See link:../ivyfile/conflicts.html[conflict manager] for details. |branch|the branch of the dependency. (*__since 1.4__*)|No, defaults to the default branch setting for the dependency. |rev|the revision of the dependency. See link:#revision[above] for details.|Yes |revConstraint|the dynamic revision constraint originally used for this dependency. See link:#revision-constraint[above] for details.|No, defaults to the value of `rev` -|force|a boolean to give an indication to conflict manager that this dependency should be forced to this revision (see link:../ivyfile/conflicts.html[conflict manager])|No, defaults to `false` +|force|a boolean to give an indication to conflict manager that this dependency should be forced to this revision (see link:../ivyfile/conflicts{outfilesuffix}[conflict manager])|No, defaults to `false` |conf|an inline mapping configuration spec (see above for details)|No, defaults to `defaultconf` attribute of dependencies element if neither conf attribute nor conf children element is given |transitive|`true` to resolve this dependency transitively, `false` otherwise (*__since 1.2__*)|No, defaults to `true` -|changing|`true` if the dependency artifacts may change without revision change, false otherwise (*__since 1.2__*). See link:../concept.html#change[cache and change management] for details.|No, defaults to `false` +|changing|`true` if the dependency artifacts may change without revision change, false otherwise (*__since 1.2__*). See link:../concept{outfilesuffix}#change[cache and change management] for details.|No, defaults to `false` |======= == Child elements @@ -177,9 +177,9 @@ See link:../ivyfile/conflicts.html[conflict manager] for details. [options="header",cols="20%,60%,20%"] |======= |Element|Description|Cardinality -|link:../ivyfile/dependency-conf.html[conf]|defines configuration mapping has sub element|0..n -|link:../ivyfile/dependency-artifact.html[artifact / include]|defines artifacts inclusion - use only if you do not control dependency Ivy file|0..n -|link:../ivyfile/artifact-exclude.html[exclude]|defines artifacts exclusion - use only if you do not control dependency Ivy file|0..n +|link:../ivyfile/dependency-conf{outfilesuffix}[conf]|defines configuration mapping has sub element|0..n +|link:../ivyfile/dependency-artifact{outfilesuffix}[artifact / include]|defines artifacts inclusion - use only if you do not control dependency Ivy file|0..n +|link:../ivyfile/artifact-exclude{outfilesuffix}[exclude]|defines artifacts exclusion - use only if you do not control dependency Ivy file|0..n |======= == Examples http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/ivyfile/include.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/ivyfile/include.adoc b/asciidoc/ivyfile/include.adoc index 460f6ca..9e6ad54 100644 --- a/asciidoc/ivyfile/include.adoc +++ b/asciidoc/ivyfile/include.adoc @@ -17,15 +17,15 @@ under the License. //// -*Tag:* include *Parent:* link:../ivyfile/configurations.html[configurations] +*Tag:* include *Parent:* link:../ivyfile/configurations{outfilesuffix}[configurations] [*__since 1.3__*] Include configurations specified in another file. -The included file should have a `configurations` tag as root tag, which follow the same specification as the link:../ivyfile/configurations.html[configurations] tag of the Ivy file. +The included file should have a `configurations` tag as root tag, which follow the same specification as the link:../ivyfile/configurations{outfilesuffix}[configurations] tag of the Ivy file. -This means that it can contain conf declarations, other file inclusions, and have link:configurations.html#attributes[attributes] controlling conf mapping. +This means that it can contain conf declarations, other file inclusions, and have link:configurations{outfilesuffix}#attributes[attributes] controlling conf mapping. When delivering an Ivy file with such an inclusion, the included descriptor file is inlined, i.e. Ivy removes the dependency on the external file. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/osgi.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/osgi.adoc b/asciidoc/osgi.adoc index 05261a1..d6f457c 100644 --- a/asciidoc/osgi.adoc +++ b/asciidoc/osgi.adoc @@ -34,7 +34,7 @@ So with a standard ivy.xml, you can express some dependency on some OSGi bundle With OSGi we can declare different kind of capabilities of a bundle which can match different kind of requirements of some other bundles (`Require-Bundle`/`Bundle-SymbolicName`, `Import-Package`/`Export-Package`, `Import-Service`/`Export-Service`). In Ivy we only have one kind of requirement and one kind of capability: the symbolic name of the bundle. Due to that restriction Ivy may not resolve exactly how we would expect with OSGi. The runtime of Ivy won't be as smart as a pure OSGi dependency manager. But we think that the mapping is working for most of the use cases involving OSGi dependencies management. -Details on the mapping of the OSGi dependency model into Ivy's one can be found in this link:osgi/osgi-mapping.html[page]. +Details on the mapping of the OSGi dependency model into Ivy's one can be found in this link:osgi/osgi-mapping{outfilesuffix}[page]. == Repository descriptor based resolvers @@ -51,8 +51,8 @@ The descriptor probably being not instantly downloaded, the descriptor is put in Here are different use case of using the OSGi capabilities of Ivy: -* link:osgi/eclipse-plugin.html[building an Eclipse™ plugin] + +* link:osgi/eclipse-plugin{outfilesuffix}[building an Eclipse™ plugin] + -* link:osgi/standard-osgi.html[building a standard OSGi bundle] + +* link:osgi/standard-osgi{outfilesuffix}[building a standard OSGi bundle] + -* link:osgi/target-platform.html[managing a "target" platform] + +* link:osgi/target-platform{outfilesuffix}[managing a "target" platform] + http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/osgi/sigil.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/osgi/sigil.adoc b/asciidoc/osgi/sigil.adoc index 269e9a8..6c8ab5e 100644 --- a/asciidoc/osgi/sigil.adoc +++ b/asciidoc/osgi/sigil.adoc @@ -41,7 +41,7 @@ The built-in OSGi resolver is __obviously__ using the Ivy engine to do the resol On the other hand, Sigil is using a separate "engine" to do the resolution, the OBR, an engine which is dedicated to understand the OSGi metadata and their semantics. -The immediate consequence of this difference is that the built-in resolver is probably less accurate than the Sigil one when it comes to understanding the OSGi dependencies semantics. As explained in this link:osgi-mapping.html[page], the OSGi model doesn't fit well into the Ivy one. +The immediate consequence of this difference is that the built-in resolver is probably less accurate than the Sigil one when it comes to understanding the OSGi dependencies semantics. As explained in this link:osgi-mapping{outfilesuffix}[page], the OSGi model doesn't fit well into the Ivy one. === Source of metadata http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/principle.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/principle.adoc b/asciidoc/principle.adoc index b6c2655..55fb6ca 100644 --- a/asciidoc/principle.adoc +++ b/asciidoc/principle.adoc @@ -23,7 +23,7 @@ Now that you have been introduced to the main Ivy terminology and concepts, it i image::images/main-tasks.png[] -More details on ant tasks link:ant.html[here]. +More details on ant tasks link:ant{outfilesuffix}[here]. == Configure @@ -31,7 +31,7 @@ Ivy needs to be configured to be able to resolve your dependencies. This configu The configuration is also responsible for indicating which resolver should be used to resolve which module. This configuration is dependent only on your environment, i.e. where the modules and artifacts can be found. -A default configuration is used by Ivy when none is given. This configuration uses an link:resolver/ibiblio.html[ibiblio resolver] pointing to https://repo1.maven.org/maven2/ to resolve all modules. +A default configuration is used by Ivy when none is given. This configuration uses an link:resolver/ibiblio{outfilesuffix}[ibiblio resolver] pointing to https://repo1.maven.org/maven2/ to resolve all modules. == Resolve http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/reference.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/reference.adoc b/asciidoc/reference.adoc index 7eb48e8..a753e9a 100644 --- a/asciidoc/reference.adoc +++ b/asciidoc/reference.adoc @@ -19,26 +19,26 @@ Welcome to the Ivy reference documentation! -If you don't know Ivy at all, take a look at its features, the faq and the link:tutorial.html[tutorials] before digging into this reference documentation. +If you don't know Ivy at all, take a look at its features, the faq and the link:tutorial{outfilesuffix}[tutorials] before digging into this reference documentation. == Reference Overview This documentation is broken into several parts: * Introduction -** link:terminology.html[Terminology] +** link:terminology{outfilesuffix}[Terminology] + This part gives you the meaning of some words used all over the Ivy documentation, such as organization, module, configurations, settings, ... -** link:concept.html[Main Concepts] +** link:concept{outfilesuffix}[Main Concepts] + This part introduces the main concepts used in Ivy: dependency resolvers, variables, patterns, and explains a central Ivy concept: module configurations. -** link:principle.html[How does it work ?] +** link:principle{outfilesuffix}[How does it work ?] + As the title suggests, here you will find an explanation of how Ivy does work internally, which can help to better understand and customize its use. -** link:install.html[Installation] +** link:install{outfilesuffix}[Installation] + This part describes how to install Ivy. @@ -46,18 +46,18 @@ This part describes how to install Ivy. + This part describes possibility to control the behavior of Ivy at run time -* link:settings.html[Settings Files] +* link:settings{outfilesuffix}[Settings Files] + This part is dedicated to the specification of the settings file of Ivy (usually called ivysettings.xml). It also gives the list of built-in dependency resolvers available in Ivy. -* link:ivyfile.html[Ivy Files] +* link:ivyfile{outfilesuffix}[Ivy Files] + This part is the reference for the module descriptors, the Ivy files in which you describe your dependencies. If you have any questions about what can be done or not in an Ivy file, you will find the answer here. -* link:ant.html[Ant Tasks] +* link:ant{outfilesuffix}[Ant Tasks] + This part describes how to use Ivy from Ant. It's in this section that all Ant tasks provided by Ivy are specified. -* link:standalone.html[Using standalone] +* link:standalone{outfilesuffix}[Using standalone] + Even though Ivy is most often used from Ant, it can also be used from the command line. This page describes how you can do this. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/resolver/packager.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/resolver/packager.adoc b/asciidoc/resolver/packager.adoc index 34db2ff..37daacc 100644 --- a/asciidoc/resolver/packager.adoc +++ b/asciidoc/resolver/packager.adoc @@ -34,7 +34,7 @@ Packager repositories allow the creation of Ivy repositories that require neither the participation of any of the modules' creators nor setting up a huge mirror site. -The Packager resolver supports a "resource cache", where downloaded archives can be stored to avoid duplicate downloads. This cache is entirely separate from the link:../concept.html#cache[normal Ivy cache]: it is "private" to the Packager resolver, and it stores unmodified original software archives, not Ivy artifacts. See the `resourceCache` attribute below for details. +The Packager resolver supports a "resource cache", where downloaded archives can be stored to avoid duplicate downloads. This cache is entirely separate from the link:../concept{outfilesuffix}#cache[normal Ivy cache]: it is "private" to the Packager resolver, and it stores unmodified original software archives, not Ivy artifacts. See the `resourceCache` attribute below for details. The packaging instructions are contained in "packager.xml" in a simple XML format. At resolve time this file gets converted into a "build.xml" file via XSLT and then executed using link:https://ant.apache.org/[Ant]. Therefore, Ant must be available as an executable on the platform. The Ant task executes in a separate Ant project and so is not affected by properties, etc. that may be set in any existing Ant environment in which Ivy is running. However, Ivy will define a few properties for convenience; see the "Properties" listed below. @@ -46,13 +46,13 @@ For security reasons, the XSLT transform ensures that b. only a very limited set of Ant tasks can be performed during the artifact "build" phase; currently these include move, copy, mkdir, zip, unzip, tar, and untar (this restriction may be overridden however; see below). -The Packager resolver is based on the link:url.html[URL resolver] and is configured similarly, except the artifact child tags specify where to find the packager.xml files, rather than the artifacts themselves. +The Packager resolver is based on the link:url{outfilesuffix}[URL resolver] and is configured similarly, except the artifact child tags specify where to find the packager.xml files, rather than the artifacts themselves. -Because the packaging process is relatively slow, it is important to use link:../concept.html#cache[Ivy's caching support] to avoid repeated execution of the packaging instructions. +Because the packaging process is relatively slow, it is important to use link:../concept{outfilesuffix}#cache[Ivy's caching support] to avoid repeated execution of the packaging instructions. == Attributes -This resolver shares the link:../settings/resolvers.html#common[common attributes] of standard resolvers, plus the following: +This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common attributes] of standard resolvers, plus the following: [options="header",cols="15%,50%,35%"] |======= http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/settings.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/settings.adoc b/asciidoc/settings.adoc index 99edfbe..551717a 100644 --- a/asciidoc/settings.adoc +++ b/asciidoc/settings.adoc @@ -19,9 +19,9 @@ = Ivy Settings -In order to work as you want, Ivy sometimes needs some settings. Actually, Ivy can work with no specific settings at all, see the link:tutorial/defaultconf.html[default settings documentation] for details about that. But Ivy is able to work in very different contexts. You just have to configure it properly. +In order to work as you want, Ivy sometimes needs some settings. Actually, Ivy can work with no specific settings at all, see the link:tutorial/defaultconf{outfilesuffix}[default settings documentation] for details about that. But Ivy is able to work in very different contexts. You just have to configure it properly. -Settings are specified through an XML file, usually called `ivysettings.xml`. To configure Ivy from Ant, you just have to use the link:use/settings.html[settings] datatype with the path of your settings file. +Settings are specified through an XML file, usually called `ivysettings.xml`. To configure Ivy from Ant, you just have to use the link:use/settings{outfilesuffix}[settings] datatype with the path of your settings file. Here is an example of the settings file: @@ -73,43 +73,43 @@ The settings file is structured in some parts and left open in others. In fact, **ivysettings** - * link:settings/property.html[property] - * link:settings/properties.html[properties] - * link:settings/settings.html[settings] - * link:settings/include.html[include] - * link:settings/classpath.html[classpath] - * link:settings/typedef.html[typedef] - * link:settings/credentials.html[credentials] - * link:settings/signers.html[signers] - * link:settings/lock-strategies.html[lock-strategies] - * link:settings/caches.html[caches] - ** link:settings/caches/cache.html[cache] - * link:settings/latest-strategies.html[latest-strategies] - * link:settings/parsers.html[parsers] - * link:settings/namespaces.html[namespaces] - ** link:settings/namespace.html[namespace] - *** link:settings/namespace/rule.html[rule] - **** link:settings/namespace/fromtosystem.html[fromsystem] - ***** link:settings/namespace/src.html[src] - ***** link:settings/namespace/dest.html[dest] - **** link:settings/namespace/fromtosystem.html[tosystem] - ***** link:settings/namespace/src.html[src] - ***** link:settings/namespace/dest.html[dest] - * link:settings/macrodef.html[macrodef] - ** link:settings/macrodef/attribute.html[attribute] + * link:settings/property{outfilesuffix}[property] + * link:settings/properties{outfilesuffix}[properties] + * link:settings/settings{outfilesuffix}[settings] + * link:settings/include{outfilesuffix}[include] + * link:settings/classpath{outfilesuffix}[classpath] + * link:settings/typedef{outfilesuffix}[typedef] + * link:settings/credentials{outfilesuffix}[credentials] + * link:settings/signers{outfilesuffix}[signers] + * link:settings/lock-strategies{outfilesuffix}[lock-strategies] + * link:settings/caches{outfilesuffix}[caches] + ** link:settings/caches/cache{outfilesuffix}[cache] + * link:settings/latest-strategies{outfilesuffix}[latest-strategies] + * link:settings/parsers{outfilesuffix}[parsers] + * link:settings/namespaces{outfilesuffix}[namespaces] + ** link:settings/namespace{outfilesuffix}[namespace] + *** link:settings/namespace/rule{outfilesuffix}[rule] + **** link:settings/namespace/fromtosystem{outfilesuffix}[fromsystem] + ***** link:settings/namespace/src{outfilesuffix}[src] + ***** link:settings/namespace/dest{outfilesuffix}[dest] + **** link:settings/namespace/fromtosystem{outfilesuffix}[tosystem] + ***** link:settings/namespace/src{outfilesuffix}[src] + ***** link:settings/namespace/dest{outfilesuffix}[dest] + * link:settings/macrodef{outfilesuffix}[macrodef] + ** link:settings/macrodef/attribute{outfilesuffix}[attribute] ** any resolver - * link:settings/resolvers.html[resolvers] + * link:settings/resolvers{outfilesuffix}[resolvers] ** any resolver - * link:settings/conflict-managers.html[conflict-managers] - * link:settings/modules.html[modules] - ** link:settings/module.html[module] - * link:settings/outputters.html[outputters] - * link:settings/statuses.html[statuses] - ** link:settings/status.html[status] - * link:settings/triggers.html[triggers] - * link:settings/version-matchers.html[version-matchers] - * link:settings/timeout-constraints.html[timeout-constraints] - ** link:settings/timeout-constraint.html[timeout-constraint] + * link:settings/conflict-managers{outfilesuffix}[conflict-managers] + * link:settings/modules{outfilesuffix}[modules] + ** link:settings/module{outfilesuffix}[module] + * link:settings/outputters{outfilesuffix}[outputters] + * link:settings/statuses{outfilesuffix}[statuses] + ** link:settings/status{outfilesuffix}[status] + * link:settings/triggers{outfilesuffix}[triggers] + * link:settings/version-matchers{outfilesuffix}[version-matchers] + * link:settings/timeout-constraints{outfilesuffix}[timeout-constraints] + ** link:settings/timeout-constraint{outfilesuffix}[timeout-constraint] == ivysettings @@ -124,24 +124,24 @@ Root tag of any Ivy settings file. [options="header"] |======= |Element|Description|Cardinality -|link:settings/property.html[property]|set an Ivy variable|0..n -|link:settings/properties.html[properties]|loads a properties file as Ivy variables|0..n -|link:settings/settings.html[settings]|configures Ivy with some defaults|0..1 -|link:settings/include.html[include]|includes another settings file|0..n -|link:settings/classpath.html[classpath]|add a location in the classpath used to load plugins|0..n -|link:settings/typedef.html[typedef]|defines new types in Ivy|0..n -|link:settings/lock-strategies.html[lock-strategies]|defines lock strategies|0..1 -|link:settings/caches.html[caches]|defines repository cache managers|0..1 -|link:settings/latest-strategies.html[latest-strategies]|defines latest strategies|0..1 -|link:settings/parsers.html[parsers]|defines module descriptor parsers|0..1 -|link:settings/namespaces.html[namespaces]|defines new namespaces|0..1 -|link:settings/macrodef.html[macrodef]|defines a new macro resolver|0..n -|link:settings/resolvers.html[resolvers]|defines dependency resolvers|0..1 -|link:settings/conflict-managers.html[conflict-managers]|defines conflict managers|0..1 -|link:settings/modules.html[modules]|defines rules between modules and dependency resolvers|0..1 -|link:settings/outputters.html[outputters]|defines the list of available report outputters|0..1 -|link:settings/statuses.html[statuses]|defines the list of available statuses|0..1 -|link:settings/triggers.html[triggers]|register triggers on Ivy events|0..1 -|link:settings/version-matchers.html[version-matchers]|defines new version matchers|0..1 -|link:settings/timeout-constraints.html[timeout-constraints]|defines the list of available timeout-constraints|0..n +|link:settings/property{outfilesuffix}[property]|set an Ivy variable|0..n +|link:settings/properties{outfilesuffix}[properties]|loads a properties file as Ivy variables|0..n +|link:settings/settings{outfilesuffix}[settings]|configures Ivy with some defaults|0..1 +|link:settings/include{outfilesuffix}[include]|includes another settings file|0..n +|link:settings/classpath{outfilesuffix}[classpath]|add a location in the classpath used to load plugins|0..n +|link:settings/typedef{outfilesuffix}[typedef]|defines new types in Ivy|0..n +|link:settings/lock-strategies{outfilesuffix}[lock-strategies]|defines lock strategies|0..1 +|link:settings/caches{outfilesuffix}[caches]|defines repository cache managers|0..1 +|link:settings/latest-strategies{outfilesuffix}[latest-strategies]|defines latest strategies|0..1 +|link:settings/parsers{outfilesuffix}[parsers]|defines module descriptor parsers|0..1 +|link:settings/namespaces{outfilesuffix}[namespaces]|defines new namespaces|0..1 +|link:settings/macrodef{outfilesuffix}[macrodef]|defines a new macro resolver|0..n +|link:settings/resolvers{outfilesuffix}[resolvers]|defines dependency resolvers|0..1 +|link:settings/conflict-managers{outfilesuffix}[conflict-managers]|defines conflict managers|0..1 +|link:settings/modules{outfilesuffix}[modules]|defines rules between modules and dependency resolvers|0..1 +|link:settings/outputters{outfilesuffix}[outputters]|defines the list of available report outputters|0..1 +|link:settings/statuses{outfilesuffix}[statuses]|defines the list of available statuses|0..1 +|link:settings/triggers{outfilesuffix}[triggers]|register triggers on Ivy events|0..1 +|link:settings/version-matchers{outfilesuffix}[version-matchers]|defines new version matchers|0..1 +|link:settings/timeout-constraints{outfilesuffix}[timeout-constraints]|defines the list of available timeout-constraints|0..n |======= http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/d7ddccdc/asciidoc/settings/caches.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/settings/caches.adoc b/asciidoc/settings/caches.adoc index 090a28f..deb2aa5 100644 --- a/asciidoc/settings/caches.adoc +++ b/asciidoc/settings/caches.adoc @@ -25,13 +25,13 @@ [ivysettings.caches]#Configures the Ivy cache system.# -See link:../concept.html#cache[cache concept] for details on the Ivy cache concept. +See link:../concept{outfilesuffix}#cache[cache concept] for details on the Ivy cache concept. By default, Ivy defines one repository cache instance, called `default-cache`, which uses the default cache settings defined using attributes on this tag. This default instance is defined as long as you don't define your own default cache using the `default` attribute, and have at least one dependency resolver which doesn't specify which cache instance to use. `defaultCacheDir` is the default directory used for both the resolution and repository cache(s). It usually points to a directory in your filesystem. If you want to isolate resolution cache from repository cache, we recommend setting both the `resolutionCacheDir` and `repositoryCacheDir` attributes on this tag instead of using `defaultCacheDir`. -Since repository cache implementations are pluggable, you can either define new cache instances based on the default implementation provided in Ivy using the link:../settings/caches/cache.html[cache] child element, or use custom cache implementations using child elements as you have defined using link:../settings/typedef.html[typedef]. +Since repository cache implementations are pluggable, you can either define new cache instances based on the default implementation provided in Ivy using the link:../settings/caches/cache{outfilesuffix}[cache] child element, or use custom cache implementations using child elements as you have defined using link:../settings/typedef{outfilesuffix}[typedef]. `ivyPattern` and `artifactPattern` are used to configure the default way Ivy stores Ivy files and artifacts in repository cache(s). Usually you do not have to change this, unless you want to use the cache directly from another tool, which is not recommended. These patterns are relative to the repository cache base directory. @@ -50,9 +50,9 @@ Since repository cache implementations are pluggable, you can either define new |repositoryCacheDir|the path of the default directory to use for repository cache data. *This should not point to a directory used as a repository!*|No, defaults to defaultCacheDir |ivyPattern|default pattern used to indicate where Ivy files should be put in the repository cache(s)|No, defaults to [organisation]/[module]/ivy-[revision].xml |artifactPattern|default pattern used to indicate where artifact files should be put in the repository cache(s)|No, defaults to [organisation]/[module]/[type]s/[artifact]-[revision].[ext] -|[line-through]#checkUpToDate#|__Deprecated, we recommend using overwriteMode on the link:../use/retrieve.html[retrieve] task instead.__ Indicates if date should be checked before retrieving artifacts from cache.|No, defaults to true +|[line-through]#checkUpToDate#|__Deprecated, we recommend using overwriteMode on the link:../use/retrieve{outfilesuffix}[retrieve] task instead.__ Indicates if date should be checked before retrieving artifacts from cache.|No, defaults to true |useOrigin|the default value to use for useOrigin for caches in which it isn't specifically defined. Use true to avoid the copy of local artifacts to the cache and use directly their original location.|No, defaults to false -|lockStrategy|the name of the default link:../settings/lock-strategies.html[lock strategy] to use when accessing repository cache(s)|No, defaults to _no-lock_ +|lockStrategy|the name of the default link:../settings/lock-strategies{outfilesuffix}[lock strategy] to use when accessing repository cache(s)|No, defaults to _no-lock_ |======= @@ -62,7 +62,7 @@ Since repository cache implementations are pluggable, you can either define new [options="header"] |======= |Element|Description|Cardinality -|link:caches/cache.html[cache]|defines a new repository cache instance, based on the default repository cache implementation|0..n +|link:caches/cache{outfilesuffix}[cache]|defines a new repository cache instance, based on the default repository cache implementation|0..n |=======
