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