asciidoc/settings/resolvers.adoc - ant-ivy - Git at Google

 ////
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      https://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
 ////

 = resolvers

 *Tag:* resolvers

 [ivysettings.resolvers]#Defines a list of dependency resolvers usable in Ivy.# Each dependency resolver is identified by its name, given as an attribute.

 The child tag used for the dependency resolver must be equal to a name of a dependency resolver type (either built-in or added with the typedef tag).

 (*__since 1.3__*) Once defined, resolvers can be referenced by their name, using the following syntax:

 [source, xml]
 ----

 <resolver ref="alreadydefinedresolver"/>

 ----

 Note that this works only if the resolver has already been defined and *NOT* if it is defined later in the Ivy settings file.

 == Child elements


 [options="header"]
 |=======
 |Element|Description|Cardinality
 |any resolver|adds a resolver to the list of available resolvers|1..n
 |=======


 == Built-in Resolvers

 Ivy comes with a set of built-in dependency resolvers that handle most common needs.

 If you don't find the one you want here, you can also check if someone has contributed it on the links page, or even link:../extend{outfilesuffix}[write your own].

 There are basically two types of resolvers in Ivy - composite and standard. A composite resolver is a resolver which delegates the work to other resolvers. The other resolvers are standard resolvers.

 Here is the list of built-in resolvers:


 [options="header",cols="15%,50%,35%"]
 |=======
 |Name|Type|Description
 |link:../resolver/ivyrep{outfilesuffix}[IvyRep]|Standard|Finds Ivy files on ivyrep and artifacts on ibiblio.
 |link:../resolver/ibiblio{outfilesuffix}[IBiblio]|Standard|Finds artifacts on ibiblio.
 |link:../resolver/bintray{outfilesuffix}[BinTray]|Standard|Finds artifacts on bintray.
 |link:../resolver/packager{outfilesuffix}[Packager]|Standard|Finds Ivy files and packaging instructions via URLs, then creates artifacts by following the instructions.
 |link:../resolver/filesystem{outfilesuffix}[FileSystem]|Standard|This very performant resolver finds Ivy files and artifacts in your file system.
 |link:../resolver/url{outfilesuffix}[URL]|Standard|Finds Ivy files and artifacts in any repository accessible with URLs.
 |link:../resolver/url{outfilesuffix}[MirroredURL]|Standard|Finds Ivy files and artifacts in any repository accessible with URLs from a mirror list.
 |link:../resolver/vfs{outfilesuffix}[VFS]|Standard|Finds Ivy files and artifacts in any repository accessible with link:https://commons.apache.org/proper/commons-vfs/[Apache Commons VFS].
 |link:../resolver/ssh{outfilesuffix}[SSH]|Standard|Finds Ivy files and artifacts in any repository accessible with SSH.
 |link:../resolver/sftp{outfilesuffix}[SFTP]|Standard|Finds Ivy files and artifacts in any repository accessible with SFTP.
 |link:../resolver/jar{outfilesuffix}[Jar]|Standard|Finds Ivy files and artifacts within a specified jar.
 |link:../resolver/chain{outfilesuffix}[Chain]|Composite|Delegates the finding to a chain of sub resolvers.
 |link:../resolver/dual{outfilesuffix}[Dual]|Composite|Delegates the finding of Ivy files to one resolver and of artifacts to another.
 |link:../resolver/obr{outfilesuffix}[OBR]|Standard|Resolve modules as OSGi bundles listed by an OSGi obr.xml.
 |link:../resolver/updatesite{outfilesuffix}[Eclipse updatesite]|Standard|Resolve modules as OSGi bundles which are hosted on an Eclipse update site.
 |link:../resolver/osgiagg{outfilesuffix}[OSGi-agg]|Composite|Delegates the finding to a chain of sub resolvers supporting OSGi bundles.
 |=======


 == [[common]]Common features and attributes

 All resolvers of the same type share some common features and attributes detailed here.

 === Features


 ==== validation

 All standard resolvers support several options for validation.

 The `validate` attribute is used to configure if Ivy files should be checked against the Ivy file XML schema.

 The `checkconsistency` attribute allows you to enable or disable consistency checking between what is expected by Ivy when it finds a module descriptor, and what the module descriptor actually contains.

 The `descriptor` attribute lets you define if module descriptors are mandatory or optional.

 The `checksums` attribute is used to define the list of checksums files to use to check if the content of downloaded files has not been corrupted (eg during transfer).

 ==== force

 Any standard resolver can be used in `force` mode, which is used mainly to handle local development builds. In force mode, the resolver attempts to find a dependency whatever the requested revision is (internally it replace the requested revision by `latest.integration`), and if it finds one, it forces this revision to be returned, even when used in a chain with `returnFirst=false`.

 By using such a resolver at the beginning of a chain, you can be sure that Ivy will pick up whatever module is available in this resolver (usually a private local build) instead of the real requested revision. This allows to handle use case like a developer working on modules `A` and `C`, where `A -> B -> C`, and pick up the local build for `C` without having to publish a local version of `B`. (*__since 2.0__*)

 ==== timeoutConstraint

 [*__since 2.5__*]

 All standard resolvers support the `timeoutConstraint` attribute. The value for this attribute is the name of the link:timeout-constraint{outfilesuffix}[timeout-constraint] that's been defined in the Ivy settings.

 Resolvers can be optionally configured to use a `timeoutConstraint` so that the timeouts defined on that constraint dictate how the resolvers behave when it comes to dealing with timeouts while establishing connections and reading content, during module descriptor and artifact resolutions.

 ==== Maven

 Any resolver which is able to parse a Maven pom.xml file has to detect the related sources or javadocs artifacts. This often involves several network connections even if neither the sources nor the javadoc are requested to be downloaded.

 (*__since 2.5__*) Setting the property `ivy.maven.lookup.sources` to `false` disables the lookup of the sources artifact.
 And setting the property `ivy.maven.lookup.javadoc` to `false` disables the lookup of the javadoc artifact.

 === Attributes

 [options="header",cols="15%,50%,12%,12%,12%"]
 |=======
 |Attribute|Description|Required|Composite|Standard
 |name|the name which identifies the resolver|Yes|Yes|Yes
 |validate|indicates if resolved Ivy files should be validated against Ivy XSD|No, defaults to call setting|Yes|Yes
 |force|Indicates if this resolver should be used in force mode (see above). (*__since 2.0__*)|No, defaults to false|No|Yes
 |checkmodified|Indicates if this resolver should check lastmodified date to know if an Ivy file is up to date.|No, defaults to ${ivy.resolver.default.check.modified}|No|Yes
 |changingPattern|Indicates for which revision pattern this resolver should check lastmodified date to know if an artifact file is up to date (*__since 1.4__*). See link:../concept{outfilesuffix}#change[cache and change management] for details.|No, defaults to none|Yes|Yes
 |changingMatcher|The name of the link:../concept{outfilesuffix}#matcher[pattern matcher] to use to match a revision against the configured changingPattern (*__since 1.4__*). See link:../concept{outfilesuffix}#change[cache and change management] for details.|No, defaults to exactOrRegexp|Yes|Yes
 |alwaysCheckExactRevision|Indicates if this resolver should check the given revision even if it's a special one (like latest.integration) (*__since 1.3__*).|No, defaults to ${ivy.default.always.check.exact.revision}|No|Yes
 |namespace|The name of the namespace to which this resolver belongs (*__since 1.3__*)|No, defaults to 'system'|Yes|Yes
 |checkconsistency|true to check consistency of module descriptors found by this resolver, false to avoid consistency check (*__since 1.3__*)|No, defaults to true|No|Yes
 |descriptor|'optional' if a module descriptor (usually an Ivy file) is optional for this resolver, 'required' to refuse modules without module descriptor (*__since 2.0__*)|No, defaults to 'optional'|No (except dual)|Yes
 |[line-through]#allownomd#|__Deprecated, we recommend using descriptor="required \| optional" instead.__ true if the absence of module descriptor (usually an Ivy file) is authorised for this resolver, false to refuse modules without module descriptor (*__since 1.4__*)|No, defaults to true|No (except dual)|Yes
 |checksums|a comma separated list of link:../concept{outfilesuffix}#checksum[checksum algorithms] to use both for publication and checking (*__since 1.4__*)|No, defaults to ${ivy.checksums}|No|Yes
 |latest|The name of the latest strategy to use.|No, defaults to 'default'|Yes|Yes
 |cache|The name of the cache manager to use.|No, defaults to the value of the default attribute of caches|No|Yes
 |signer|The name of the link:../settings/signers{outfilesuffix}[detached signature generator] to use when publishing artifacts. (*__since 2.2__*)|No, by default published artifacts will not get signed by Ivy.|No|Yes
 |timeoutConstraint|The name of the link:timeout-constraint{outfilesuffix}[timeout-constraint] to use for the resolver. (*__since 2.5__*)|No. In the absence of a `timeoutConstraint`, the resolver's behaviour with timeouts is implementation specific.|No|Yes
 |=======


 == Examples


 [source, xml]
 ----

 <resolvers>
   <filesystem name="1" cache="cache-1">
     <ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
     <artifact pattern="${ivy.settings.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
   </filesystem>
   <chain name="chain1">
     <resolver ref="1"/>
     <ivyrep name="ivyrep"/>
   </chain>
   <chain name="chain2" returnFirst="true" dual="true">
     <resolver ref="1"/>
     <ibiblio name="ibiblio"/>
   </chain>
 </resolvers>

 ----

 Defines a filesystem resolver, named `1`, which is then used in two chains, the first combining the filesystem resolver with an ivyrep resolver, and second combining the filesystem resolver with an ibiblio resolver, which returns the first module found, and uses the whole chain to download artifacts (see corresponding resolvers documentation for details about them). Resolver `1` will use a cache named `cache-1` which should have been defined in the caches element.
	////
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	https://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	////

	= resolvers

	Tag: resolvers

	[ivysettings.resolvers]#Defines a list of dependency resolvers usable in Ivy.# Each dependency resolver is identified by its name, given as an attribute.

	The child tag used for the dependency resolver must be equal to a name of a dependency resolver type (either built-in or added with the typedef tag).

	(__since 1.3__) Once defined, resolvers can be referenced by their name, using the following syntax:

	[source, xml]
	----

	<resolver ref="alreadydefinedresolver"/>

	----

	Note that this works only if the resolver has already been defined and NOT if it is defined later in the Ivy settings file.

	== Child elements


	[options="header"]
	\|=======
	\|Element\|Description\|Cardinality
	\|any resolver\|adds a resolver to the list of available resolvers\|1..n
	\|=======



	== Built-in Resolvers

	Ivy comes with a set of built-in dependency resolvers that handle most common needs.

	If you don't find the one you want here, you can also check if someone has contributed it on the links page, or even link:../extend{outfilesuffix}[write your own].

	There are basically two types of resolvers in Ivy - composite and standard. A composite resolver is a resolver which delegates the work to other resolvers. The other resolvers are standard resolvers.

	Here is the list of built-in resolvers:


	[options="header",cols="15%,50%,35%"]
	\|=======
	\|Name\|Type\|Description
	\|link:../resolver/ivyrep{outfilesuffix}[IvyRep]\|Standard\|Finds Ivy files on ivyrep and artifacts on ibiblio.
	\|link:../resolver/ibiblio{outfilesuffix}[IBiblio]\|Standard\|Finds artifacts on ibiblio.
	\|link:../resolver/bintray{outfilesuffix}[BinTray]\|Standard\|Finds artifacts on bintray.
	\|link:../resolver/packager{outfilesuffix}[Packager]\|Standard\|Finds Ivy files and packaging instructions via URLs, then creates artifacts by following the instructions.
	\|link:../resolver/filesystem{outfilesuffix}[FileSystem]\|Standard\|This very performant resolver finds Ivy files and artifacts in your file system.
	\|link:../resolver/url{outfilesuffix}[URL]\|Standard\|Finds Ivy files and artifacts in any repository accessible with URLs.
	\|link:../resolver/url{outfilesuffix}[MirroredURL]\|Standard\|Finds Ivy files and artifacts in any repository accessible with URLs from a mirror list.
	\|link:../resolver/vfs{outfilesuffix}[VFS]\|Standard\|Finds Ivy files and artifacts in any repository accessible with link:https://commons.apache.org/proper/commons-vfs/[Apache Commons VFS].
	\|link:../resolver/ssh{outfilesuffix}[SSH]\|Standard\|Finds Ivy files and artifacts in any repository accessible with SSH.
	\|link:../resolver/sftp{outfilesuffix}[SFTP]\|Standard\|Finds Ivy files and artifacts in any repository accessible with SFTP.
	\|link:../resolver/jar{outfilesuffix}[Jar]\|Standard\|Finds Ivy files and artifacts within a specified jar.
	\|link:../resolver/chain{outfilesuffix}[Chain]\|Composite\|Delegates the finding to a chain of sub resolvers.
	\|link:../resolver/dual{outfilesuffix}[Dual]\|Composite\|Delegates the finding of Ivy files to one resolver and of artifacts to another.
	\|link:../resolver/obr{outfilesuffix}[OBR]\|Standard\|Resolve modules as OSGi bundles listed by an OSGi obr.xml.
	\|link:../resolver/updatesite{outfilesuffix}[Eclipse updatesite]\|Standard\|Resolve modules as OSGi bundles which are hosted on an Eclipse update site.
	\|link:../resolver/osgiagg{outfilesuffix}[OSGi-agg]\|Composite\|Delegates the finding to a chain of sub resolvers supporting OSGi bundles.
	\|=======



	== [[common]]Common features and attributes

	All resolvers of the same type share some common features and attributes detailed here.

	=== Features


	==== validation

	All standard resolvers support several options for validation.

	The `validate` attribute is used to configure if Ivy files should be checked against the Ivy file XML schema.

	The `checkconsistency` attribute allows you to enable or disable consistency checking between what is expected by Ivy when it finds a module descriptor, and what the module descriptor actually contains.

	The `descriptor` attribute lets you define if module descriptors are mandatory or optional.

	The `checksums` attribute is used to define the list of checksums files to use to check if the content of downloaded files has not been corrupted (eg during transfer).

	==== force

	Any standard resolver can be used in `force` mode, which is used mainly to handle local development builds. In force mode, the resolver attempts to find a dependency whatever the requested revision is (internally it replace the requested revision by `latest.integration`), and if it finds one, it forces this revision to be returned, even when used in a chain with `returnFirst=false`.

	By using such a resolver at the beginning of a chain, you can be sure that Ivy will pick up whatever module is available in this resolver (usually a private local build) instead of the real requested revision. This allows to handle use case like a developer working on modules `A` and `C`, where `A -> B -> C`, and pick up the local build for `C` without having to publish a local version of `B`. (__since 2.0__)

	==== timeoutConstraint

	[__since 2.5__]

	All standard resolvers support the `timeoutConstraint` attribute. The value for this attribute is the name of the link:timeout-constraint{outfilesuffix}[timeout-constraint] that's been defined in the Ivy settings.

	Resolvers can be optionally configured to use a `timeoutConstraint` so that the timeouts defined on that constraint dictate how the resolvers behave when it comes to dealing with timeouts while establishing connections and reading content, during module descriptor and artifact resolutions.

	==== Maven

	Any resolver which is able to parse a Maven pom.xml file has to detect the related sources or javadocs artifacts. This often involves several network connections even if neither the sources nor the javadoc are requested to be downloaded.

	(__since 2.5__) Setting the property `ivy.maven.lookup.sources` to `false` disables the lookup of the sources artifact.
	And setting the property `ivy.maven.lookup.javadoc` to `false` disables the lookup of the javadoc artifact.

	=== Attributes

	[options="header",cols="15%,50%,12%,12%,12%"]
	\|=======
	\|Attribute\|Description\|Required\|Composite\|Standard
	\|name\|the name which identifies the resolver\|Yes\|Yes\|Yes
	\|validate\|indicates if resolved Ivy files should be validated against Ivy XSD\|No, defaults to call setting\|Yes\|Yes
	\|force\|Indicates if this resolver should be used in force mode (see above). (__since 2.0__)\|No, defaults to false\|No\|Yes
	\|checkmodified\|Indicates if this resolver should check lastmodified date to know if an Ivy file is up to date.\|No, defaults to ${ivy.resolver.default.check.modified}\|No\|Yes
	\|changingPattern\|Indicates for which revision pattern this resolver should check lastmodified date to know if an artifact file is up to date (__since 1.4__). See link:../concept{outfilesuffix}#change[cache and change management] for details.\|No, defaults to none\|Yes\|Yes
	\|changingMatcher\|The name of the link:../concept{outfilesuffix}#matcher[pattern matcher] to use to match a revision against the configured changingPattern (__since 1.4__). See link:../concept{outfilesuffix}#change[cache and change management] for details.\|No, defaults to exactOrRegexp\|Yes\|Yes
	\|alwaysCheckExactRevision\|Indicates if this resolver should check the given revision even if it's a special one (like latest.integration) (__since 1.3__).\|No, defaults to ${ivy.default.always.check.exact.revision}\|No\|Yes
	\|namespace\|The name of the namespace to which this resolver belongs (__since 1.3__)\|No, defaults to 'system'\|Yes\|Yes
	\|checkconsistency\|true to check consistency of module descriptors found by this resolver, false to avoid consistency check (__since 1.3__)\|No, defaults to true\|No\|Yes
	\|descriptor\|'optional' if a module descriptor (usually an Ivy file) is optional for this resolver, 'required' to refuse modules without module descriptor (__since 2.0__)\|No, defaults to 'optional'\|No (except dual)\|Yes
	\|[line-through]#allownomd#\|__Deprecated, we recommend using descriptor="required \\| optional" instead.__ true if the absence of module descriptor (usually an Ivy file) is authorised for this resolver, false to refuse modules without module descriptor (__since 1.4__)\|No, defaults to true\|No (except dual)\|Yes
	\|checksums\|a comma separated list of link:../concept{outfilesuffix}#checksum[checksum algorithms] to use both for publication and checking (__since 1.4__)\|No, defaults to ${ivy.checksums}\|No\|Yes
	\|latest\|The name of the latest strategy to use.\|No, defaults to 'default'\|Yes\|Yes
	\|cache\|The name of the cache manager to use.\|No, defaults to the value of the default attribute of caches\|No\|Yes
	\|signer\|The name of the link:../settings/signers{outfilesuffix}[detached signature generator] to use when publishing artifacts. (__since 2.2__)\|No, by default published artifacts will not get signed by Ivy.\|No\|Yes
	\|timeoutConstraint\|The name of the link:timeout-constraint{outfilesuffix}[timeout-constraint] to use for the resolver. (__since 2.5__)\|No. In the absence of a `timeoutConstraint`, the resolver's behaviour with timeouts is implementation specific.\|No\|Yes
	\|=======



	== Examples


	[source, xml]
	----

	<resolvers>
	<filesystem name="1" cache="cache-1">
	<ivy pattern="${ivy.settings.dir}/1/[organisation]/[module]/ivys/ivy-[revision].xml"/>
	<artifact pattern="${ivy.settings.dir}/1/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
	</filesystem>
	<chain name="chain1">
	<resolver ref="1"/>
	<ivyrep name="ivyrep"/>
	</chain>
	<chain name="chain2" returnFirst="true" dual="true">
	<resolver ref="1"/>
	<ibiblio name="ibiblio"/>
	</chain>
	</resolvers>

	----

	Defines a filesystem resolver, named `1`, which is then used in two chains, the first combining the filesystem resolver with an ivyrep resolver, and second combining the filesystem resolver with an ibiblio resolver, which returns the first module found, and uses the whole chain to download artifacts (see corresponding resolvers documentation for details about them). Resolver `1` will use a cache named `cache-1` which should have been defined in the caches element.