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">
  ...
  <path id="maven-ant-tasks.classpath" path="lib/maven-ant-tasks-2.0.9.jar" />
  <typedef resource="org/apache/maven/artifact/ant/antlib.xml" uri="urn:maven-artifact-ant"
           classpathref="maven-ant-tasks.classpath" />
  ...

Declaring Dependencies

The main purpose of the Maven Ant Tasks is to utilise Maven's 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 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 Dependency Mechanism documentation in the Maven 2.0 site.

Other options are:

• sourcesFilesetId , which will give you a fileset reference containing sources artifacts, (since 2.0.6)
• javadocFilesetId , which will give you a fileset reference containing javadoc artifacts, (since 2.0.9)
• org.apache.maven.artifact.ant.VersionMapper , which can be used to drop version numbers in filenames (since 2.0.7)

For example, to populate lib with your dependencies without version in filename and lib/src with corresponding sources:

<artifact:dependencies filesetId="dependency.fileset"
        sourcesFilesetId="sources.dependency.fileset" javadocFilesetId="javadoc.dependency.fileset"
        versionsId="dependency.versions">
  ...
</artifact:dependencies>
<copy todir="lib">
  <fileset refid="dependency.fileset" />
  <mapper classpathref="maven-ant-tasks.classpath" classname="org.apache.maven.artifact.ant.VersionMapper"
          from="${dependency.versions}" to="flatten" />
</copy>
<copy todir="lib/src">
  <fileset refid="sources.dependency.fileset" />
  <mapper classpathref="maven-ant-tasks.classpath" classname="org.apache.maven.artifact.ant.VersionMapper"
          from="${dependency.versions}" to="flatten" />
</copy>
<copy todir="lib/javadoc">
  <fileset refid="javadoc.dependency.fileset" />
  <mapper classpathref="maven-ant-tasks.classpath" classname="org.apache.maven.artifact.ant.VersionMapper"
          from="${dependency.versions}" to="flatten" />
</copy>

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/ is used. But if at least one remote repository is specified, repo1 is not automatically added: you have to declare it if you need it.

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-beta-2"/>
  
  <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>
...

Note that if you use antcall , the provider isn't available during the Ant call: you have to register it again if you need it.

Maven Ant Tasks contain file and http-lightweight providers. The other available providers are:

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

The task can include the dependency nested type, in addition to the other shared types explained later. You must include either: a single pom element, or a pomRefId attribute or one or more dependency element(s).

If you have set a value for versionsId , you can later use VersionMapper , for example during a copy:

<copy todir="...">
  <fileset refid="..." />
  <mapper classpathref="maven-ant-tasks.classpath" classname="org.apache.maven.artifact.ant.VersionMapper"
          from="${...versionId property...}" to="flatten" />
</copy>

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

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.

The task must also take a either a nested pom element, or a pomRefId attribute. The tasks can have an optional localRepository element.

deploy can have an optional remoteRepository element. If no remoteRepository element is given, the distributionManagement section of the POM is used.

install-provider

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

localRepository

Specifies the location of the local repository of artifacts.

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

remoteRepository

Specifies the location of the remote repository.

pom

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