asciidoc/use/retrieve.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.
 ////

 The `retrieve` task copies resolved dependencies anywhere you want in your file system.

 This is a link:../use/postresolvetask{outfilesuffix}[post resolve task], with all the behaviour and attributes common to all post resolve tasks.

 (*__since 1.4__*) This task can even be used to synchronize the destination directory with what should actually be in according to the dependency resolution. This means that by setting `sync="true"`, Ivy will not only copy the necessary files, but it will also remove the files which do not need to be there.

 The synchronisation actually consists in deleting all filles and directories in the root destination directory which are not required by the retrieve.

 The root destination directory is the the directory denoted by the first level up the first token in the destination pattern.
 For instance, for the pattern `lib/[conf]/[artifact].[ext]`, the root will be `lib`.

 (*__since 2.3__*) A nested link:https://ant.apache.org/manual/Types/mapper.html[mapper] element can be used to specify more complex filename transformations of the retrieved files. See the examples below.

 == Attributes

 [options="header",cols="15%,50%,35%"]
 |=======
 |Attribute|Description|Required
 |pattern|the pattern to use to copy the dependencies|No. Defaults to `${ivy.retrieve.pattern}`
 |ivypattern|the pattern to use to copy the Ivy files of dependencies (*__since 1.3__*)|No. Dependency Ivy files are not retrieved by default.
 |conf|a comma separated list of the configurations to retrieve|No. Defaults to the configurations resolved by the last resolve call, or `$$*$$` if no resolve was explicitly called
 |sync|`true` to synchronize the destination, false to just make a copy (*__since 1.4__*)|No. Defaults to `false`
 |type|comma separated list of accepted artifact types (*__since 1.4__*)|No. All artifact types are accepted by default.
 |overwriteMode|option to configure when the destination file should be overwritten if it exists (*__since 2.2__*).

 Possible values are: +
 * `newer`: overwrite the destination file if a more recent one is available (based on timestamp) +
 * `different`: overwrite the destination file if the timestamp is different +
 * `always`: always overwrite the destination file +
 * `never`: never overwrite the destination file +
 |No. Defaults to `newer`.
 |symlink|`true` to create symbolic links, `false` to copy the artifacts. The destination of the symbolic links depends on the value of the `useOrigin` attribute. +
 The implementation of this task relies on Java standard `Files.createSymbolicLink` API and depending on whether or not the underlying filesystem supports symbolic links, creation of such symbolic links may or may not work. +
 If this option is set to `true` and symbolic link creation fails, then the retrieve task will attempt to do a regular copy of the artifact which failed symlink creation. (*__since 2.0__*)|No. Defaults to `false`
 |[line-through]#symlinkmass#| *__Deprecated since 2.5__* This option is no longer supported or relevant.|No. Defaults to `false`
 |settingsRef|A reference to Ivy settings that must be used by this task (*__since 2.0__*)|No, defaults ot `ivy.instance`.
 |log|the log setting to use during the resolve and retrieve process. (*__since 2.0__*)

 Available options are the same as for link:../use/resolve{outfilesuffix}[resolve] when used to trigger resolve automatically (see link:../use/postresolvetask{outfilesuffix}[postresolvetask]), or the following for the retrieve process only: +
 * `default`: the default log settings, where all usual messages are output to the console +
 * `quiet`: disable all usual messages, making the whole retrieve process quiet unless errors occur
 |No, defaults to `default`.
 |pathId|the id of the path to create containing the retrieved artifacts. (*__since 2.3__*)|No. No path is created by default.
 |setId|the id of the fileset to create containing the retrieved artifacts. (*__since 2.3__*)|No. No fileset is created by default.
 |=======

 == Examples

 [source,xml]
 ----
 <ivy:retrieve/>
 ----

 Retrieves dependencies using default parameters. This usually retrieves all the dependencies of the last resolve call to a lib directory.

 '''

 [source,xml]
 ----
 <ivy:retrieve pattern="${lib.dir}/[conf]/[artifact].[ext]"/>
 ----

 Retrieves all dependencies of the last resolve call to a lib directory, dependencies being separated in directories named by configuration, each conf directory containing corresponding artifacts without the revision.
 For instance, if the Ivy file declares two configurations default and test, the resulting lib dir could look like this:

 [source]
 ----
 lib
   default
     commons-lang.jar
     commons-logging.jar
   test
     junit.jar
 ----

 Note that if a dependency is required in the two configurations, it will be copied in the two directories. The download of the dependency is however only made once at resolve time.

 '''

 [source,xml]
 ----
 <ivy:retrieve pattern="${lib.dir}/[conf]/[artifact].[ext]" sync="true"/>
 ----

 Same as before, but with synchronisation enabled.

 For instance, if the Ivy file declares two configurations default and test, the resulting lib dir could look like this:

 [source]
 ----
 lib
   default
     commons-lang.jar
     commons-logging.jar
   test
     junit.jar
 ----

 And now suppose commons-logging is no longer part of the dependencies of the default configuration, then a new call to retrieve will result in:

 [source]
 ----
 lib
   default
     commons-lang.jar
   test
     junit.jar
 ----

 With no synchronisation, commons-logging would not have been removed by the call.

 '''

 [source,xml]
 ----
 <ivy:retrieve pattern="${lib.dir}/[type]/[artifact]-[revision].[ext]" conf="runtime"/>
 ----

 Retrieves only the dependencies of the `runtime`. Dependencies separated in directories named by artifact type. The resulting lib dir could look like this:

 [source]
 ----
 lib
   jar
     commons-lang-1.0.jar
     looks-1.1.jar
   source
     looks-1.1.zip
 ----

 '''

 [source,xml]
 ----
 <ivy:retrieve pattern="${lib.dir}/[organisation]/[artifact]-[revision].[ext]"/>
 ----

 Retrieves all dependencies of the last resolve call to a lib directory. The `[organisation]` token will get the unmodified organisation value. The resulting lib dir could look like this:

 [source]
 ----
 lib
   org.apache
     commons-lang-1.0.jar
   org.junit
     junit-4.1.jar
     junit-4.1.zip
 ----

 [source,xml]
 ----
 <ivy:retrieve pattern="${lib.dir}/[orgPath]/[artifact]-[revision].[ext]"/>
 ----

 Retrieves all dependencies of the last resolve call to a lib directory. The `[orgPath]` token will get a tree structure. The resulting lib dir could look like this:

 [source]
 ----
 lib
   org
     apache
       commons-lang-1.0.jar
     junit
       junit-4.1.jar
       junit-4.1.zip
 ----

 '''

 [source,xml]
 ----
 <ivy:retrieve organisation="foo" module="bar" inline="true" pattern="${my.install.dir}/[artifact].[ext]"/>
 ----

 Resolves and retrieves the latest version of the module bar and its dependencies in the directory pointed by `${my.install.dir}`.

 '''

 [source,xml]
 ----
 <ivy:retrieve pattern="lib/[artifact]-[revision].[ext]">
     <firstmatchmapper>
         <globmapper from="lib/*-SNAPSHOT.jar" to="lib/snapshots/*-SNAPSHOT.jar"/>
         <globmapper from="lib/*" to="lib/releases/*"/>
     </firstmatchmapper>
 </ivy:retrieve>
 ----

 Retrieves all dependencies of the last resolve call to a lib directory. The jar files with a version equal to `SNAPSHOT` are retrieved in a `snapshots` directory. The other ones are retrieved in a `releases` directory.
	////
	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.
	////

	The `retrieve` task copies resolved dependencies anywhere you want in your file system.

	This is a link:../use/postresolvetask{outfilesuffix}[post resolve task], with all the behaviour and attributes common to all post resolve tasks.

	(__since 1.4__) This task can even be used to synchronize the destination directory with what should actually be in according to the dependency resolution. This means that by setting `sync="true"`, Ivy will not only copy the necessary files, but it will also remove the files which do not need to be there.

	The synchronisation actually consists in deleting all filles and directories in the root destination directory which are not required by the retrieve.

	The root destination directory is the the directory denoted by the first level up the first token in the destination pattern.
	For instance, for the pattern `lib/[conf]/[artifact].[ext]`, the root will be `lib`.

	(__since 2.3__) A nested link:https://ant.apache.org/manual/Types/mapper.html[mapper] element can be used to specify more complex filename transformations of the retrieved files. See the examples below.

	== Attributes

	[options="header",cols="15%,50%,35%"]
	\|=======
	\|Attribute\|Description\|Required
	\|pattern\|the pattern to use to copy the dependencies\|No. Defaults to `${ivy.retrieve.pattern}`
	\|ivypattern\|the pattern to use to copy the Ivy files of dependencies (__since 1.3__)\|No. Dependency Ivy files are not retrieved by default.
	\|conf\|a comma separated list of the configurations to retrieve\|No. Defaults to the configurations resolved by the last resolve call, or `$$*$$` if no resolve was explicitly called
	\|sync\|`true` to synchronize the destination, false to just make a copy (__since 1.4__)\|No. Defaults to `false`
	\|type\|comma separated list of accepted artifact types (__since 1.4__)\|No. All artifact types are accepted by default.
	\|overwriteMode\|option to configure when the destination file should be overwritten if it exists (__since 2.2__).

	Possible values are: +
	* `newer`: overwrite the destination file if a more recent one is available (based on timestamp) +
	* `different`: overwrite the destination file if the timestamp is different +
	* `always`: always overwrite the destination file +
	* `never`: never overwrite the destination file +
	\|No. Defaults to `newer`.
	\|symlink\|`true` to create symbolic links, `false` to copy the artifacts. The destination of the symbolic links depends on the value of the `useOrigin` attribute. +
	The implementation of this task relies on Java standard `Files.createSymbolicLink` API and depending on whether or not the underlying filesystem supports symbolic links, creation of such symbolic links may or may not work. +
	If this option is set to `true` and symbolic link creation fails, then the retrieve task will attempt to do a regular copy of the artifact which failed symlink creation. (__since 2.0__)\|No. Defaults to `false`
	\|[line-through]#symlinkmass#\| __Deprecated since 2.5__ This option is no longer supported or relevant.\|No. Defaults to `false`
	\|settingsRef\|A reference to Ivy settings that must be used by this task (__since 2.0__)\|No, defaults ot `ivy.instance`.
	\|log\|the log setting to use during the resolve and retrieve process. (__since 2.0__)

	Available options are the same as for link:../use/resolve{outfilesuffix}[resolve] when used to trigger resolve automatically (see link:../use/postresolvetask{outfilesuffix}[postresolvetask]), or the following for the retrieve process only: +
	* `default`: the default log settings, where all usual messages are output to the console +
	* `quiet`: disable all usual messages, making the whole retrieve process quiet unless errors occur
	\|No, defaults to `default`.
	\|pathId\|the id of the path to create containing the retrieved artifacts. (__since 2.3__)\|No. No path is created by default.
	\|setId\|the id of the fileset to create containing the retrieved artifacts. (__since 2.3__)\|No. No fileset is created by default.
	\|=======

	== Examples

	[source,xml]
	----
	<ivy:retrieve/>
	----

	Retrieves dependencies using default parameters. This usually retrieves all the dependencies of the last resolve call to a lib directory.

	'''

	[source,xml]
	----
	<ivy:retrieve pattern="${lib.dir}/[conf]/[artifact].[ext]"/>
	----

	Retrieves all dependencies of the last resolve call to a lib directory, dependencies being separated in directories named by configuration, each conf directory containing corresponding artifacts without the revision.
	For instance, if the Ivy file declares two configurations default and test, the resulting lib dir could look like this:

	[source]
	----
	lib
	default
	commons-lang.jar
	commons-logging.jar
	test
	junit.jar
	----

	Note that if a dependency is required in the two configurations, it will be copied in the two directories. The download of the dependency is however only made once at resolve time.

	'''

	[source,xml]
	----
	<ivy:retrieve pattern="${lib.dir}/[conf]/[artifact].[ext]" sync="true"/>
	----

	Same as before, but with synchronisation enabled.

	For instance, if the Ivy file declares two configurations default and test, the resulting lib dir could look like this:

	[source]
	----
	lib
	default
	commons-lang.jar
	commons-logging.jar
	test
	junit.jar
	----

	And now suppose commons-logging is no longer part of the dependencies of the default configuration, then a new call to retrieve will result in:

	[source]
	----
	lib
	default
	commons-lang.jar
	test
	junit.jar
	----

	With no synchronisation, commons-logging would not have been removed by the call.

	'''

	[source,xml]
	----
	<ivy:retrieve pattern="${lib.dir}/[type]/[artifact]-[revision].[ext]" conf="runtime"/>
	----

	Retrieves only the dependencies of the `runtime`. Dependencies separated in directories named by artifact type. The resulting lib dir could look like this:

	[source]
	----
	lib
	jar
	commons-lang-1.0.jar
	looks-1.1.jar
	source
	looks-1.1.zip
	----

	'''

	[source,xml]
	----
	<ivy:retrieve pattern="${lib.dir}/[organisation]/[artifact]-[revision].[ext]"/>
	----

	Retrieves all dependencies of the last resolve call to a lib directory. The `[organisation]` token will get the unmodified organisation value. The resulting lib dir could look like this:

	[source]
	----
	lib
	org.apache
	commons-lang-1.0.jar
	org.junit
	junit-4.1.jar
	junit-4.1.zip
	----

	[source,xml]
	----
	<ivy:retrieve pattern="${lib.dir}/[orgPath]/[artifact]-[revision].[ext]"/>
	----

	Retrieves all dependencies of the last resolve call to a lib directory. The `[orgPath]` token will get a tree structure. The resulting lib dir could look like this:

	[source]
	----
	lib
	org
	apache
	commons-lang-1.0.jar
	junit
	junit-4.1.jar
	junit-4.1.zip
	----

	'''

	[source,xml]
	----
	<ivy:retrieve organisation="foo" module="bar" inline="true" pattern="${my.install.dir}/[artifact].[ext]"/>
	----

	Resolves and retrieves the latest version of the module bar and its dependencies in the directory pointed by `${my.install.dir}`.

	'''

	[source,xml]
	----
	<ivy:retrieve pattern="lib/[artifact]-[revision].[ext]">
	<firstmatchmapper>
	<globmapper from="lib/-SNAPSHOT.jar" to="lib/snapshots/-SNAPSHOT.jar"/>
	<globmapper from="lib/" to="lib/releases/"/>
	</firstmatchmapper>
	</ivy:retrieve>
	----

	Retrieves all dependencies of the last resolve call to a lib directory. The jar files with a version equal to `SNAPSHOT` are retrieved in a `snapshots` directory. The other ones are retrieved in a `releases` directory.