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