src/site/apt/ant-tasks.apt

  --------
  Antlib for Maven 2.0
  --------
  Brett Porter
  --------
  24 June 2005
  --------

Antlib for Maven 2.0

  Maven 2.0 now comes with a set of Ant tasks that can be used to utilise Maven's artifact handling features
  from within Ant. This includes:

    * <Dependency management> - including transitive dependencies, scope recognition and SNAPSHOT handling

    * <Artifact deployment> - file and SSH based deployment to a Maven repository

    * <POM processing> - for reading a Maven 2.0 <<<pom.xml>>> file

  The Ant tasks can be downloaded from {{{download.html} Maven 2.0 download page}}.

Installing the Ant Tasks

  For convenience, the Ant task and all its dependencies are packaged together as a single JAR file.

  There are two ways to use the tasks from your scripts.

* Intalling in Ant's <<<lib>>> directory

  This is the simplest installation method but requires changes on every machine using the build file.
  You can place the JAR in your Ant <<<lib>>> directory, include it in the <<<CLASSPATH>>> environment variable,
  or pass it in to Ant using the <<<-lib>>> command line parameter.

  Using this method, to make the tasks available in your build file, add the following namespace to the start of
  the file:

-----
<project ... xmlns:artifact="antlib:org.apache.maven.artifact.ant">
  ...
-----

* Declaring a <<<typedef>>>

  Using a <<<typedef>>> declaration allows you to store the library anywhere you like (such as source control)
  and put it's location in the build file. This can be used to bootstrap the tasks by using <<<get>>> to obtain
  the library, and then reference it from the build script.

  The following example shows how to set it up, assuming the library is in the <<<lib>>> subdirectory of your current
  project.

-----
<project ... xmlns:artifact="urn:maven-artifact-ant">
  ...
  <typedef resource="org/apache/maven/artifact/ant/antlib.xml" uri="urn:maven-artifact-ant">
    <classpath>
      <pathelement location="lib/maven-artifact-ant-2.0.2-dep.jar" />
    </classpath>
  </typedef>
  ...
-----

Using the Antlib

* Declaring Dependencies

  The main purpose of the antlib is to utilise Maven's {{{guides/introduction/introduction-to-dependency-mechanism.html} dependency management features}}.

  This is achieved with the <<<dependencies>>> task. The simplest usage involves specifying your dependencies inline,
  such as in the following example:

-----
<artifact:dependencies pathId="dependency.classpath">
  <dependency groupId="org.apache.maven.wagon" artifactId="wagon-provider-test"
              version="1.0-alpha-2"/>
  <dependency groupId="org.codehaus.modello" artifactId="modello-core" 
              version="1.0-alpha-2-SNAPSHOT"/>
  <dependency groupId="javax.servlet" artifactId="servlet-api" 
              version="2.4" scope="provided" />
