| <!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. |
| (requires "ln" to be a valid command, and to support the options -s and -f (works on UNIX/Linux, on other systems you may need to script "ln") |
| <span class="since">(since 2.0)</span></td><td>No. Defaults to false</td></tr> |
| <tr><td>symlinkmass</td><td>true to create symbolic links in mass, false to copy the artifacts. |
| "symlinkmass" overrides "symlink" if both are set to "true". |
| "symlinkmass" will create the same symbolic links "symlink" does, but with a single process call to "sh" with batched "ln" commands passed in as standard input (works on UNIX/Linux, on other systems you may need to script it) |
| Far large lists of resolved jars, this can be dramatically faster. |
| The destination of the symbolic links depends on the value of the useOrigin attribute. |
| The events "StartRetrieveArtifactEvent" and EndRetrieveEvent are NOT fired by this activity, because it is not clear when they should be called. |
| <span class="since">(since 2.4)</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> |