 ------
 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  |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<versionsId>>>        | The property ID to store the versions of the resolved dependencies, for use by a {{{reference.html#VersionMapper} <<<VersionMapper>>>}}. | No | 2.0.7 |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<cacheDependencyRefs>>> | If set to true, will generate an Ant build file that contains properties and fileset references for the dependencies.  Then try to load information from this file in subsequent builds.  Default is <false>.  | No | 2.1.0 |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<addArtifactFileSetRefs>>> | Defines the name of the file in which to store properties and references to the paths of dependency artifacts.  Default is <false>.  | No | 2.1.0 |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<addArtifactFileSetRefs>>> | <<Deprecated>> in version 2.1.0.  The dependencies task will always add a fileset with id of <<<groupId:artifactId:type[:classifier]>>>.  Default is <true>.  |   | 2.0.10 |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+
| <<<verbose>>>           | <<Deprecated>> in version 2.1.0.  Use the Ant command line -v option for verbose output.     | No | |
*-------------------------+---------------------------------------------------------------------------+--------------+-------------+

  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           |
*------------------+--------------------------------------------------------+--------------+
| <<<classifier>>> | The classifier of the dependency.                      | 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, unless an attached artifact is specified   |             |
*---------------------+--------------------------------------------------------------------------+-------------------------------------------------+-------------+
| <<<pomRefId>>>      | The reference ID from a POM datatype defined earlier in the build file.  | Yes, unless 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          |             |
*------------------+--------------------------------------------------------------------------+--------------+-------------+

* <<<{writepom}>>> <(since 2.1.0)>

  This task will write a POM object to a file.

*------------------+--------------------------------------------------------------------------+--------------+
| <<Attribute>>    | <<Description>>                                                          | <<Required>> |
*------------------+--------------------------------------------------------------------------+--------------+
| <<<pomRefId>>>   | The ID of the POM to write.                                              | Yes          |
*------------------+--------------------------------------------------------------------------+--------------+
| <<<file>>>       | The name of the file to write the POM                                    | Yes          |
*------------------+--------------------------------------------------------------------------+--------------+
| <<<trim>>>       | A boolean value to determine whether unnecessary information should be removed from the POM.  Defaults to <<<true>>>.   | No           |
*------------------+--------------------------------------------------------------------------+--------------+


{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>> | << Since >> |
*------------------+--------------------------------------------------------+--------------+-------------+
| <<<file>>>       | The file of the POM to load.                           | Yes          |
*------------------+--------------------------------------------------------+--------------+
| <<<id>>>         | The reference ID of this POM.                          | No           |
*------------------+--------------------------------------------------------+--------------+
| <<<refid>>>      | The reference ID to use a previously defined POM.      | No           |
*------------------+--------------------------------------------------------+--------------+
| <<<inheritAllProperties>>>  | If set to true, all Ant properties will be passed to the Maven POM.  If set to false, only user (command-line) properties will be passed.  Defaults to true.   | No    | 2.1.0 |
*------------------+--------------------------------------------------------+--------------+
| <<<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}}.