mirror of https://github.com/apache/ant-ivy
209 lines
8.3 KiB
Plaintext
209 lines
8.3 KiB
Plaintext
////
|
|
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 link:../concept{outfilesuffix}#patterns[pattern] to use to copy the dependencies. Make sure to specify a pattern that defines unique filenames for the artifacts.|No. Defaults to `${ivy.retrieve.pattern}`
|
|
|ivypattern|the link:../concept{outfilesuffix}#patterns[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.
|