Basic Example

The following example declares three dependencies and adds them to the dependency.classpath pathId.

<artifact:dependencies pathId="dependency.classpath">
  <dependency groupId="junit" artifactId="junit" version="3.8.2" scope="test"/>
  <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 pathId can be used in the Ant build file for example in the javac task.

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

Using FileSets and the Version Mapper

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">
  <!-- Your dependency definitions go here -->
  ...
</artifact:dependencies>
<copy todir="${webapp.output}/WEB-INF/lib">
  <fileset refid="dependency.fileset" />
  <!-- This mapper strips off all leading directory information -->
  <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 by the servlet container.

You can also specify a scope parameter on each dependency. This changes the behavior 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 on 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)
  • versionsId, which can be used to drop version numbers in filenames (since 2.0.7)

For example, to populate lib with your dependencies without the version in the filenames, lib/src with the corresponding sources and lib/javadoc with the corresponding javadocs:

<artifact:dependencies filesetId="dependency.fileset"
        sourcesFilesetId="sources.dependency.fileset"
        javadocFilesetId="javadoc.dependency.fileset"
        versionsId="dependency.versions">
  <!-- Your dependency definitions go here -->
  ...
</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>

Note: In the above example you only need to specify classpathref="maven-ant-tasks.classpath" if are using Maven Ant Tasks by declaring a typedef. It can be omitted if Maven Ant Tasks was installed in Ant's lib directory.

Using Properties to Access Dependencies

(since 2.0.8) For each dependency resolved using either inline declaration or a pom reference, the property groupId:artifactId:type[:classifier] is defined pointing to the corresponding file. For example, a resolved dependency on junit can be accessed in the following way:

<echo message="JUnit jar file downloaded to ${junit:junit:jar}"/>

Note about system scope

Dependencies that use the system scope specify a path on the local system that may be outside of the local maven repository. An Ant fileset only allows a single base directory, so these dependencies will not be included in the generated fileset for resolved dependencies. They will, however, be included in the path object.

Filtering Dependencies by Scope

There are two options available for filtering POM dependencies by scope: the useScope attribute, and the scopes attribute. One or the other of these attributes should be used but not both.

The useScope attribute follows the Maven conventions for scoping behaviour. This means the attribute can be set to one of three possible scopes: compile, runtime, or test. These scopes will behave as follows.

  • compile - Includes scopes compile, system and provided
  • runtime - Includes scopes compile and runtime
  • test - Includes scopes system, provided, compile, runtime and test

For example, using the scope runtime, any dependencies defined with compile, runtime, or nothing (defaults to compile) in the scope field will be included in the resulting fileset.

    <artifact:dependencies filesetId="deps.fileset" useScope="runtime">
      <pom file="mypom.xml"/>
    </artifact:dependencies>

(Since 2.0.10) The scopes attribute accepts a comma separated list of scopes to include in the filtering. Only dependencies with these specific scopes will be included in the resulting fileset. If no value is specified, all scopes are included. The following example includes only dependencies with a scope of either provided or test.

    <artifact:dependencies filesetId="deps.fileset" scopes="provided, test">
      <pom file="mypom.xml"/>
    </artifact:dependencies>

Filtering Dependencies by Type

Dependencies can be filtered by type by using the type attribute. This can be set to a comma separated list of the types to select. The following example will only include artifacts of the jar type.

    <artifact:dependencies filesetId="deps.fileset" type="jar">
      <pom file="mypom.xml"/>
    </artifact:dependencies>

By default, all artifact types will be included when building the list of dependencies.

Generating an Ant build with the dependency properties and references

(Since 2.1.0) For a project with a large dependency tree, the resolution process can take some time. In these cases, the dependencies task provides an option to generate an Ant build file (called build-dependencies.xml by default) that contains properties and references generated by the dependency resolution. This file can be used as a cache to quickly load the paths to the dependency artifacts. Or it can be used directly in other ant build files via the import task.

There are two parameters to the dependencies task related to this feature cacheDependencyRefs and dependencyRefsBuildFile. The first is a boolean parameter to say whether the build file should be generated. By default the file will be created as "./target/build-dependencies.xml". The second parameter allows the default file name to be changed.

For example, to turn on the dependency cache, the following configuration could be used.

    <artifact:dependencies cacheDependencyRefs="true">
      <pom file="mypom.xml"/>
    </artifact:dependencies>

The first time the build is run, the dependencies will be resolved from the repository, and the task will generate a file called "build-dependencies.xml". This file contains a list of the properties and fileset references generated during the build. The next time the build is run, the dependency references will simply be loaded from the generate file.