 ------
 Task and Type Reference
 ------
 Brett Porter
 Hervé Boutemy
 ------
 2008-07-17
 ------

~~ 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.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

{Task} Reference

  ~~ TODO: Can the task and type classes be generated using Modello?
  ~~ If so, the reference documentation can be generated from the model.

* <<<{dependencies}>>>

  This task will check if any of the specified dependencies, and their dependencies are missing or updated, and
  download them if necessary. The dependencies will be made available as a fileset or path reference.

  The dependencies task accepts the following attributes:

*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<Attribute>>           | <<Description>>                                                           | <<Required>> | << Since >> |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<filesetId>>>         | The reference ID to store a fileset under, for the resolved dependencies. | No           |             |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<javadocFilesetId>>>  | The reference ID to store a fileset under, for the javadoc attachements of the resolved dependencies. | No | 2.0.9 |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<pathId>>>            | The reference ID to store a path under, for the resolved dependencies.    | No           |             |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<pomRefId>>>          | The reference ID from a POM datatype defined earlier in the build file.   | Yes, either this or a <<<pom>>> nested element or one or more <<<dependency>>> nested elements | |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<settingsFile>>>      | The settings file to use. Defaults to <<<$\{user.home\}/.ant/settings.xml>>> or if that doesn't exist <<<$\{user.home\}/.m2/settings.xml>>>. | No | 2.0.6 |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<sourcesFilesetId>>>  | The reference ID to store a fileset under, for the sources attachements of the resolved dependencies. | No | 2.0.6 |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<type>>>              | A comma separated list of artifact types to be retrieved. By default all artifact types will be included.   | No     |    |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<useScope>>>          | Follows the maven scope behaviour.  Can be set to <<<compile>>>, <<<runtime>>>, or <<<test>>>.  If no value is provided, all scopes will be included.  | No   |    |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<scopes>>>            | A comma separated list of specific scopes to be retrieved.  If no value is provided, all scopes will be included.  | No   |  2.0.10  |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<verbose>>>           | If <<<true>>> this displays the results of each dependency resolution and their relationships. Default is <false>. | No | |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<versionsId>>>        | The property ID to store the versions of the resolved dependencies, for use by a {{{reference.html#VersionMapper} <<<VersionMapper>>>}}. | No | 2.0.7 |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<addArtifactFileSetRefs>>> | If set to true, will add a fileset for each resolved dependency.  The fileset has an id of <<<groupId:artifactId:type[:classifier]>>>.  Default is <false>.  | No | 2.0.10 |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+

  The task can include the <<<dependency>>> nested type, in addition to the other shared types
  {{{reference.html#localRepository} <<<localRepository>>>}}, {{{reference.html#pom} <<<pom>>>}} and
  {{{reference.html#remoteRepository} <<<remoteRepository>>>}}, which will be explained later.

  You must include either
      a single <<<pom>>> element
      or a <<<pomRefId>>> attribute
      or one or more <<<dependency>>> elements.

  If you have set a value for <<<versionsId>>>, you can later use {{{reference.html#versionMapper} <<<VersionMapper>>>}}.

  <(since 2.0.8)> For each dependency resolved, the property <<<groupId:artifactId:type[:classifier]>>> is defined pointing to
  the corresponding file.

** <<<dependency>>>

  ~~ TODO: Is system scope supported, in the table below?

*------------------+--------------------------------------------------------+--------------+
| <<Attribute>>    | <<Description>>                                        | <<Required>> |
*------------------+--------------------------------------------------------+--------------+
| <<<groupId>>>    | The group ID of the dependency.                        | Yes          |
*------------------+--------------------------------------------------------+--------------+
| <<<artifactId>>> | The artifact ID of the dependency.                     | Yes          |
*------------------+--------------------------------------------------------+--------------+
| <<<version>>>    | The version of the dependency.                         | Yes          |
*------------------+--------------------------------------------------------+--------------+
| <<<type>>>       | The type of the dependency. The default is <<<jar>>>.  | No           |
*------------------+--------------------------------------------------------+--------------+
| <<<scope>>>      | The scope of the usage of the dependency, which affects which of that dependency's own dependencies are also retrieved. This can be <<<compile>>>, <<<runtime>>>, <<<test>>>, <<<provided>>>. | No |
*------------------+--------------------------------------------------------+--------------+

  The dependency can also nest multiple <<<exclusion>>> elements.

*** <<<exclusion>>>

  An exclusion can be used to prevent the resolution of a particular artifact in the tree of the <<<dependency>>>.

*------------------+--------------------------------------------------------+--------------+
| <<Attribute>>    | <<Description>>                                        | <<Required>> |
*------------------+--------------------------------------------------------+--------------+
| <<<groupId>>>    | The group ID of the dependency to exclude.             | Yes          |
*------------------+--------------------------------------------------------+--------------+
| <<<artifactId>>> | The artifact ID of the dependency to exclude.          | Yes          |
*------------------+--------------------------------------------------------+--------------+

* <<<{install}>>>, <<<{deploy}>>>

  These tasks will install/deploy the given file into the local/remote repository. It is stored using the information in the supplied
  POM. Multiple artifacts can be attached during install/deploy using <<<attach>>> elements.

*---------------------+--------------------------------------------------------------------------+-------------------------------------------------+-------------+
| <<Attribute>>       | <<Description>>                                                          | <<Required>>                                    | << Since >> |
*---------------------+--------------------------------------------------------------------------+-------------------------------------------------+-------------+
| <<<file>>>          | The file to install in the repository.                                   | Yes, except if packaging is <<<pom>>>           |             |
*---------------------+--------------------------------------------------------------------------+-------------------------------------------------+-------------+
| <<<pomRefId>>>      | The reference ID from a POM datatype defined earlier in the build file.  | No, if a <<<pom>>> nested element is provided instead |       |
*---------------------+--------------------------------------------------------------------------+-------------------------------------------------+-------------+
| <<<settingsFile>>>  | The settings file to use. Defaults to <<<$\{user.home\}/.ant/settings.xml>>> or if that doesn't exist <<<$\{user.home\}/.m2/settings.xml>>>. | No | 2.0.6 |
*---------------------+--------------------------------------------------------------------------+-------------------------------------------------+-------------+
| <<<uniqueVersion>>> | (<<<deploy>>> only) Whether to assign snapshots a unique version comprised of the timestamp and build number, or to use the same version each time | No, the default is <<<true>>>. | |
*---------------------+--------------------------------------------------------------------------+-------------------------------------------------+-------------+

  The task must take either a nested {{{reference.html#pom} <<<pom>>>}} element, or a <<<pomRefId>>> attribute. Both release and <<<-SNAPSHOT>>> versions are supported.
  The task can have an optional {{{reference.html#localRepository} <<<localRepository>>>}} nested element.

  <<<deploy>>> can have an optional {{{reference.html#remoteRepository} <<<remoteRepository>>>}} nested element. If no
  <<<remoteRepository>>> nested element is given, the <<<distributionManagement>>> section of the POM is used.

** <<<attach>>> <(since 2.0.6)>

  Multiple artifacts can be attached to the main artifact, for example: sources, javadocs, ...

*------------------+--------------------------------------------------------+--------------+
| <<Attribute>>    | <<Description>>                                        | <<Required>> |
*------------------+--------------------------------------------------------+--------------+
| <<<file>>>       | The file to attach.                                    | Yes          |
*------------------+--------------------------------------------------------+--------------+
| <<<type>>>       | The type of the file. Defaults to <<<jar>>>.           | No           |
*------------------+--------------------------------------------------------+--------------+
| <<<classifier>>> | The classifier of the file.                            | No           |
*------------------+--------------------------------------------------------+--------------+

* <<<{install-provider}>>>

  This task will install a Wagon provider, to add support for more protocols.

*------------------+--------------------------------------------------------------------------+--------------+-------------+
| <<Attribute>>    | <<Description>>                                                          | <<Required>> | << Since >> |
*------------------+--------------------------------------------------------------------------+--------------+-------------+
| <<<artifactId>>> | The artifact ID of the provider to install.                              | Yes          |             |
*------------------+--------------------------------------------------------------------------+--------------+-------------+
| <<<groupId>>>    | The group ID of the provider to install. The default is <<<org.apache.maven.wagon>>>. | No | 2.0.7    |
*------------------+--------------------------------------------------------------------------+--------------+-------------+
| <<<version>>>    | The version of the provider to install.                                  | Yes          |             |
*------------------+--------------------------------------------------------------------------+--------------+-------------+


{Type} Reference

* <<<{localRepository}>>>

  Specifies the location of the local repository of artifacts.
  ~~ TODO: id/refid

*------------------+--------------------------------------------------------+--------------+-------------+
| <<Attribute>>    | <<Description>>                                        | <<Required>> | << Since >> |
*------------------+--------------------------------------------------------+--------------+-------------+
| <<<layout>>>     | The layout of the local repository. The valid options are <<<legacy>>> (Maven 1), or <<<default>>> (Maven 2). Defaults to <<<default>>>. | No | |
*------------------+--------------------------------------------------------+--------------+-------------+
| <<<path>>>       | The directory of the local repository.                 | Yes          | 2.0.7       |
*------------------+--------------------------------------------------------+--------------+-------------+

  <<Note>>: until 2.0.6, attribute <<<path>>> was named <<<location>>>, but this changed in 2.0.7 to solve a conflict with Ant 1.7.

* <<<{remoteRepository}>>>

  Specifies the location of the remote repository.
  ~~ TODO: id/refid

*----------------------+--------------------------------------------------------+--------------+
| <<Attribute>>        | <<Description>>                                        | <<Required>> |
*----------------------+--------------------------------------------------------+--------------+
| <<<id>>>             | A unique ID of the repository.                         | Yes          |
*----------------------+--------------------------------------------------------+--------------+
| <<<url>>>            | The URL of the repository.                             | Yes          |
*----------------------+--------------------------------------------------------+--------------+
| <<<layout>>>         | The layout of the remote repository. The valid options are <<<legacy>>> (Maven 1), or <<<default>>> (Maven 2). Defaults to <<<default>>>. | No |
*----------------------+--------------------------------------------------------+--------------+

  The <<<remoteRepository>>> can have the following nested elements: <<<releases>>>, <<<snapshots>>>, <<<authentication>>> and <<<proxy>>>.

** <<<releases>>>, <<<snapshots>>>

  Policies about downloading different types of artifacts.

*----------------------+--------------------------------------------------------+--------------+
| <<Attribute>>        | <<Description>>                                        | <<Required>> |
*----------------------+--------------------------------------------------------+--------------+
| <<<checksumPolicy>>> | How to treat missing or incorrect checksums for the dependencies that are downloaded. Valid values are <<<warn>>> (<default>) and <<<fail>>>. | No |
*----------------------+--------------------------------------------------------+--------------+
| <<<enabled>>>        | Whether to download this type of artifact from the repository. Default is <<<true>>>. | No |
*----------------------+--------------------------------------------------------+--------------+
| <<<updatePolicy>>>   | How often to check for updates on dependencies that are snapshots or include a range of versions. Valid values are <<<never>>>, <<<interval:MINUTES>>>, <<<daily>>> (<default>), <<<always>>>. | No |
*----------------------+--------------------------------------------------------+--------------+

** <<<authentication>>>

  The authentication element is used for passing a username, password and other credentials to the repository either
  on upload or download. The content is the same as for <<<server>>> in the {{{http://maven.apache.org/maven-settings/settings.html#class_server} settings reference}}.

** <<<proxy>>>

  The proxy element is typically used for HTTP repositories. The content is the same as for <<<proxy>>> in the
  {{{http://maven.apache.org/maven-settings/settings.html#class_proxy} settings reference}}.

* <<<{pom}>>>

  The POM element will load a POM file and make it available as a reference for the other tasks or as properties.

*------------------+--------------------------------------------------------+--------------+
| <<Attribute>>    | <<Description>>                                        | <<Required>> |
*------------------+--------------------------------------------------------+--------------+
| <<<file>>>       | The file of the POM to load.                           | Yes          |
*------------------+--------------------------------------------------------+--------------+
| <<<id>>>         | The reference ID of this POM.                          | No           |
*------------------+--------------------------------------------------------+--------------+
| <<<settingsFile>>>  | The settings file to use. Defaults to <<<$\{user.home\}/.ant/settings.xml>>> or if that doesn't exist <<<$\{user.home\}/.m2/settings.xml>>>. | No | 2.0.6 |
*---------------------+--------------------------------------------------------------------------+-------------------------------------------------+-------------+

** <<<profile>>> <(since 2.0.10)>

  Multiple profile elements can be nested within the pom element.  By default the profile
  will be activated.  If <<active>> is set to false, then the profile will be explicitly
  deactivated.

*------------------+--------------------------------------------------------+--------------+
| <<Attribute>>    | <<Description>>                                        | <<Required>> |
*------------------+--------------------------------------------------------+--------------+
| <<<id>>>         | The id of the profile to be activated/deactivated.     | Yes          |
*------------------+--------------------------------------------------------+--------------+
| <<<active>>>     | Set to <<<true>>> or <<<false>>> to determine whether the profile should be active. Default is <<<true>>>. | No    |
*------------------+--------------------------------------------------------+--------------+

* <<<{versionMapper}>>> <(since 2.0.7)>

  This is a {{{http://ant.apache.org/manual/CoreTypes/mapper.html}filename mapper}}
  that removes version info from the filename when copying dependencies. It can
  also, optionally, remove the directory info from the filename.

  The full class name to use in <<<classname>>> attribute of <<<\<mapper\>>>> element is
  <<<org.apache.maven.artifact.ant.VersionMapper>>>.

*------------------+--------------------------------------------------------+--------------+
| <<Attribute>>    | <<Description>>                                        | <<Required>> |
*------------------+--------------------------------------------------------+--------------+
| <<<from>>>       | The versions of the dependencies, as set by <<<versionsId>>> attribute of <<<dependencies>>> task. | Yes |
*------------------+--------------------------------------------------------+--------------+
| <<<to>>>         | If this is set to <<<flatten>>> the directory info is also removed from the filename. | No |
*------------------+--------------------------------------------------------+--------------+

  You can see a full working example in the {{{examples/dependencies.html} examples}}.