mirror of https://github.com/apache/ant-ivy
185 lines
8.7 KiB
HTML
185 lines
8.7 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
<!--
|
|
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
|
|
|
|
http://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.
|
|
-->
|
|
<html>
|
|
<head>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
|
|
<script type="text/javascript">var xookiConfig = {level: 1};</script>
|
|
<script type="text/javascript" src="../xooki/xooki.js"></script>
|
|
</head>
|
|
<body>
|
|
<textarea id="xooki-source">
|
|
The retrieve task copies resolved dependencies anywhere you want in your file system.
|
|
|
|
This is a [[ant:postresolvetask post resolve task]], with all the behaviour and attributes common to all post resolve tasks.
|
|
|
|
<span class="since">since 1.4</span> 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.
|
|
Example:
|
|
pattern: lib/[conf]/[artifact].[ext]
|
|
root: lib
|
|
|
|
<span class="since">since 2.3</span> A nested <a href="http://ant.apache.org/manual/Types/mapper.html">mapper</a> element can be used to specify more complex filename transformations of the retrieved files. See the examples below.
|
|
|
|
<table class="ant">
|
|
<thead>
|
|
<tr><th class="ant-att">Attribute</th><th class="ant-desc">Description</th><th class="ant-req">Required</th></tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td>pattern</td><td>the pattern to use to copy the dependencies</td>
|
|
<td>No. Defaults to ${ivy.retrieve.pattern}</td></tr>
|
|
<tr><td>ivypattern</td><td>the pattern to use to copy the ivy files of dependencies <span class="since">since 1.3</span></td>
|
|
<td>No. Dependencies ivy files are not retrieved by default.</td></tr>
|
|
<tr><td>conf</td><td>a comma separated list of the configurations to retrieve</td>
|
|
<td>No. Defaults to the configurations resolved by the last resolve call, or * if no resolve was explicitly called</td></tr>
|
|
<tr><td>sync</td><td>true to synchronize the destination, false to just make a copy <span class="since">since 1.4</span></td>
|
|
<td>No. Defaults to false</td></tr>
|
|
<tr><td>type</td><td>comma separated list of accepted artifact types <span class="since">since 1.4</span></td>
|
|
<td>No. All artifact types are accepted by default.</td></tr>
|
|
<tr><td>overwriteMode</td><td>option to configure when the destination file should be overwritten if it exist <span class="since">(since 2.2.0)</span>.
|
|
Possible values are:
|
|
<ul><li><b>newer</b> (default)</li> overwrite the destination file if a more recent one is available (based on timestamp)
|
|
<li><b>different</b></li> overwrite the destination file if the timestamp is different
|
|
<li><b>always</b></li> always overwrite the destination file
|
|
<li><b>never</b></li> never overwrite the destination file
|
|
</ul></td><td>No. Defaults to 'newer'.</td></tr>
|
|
<tr><td>symlink</td><td>true to create symbolic links, false to copy the artifacts. The destination of the symbolic links depends on the value of the useOrigin attribute <span class="since">(since 2.0)</span></td><td>No. Defaults to false</td></tr>
|
|
<tr><td>settingsRef</td><td>A reference to the ivy settings that must be used by this task <span class="since">(since 2.0)</span></td><td>No, 'ivy.instance' is taken by default.</td></tr></tbody>
|
|
<tr><td>log</td><td>the log setting to use during the resolve and retrieve process. <span class="since">(since 2.0)</span><br/>
|
|
Available options are the same as for [[ant:resolve]] when used to trigger resolve automatically (see [[ant:postresolvetask]]), or the following for the retrieve process only:
|
|
<ul><li><b>default</b></li> the default log settings, where all usual messages are output to the console
|
|
<li><b>quiet</b></li> disable all usual messages, making the whole retrieve process quiet unless errors occur
|
|
</ul></td><td>No, defaults to 'default'.</td></tr>
|
|
<tr><td>pathId</td><td>the id of the path to create containing the retrieved artifacts. <span class="since">since 2.3</span></td>
|
|
<td>No. No path is created by default.</td></tr>
|
|
<tr><td>setId</td><td>the id of the fileset to create containing the retrieved artifacts. <span class="since">since 2.3</span></td>
|
|
<td>No. No fileset is created by default.</td></tr>
|
|
</table>
|
|
<h1>Examples</h1>
|
|
<code type="xml">
|
|
<ivy:retrieve />
|
|
</code>
|
|
Retrieves dependencies using default parameters. This usually retrieves all the dependencies of the last resolve call to a lib directory.
|
|
|
|
<hr/>
|
|
<code type="xml">
|
|
<ivy:retrieve pattern="${lib.dir}/[conf]/[artifact].[ext]"/>
|
|
</code>
|
|
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:
|
|
<code>
|
|
lib
|
|
default
|
|
commons-lang.jar
|
|
commons-logging.jar
|
|
test
|
|
junit.jar
|
|
</code>
|
|
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.
|
|
|
|
<hr/>
|
|
<code type="xml">
|
|
<ivy:retrieve pattern="${lib.dir}/[conf]/[artifact].[ext]" sync="true" />
|
|
</code>
|
|
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:
|
|
<code>
|
|
lib
|
|
default
|
|
commons-lang.jar
|
|
commons-logging.jar
|
|
test
|
|
junit.jar
|
|
</code>
|
|
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:
|
|
<code>
|
|
lib
|
|
default
|
|
commons-lang.jar
|
|
test
|
|
junit.jar
|
|
</code>
|
|
With no synchronisation, commons-logging would not have been removed by the call.
|
|
|
|
<hr/>
|
|
<code type="xml">
|
|
<ivy:retrieve pattern="${lib.dir}/[type]/[artifact]-[revision].[ext]" conf="runtime"/>
|
|
</code>
|
|
Retrieves only the dependencies of the <code>runtime</code> configuration in directories named by artifact type. The resulting lib dir could look like this:
|
|
<code>
|
|
lib
|
|
jar
|
|
commons-lang-1.0.jar
|
|
looks-1.1.jar
|
|
source
|
|
looks-1.1.zip
|
|
</code>
|
|
|
|
<hr/>
|
|
<code type="xml">
|
|
<ivy:retrieve pattern="${lib.dir}/[organisation]/[artifact]-[revision].[ext]" />
|
|
</code>
|
|
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:
|
|
<code>
|
|
lib
|
|
org.apache
|
|
commons-lang-1.0.jar
|
|
org.junit
|
|
junit-4.1.jar
|
|
junit-4.1.zip
|
|
</code>
|
|
|
|
<code type="xml">
|
|
<ivy:retrieve pattern="${lib.dir}/[orgPath]/[artifact]-[revision].[ext]" />
|
|
</code>
|
|
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:
|
|
<code>
|
|
lib
|
|
org
|
|
apache
|
|
commons-lang-1.0.jar
|
|
junit
|
|
junit-4.1.jar
|
|
junit-4.1.zip
|
|
</code>
|
|
|
|
<hr/>
|
|
<code type="xml">
|
|
<ivy:retrieve organisation="foo" module="bar" inline="true" pattern="${my.install.dir}/[artifact].[ext]"/>
|
|
</code>
|
|
Resolves and retrieve the latest version of the module bar and its dependencies in the directory pointed by ${my.install.dir}.
|
|
<hr/>
|
|
<code type="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>
|
|
</code>
|
|
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.
|
|
</textarea>
|
|
<script type="text/javascript">xooki.postProcess();</script>
|
|
</body>
|
|
</html>
|