</artifact:dependencies>
-----

  The above example will download those 3 dependencies, and their dependencies, and so on. They will be stored in
  the default local repository location, <<<$\{user.home\}/.m2/repository>>>.

  You can also use a Maven 2.0 POM to declare your dependencies, which is {{{#POM} explained below}}. This is a
  recommended practice so that you can reuse the file to deploy your own artifacts. 

  You may have noticed the <<<pathId>>> reference. This is optional, but if given will create a classpath reference
  that includes the local files downloaded as dependencies. This is usually used to pass to <<<javac>>> or other tasks:

-----
<javac ...>
  <classpath refid="dependency.classpath" />
  ...
</javac>
-----

  Another option you can use is <<<filesetId>>>, which will give you a fileset reference that can be used to copy
  files into a particular location. For example, to populate <<<WEB-INF/lib>>> with your dependencies
  you could use the following:

-----
<artifact:dependencies filesetId="dependency.fileset" useScope="runtime">
  ...
</artifact:dependencies>
<copy todir="${webapp.output}/WEB-INF/lib">
  <fileset refid="dependency.fileset" />
  <mapper type="flatten" />
</copy>
-----

  Note the <<<useScope>>> attribute in this call. This ensures that your web application only includes your compile
  and runtime dependencies, excluding those that are only for testing or are expected to already be provided in
  the servlet container.

  You can also specify a <<<scope>>> parameter on each dependency. This changes the behaviour of
  transitive dependencies and is useful for building different types of classpaths. To see how it affects
  the behaviour of the dependencies, see the {{{guides/introduction/introduction-to-dependency-mechanism.html} Dependency Mechanism}}
  documentation in the Maven 2.0 site.

* Declaring Repositories

  All of the tasks can optionally take one or more remote repositories to download from and upload to, and a
  local repository to store downloaded and installed archives to.

  These can be specified inline, or if you choose to reuse them, they can be declared with an <<<id>>>/<<<refid>>>
  combination.

  For example, you can specify the remote repository you want to use:

-----
<artifact:remoteRepository id="remote.repository" url="http://repository.mycompany.com/" />
...
<artifact:dependencies>
  ...
  <remoteRepository refid="remote.repository" />
</artifact:dependencies>
-----

  If no remote repositories are specified, the default {{{http://repo1.maven.org/maven2} http://repo1.maven.org/maven2}}
  is used.

  <<Note:>> to work with transitive dependencies, you <must> use a Maven 2.0 repository.

  If your repository requires authentication, you can provide this as a nested element. It accepts the
  attributes <<<username>>>, <<<password>>>, and for SSH based repositories <<<privateKey>>>
  and <<<passphrase>>>. For example:

-----
<authentication username="brett" privateKey="${user.home}/.ssh/id_dsa" />
-----

* Installing and Deploying Your Own Artifacts

  If you want to share your built artifacts between projects, you can use two other tasks: <<<install>>> for
  placing them in your local repository for access as dependencies in other scripts, and <<<deploy>>> for
  deploying them to a remote location you have set up to serve as a repository in your organisation.

  Note that the installation and deployment require that you have a Maven 2.0 POM file to deploy along with it.
  These are required for the transitive dependency mechanism to work effectively, and can be quite simple to
  create.

-----
...
  <artifact:pom id="maven.project" file="pom.xml" />

  <artifact:install file="target/maven-artifact-ant-2.0-alpha-3.jar">
    <pom refid="maven.project"/>
  </artifact:install>

  <artifact:deploy file="target/maven-artifact-ant-2.0-alpha-3.jar">
    <remoteRepository url="file://localhost/www/repository"/>
    <pom refid="maven.project"/>
  </artifact:deploy>
...
-----

  For deploying using a protocol other than local file system, you need to register a provider to make the other
  protocols available. For example:

-----
...
  <artifact:install-provider artifactId="wagon-ssh" version="1.0-alpha-5"/>
  
  <artifact:deploy file="target/maven-artifact-ant-2.0-alpha-3.jar">
    <remoteRepository url="scp://localhost/www/repository">
      <authentication username="${repository.username}" privateKey="${user.home}/.ssh/id_dsa"/>
    </remoteRepository>
    <pom refid="maven.project"/>
  </artifact:deploy>
...
-----

  The currently available providers are:

*--------------+--------------------------+-------------------+
| Protocol     | Artifact ID              | Version           |
*--------------+--------------------------+-------------------+
| <<<file>>>   | <<<wagon-file>>>         | <<<1.0-alpha-5>>> |
*--------------+--------------------------+-------------------+
| <<<scp>>>    | <<<wagon-ssh>>>          | <<<1.0-alpha-5>>> |
*--------------+--------------------------+-------------------+
| <<<scpexe>>> | <<<wagon-ssh-external>>> | <<<1.0-alpha-5>>> |
*--------------+--------------------------+-------------------+
| <<<ftp>>>    | <<<wagon-ftp>>>          | <<<1.0-alpha-5>>> |
*--------------+--------------------------+-------------------+

* Using a Maven {POM} File

  In Maven, the Project Object Model (POM) represents a unit of work - one exists for each artifact that is built.

  Maven 2.0 POM files are required for deploying your own artifacts to a repository for use in the dependencies
  elements of other projects. 

  They can also be reused for declaring your own dependencies, instead of specifying the inline version given earlier.

  Here is the earlier example, expressed as a POM:

-----
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.project</groupId>
  <artifactId>project-model</artifactId>
  <version>1.0-SNAPSHOT</version>

  <dependencies>
    <dependency>
      <groupId>org.apache.maven.wagon</groupId>
      <artifactId>wagon-provider-api</artifactId>
      <version>1.0-alpha-2</version>
    </dependency>

    <dependency>
      <groupId>org.codehaus.modello</groupId>
      <artifactId>modello-core</artifactId>
      <version>1.0-alpha-2-SNAPSHOT</version>
    </dependency>

    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>servlet-api</artifactId>
      <version>2.4</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
</project>
-----

  These elements represent:

    * <modelVersion> - this is the version of the POM layout in use, currently <<<4.0.0>>>

    * <groupId> - the group ID represents your organisation and project name, much like a Java package name.
      This must be universally unique. This becomes the base directory in the repository as well.

    * <artifactId> - the artifact ID represents the current build unit. It usually equals the filename of the
      resulting file, and must be unique within the group.

    * <version> - the version of the artifact you are building.

    * <dependencies> - the artifacts the project is dependant on.

  This is all that is required for most projects. However, it is also possible to use other fields available in
  Maven to describe your project, and reference them from your build script. 

  To access a POM as Ant properties, you must define it as a reference. For example, to access the version from a POM,
  you could use the following:

-----
  <artifact:pom id="maven.project" file="pom.xml" />

  <echo>The version is ${maven.project.version}</echo>
-----

  You can also access nested parts of the POM. For example, you can read the default value of the <<<directory>>>
  element within the <<<build>>> element using a <<<.>>> separator.

-----
  <artifact:pom id="project" file="pom.xml" />

  <echo>The build directory is ${project.build.directory}</echo>
-----

  For more information on the elements available in the POM, see the {{{maven-model/maven.html} descriptor reference}}.

The Settings File

  The POM can be used to represent most of the information that the tasks have access to, including remote
  repositories. For information that is user or environment specific, such as the <<<authentication>>> tag, are
  specified in the <<<settings.xml>>> file in Maven, and can be accessed from the Ant tasks also.

  The file is first looked for in <<<$\{user.home\}/.ant/settings.xml>>>, then in <<<$\{user.home\}/.m2/settings.xml>>>
  so that the settings can be shared with Maven 2.0 itself.

  For example, to specify your proxy settings, you would specify the following <<<settings.xml>>> file:

-----
<settings>
  <proxies>
    <proxy>
      <protocol>http</protocol>
      <host>proxy.host.net</host>
      <port>8080</port>
      <nonProxyHosts>localhost</nonProxyHosts>
    </proxy>
  </proxies>
</settings>
-----

  For more information in configuring <<<settings.xml>>>, see:

    * {{{guides/mini/guide-configuring-maven.html} Configuring Maven}}.

    * {{{maven-settings/settings.html} Settings Descriptor Reference}}.

    * There is a
      {{{http://svn.apache.org/repos/asf/maven/components/trunk/maven-cli/src/conf/settings.xml} sample settings file}}
      in the Maven installation.

Sample Ant Script

  The file 
  {{{http://svn.apache.org/repos/asf/maven/components/trunk/maven-artifact-ant/sample.build.xml} sample.build.xml}}
  is a sample Ant script showing some of the functionality in action.

Getting Help

  If you have any questions specific to the Ant tasks, please contact the
  {{{mail-lists.html} Maven Users Mailing List}}.

  For more on the Maven functionality behind them, try the following links:

    * {{{guides/introduction/introduction-to-dependency-mechanism.html} Dependency Mechanism}}

    * {{{maven-settings/settings.html} Settings Reference}}

    * {{{maven-model/maven.html} POM Reference}}

Task Reference

* <<<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:

*-----------------+--------------------------------------------------------+
| <<<verbose>>>   | If <<<true>>> this displays the results of each dependency resolution and their relationships. Default is <false>.
*-----------------+--------------------------------------------------------+
| <<<filesetId>>> | The reference ID to store a fileset under for the resolved dependencies.
*-----------------+--------------------------------------------------------+
| <<<pathId>>>    | The reference ID to store a path under for the resolved dependencies.
*-----------------+--------------------------------------------------------+

  The task can include the <<<dependency>>> nested type, in addition to the other shared types explained later.
  You must include at least one <<<dependency>>> element, or a single <<<pom>>> element, but not both.

** <<<dependency>>>

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

  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.

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

* <<<install>>>

  This task will install the given file into the local repository. It is stored using the information in the supplied
  POM.

*------------------+--------------------------------------------------------+
| <<<file>>>       | The file to install in the local repository.
*------------------+--------------------------------------------------------+

  The task must also take a nested <<<pom>>>, and can have an optional <<<localRepository>>> element.

* <<<deploy>>>

  This task will deploy the given file into the remote repository. It is stored using the information in the supplied
  POM.

*------------------+--------------------------------------------------------+
| <<<file>>>       | The file to deploy in the remote repository.
*------------------+--------------------------------------------------------+

  The task must also take a nested <<<pom>>>, and can have an optional <<<remoteRepository>>> element. If no
  <<<remoteRepository>>> element is given, the <<<distributionManagement>>> section of the POM is used.

Type Reference

* <<<localRepository>>>

  Specifies the location of the local repository of artifacts.

*------------------+--------------------------------------------------------+
| <<<location>>>   | The directory of the local repository. <Required>
*------------------+--------------------------------------------------------+
| <<<layout>>>     | The layout of the local repository. The valid options are <<<legacy>>> (Maven 1), or <<<default>>> (Maven 2).
*------------------+--------------------------------------------------------+

* <<<remoteRepository>>>

  Specifies the location of the remote repository.

*----------------------+--------------------------------------------------------+
| <<<url>>>            | The URL of the repository. <Required>
*----------------------+--------------------------------------------------------+
| <<<layout>>>         | The layout of the remote repository. The valid options are <<<legacy>>> (Maven 1), or <<<default>>> (Maven 2).
*----------------------+--------------------------------------------------------+
| <<<snapshots>>>      | Policies regarding downloading snapshot artifacts.
*----------------------+--------------------------------------------------------+
| <<<releases>>>       | Policies regarding downloading released artifacts.
*----------------------+--------------------------------------------------------+

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

  Policies about downloading each type of artifact.

*----------------------+--------------------------------------------------------+
| <<<enabled>>>        | Whether to download this type of artifact from the repository. Default is <<<true>>>.
*----------------------+--------------------------------------------------------+
| <<<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>>>.
*----------------------+--------------------------------------------------------+
| <<<checksumPolicy>>> | How to treat missing or incorrect checksums for the dependencies that are downloaded. Valid values are <<<warn>>> (<default>) and <<<fail>>>.
*----------------------+--------------------------------------------------------+

  The remote repository can also nest the following elements: <<<authentication>>> and <<<proxy>>>.

** <<<proxy>>>

  The proxy element is typically used for HTTP repositories. The layout is the same as in the
  {{{maven-settings/settings.html#class_proxy} settings reference}}.

** <<<authentication>>>

  The authentication element is used for passing a username, password and other credentials to the repository either
  on upload or download. The layout is the same as in the {{{maven-settings/settings.html#class_server} 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.

*------------------+--------------------------------------------------------+
| <<<file>>>       | The file of the POM to load. <Required>
*------------------+--------------------------------------------------------+