mirror of https://github.com/apache/maven.git
move to APT, improve ant task document
git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@201573 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Brett Leslie Porter
parent
92fb6285eb
commit
d430b422e0
|
|
@ -0,0 +1,222 @@
|
|||
--------
|
||||
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#ant} 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="maven-artifact-ant">
|
||||
<classpath>
|
||||
<pathelement location="lib/maven-artifact-ant-2.0-alpha-3.jar" />
|
||||
</classpath>
|
||||
</typedef>
|
||||
...
|
||||
-----
|
||||
|
||||
Using the Antlib
|
||||
|
||||
* Declaring Dependencies
|
||||
|
||||
The main purpose of the antlib is to utilise Maven's {{{dependencies.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-api"
|
||||
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, and assuming
|
||||
you passed <<<filesetId="dependeny.fileset">>> to the <<<dependencies>>> task, you could use the following:
|
||||
|
||||
-----
|
||||
<copy todir="${webapp.output}/WEB-INF/lib">
|
||||
<fileset refid="depdendency.fileset" />
|
||||
</copy>
|
||||
-----
|
||||
|
||||
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 <a href="dependencies.html#Dependency_Scope">Dependency Mechanism</a>
|
||||
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 an remote location you have set up to serve as a repository in your organisation.
|
||||
|
||||
-----
|
||||
...
|
||||
<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="scp://localhost/www/repository">
|
||||
<authentication username="${repository.username}" privateKey="${user.home}/.ssh/id_dsa"/>
|
||||
</remoteRepository>
|
||||
<pom refid="maven.project"/>
|
||||
</artifact:deploy>
|
||||
...
|
||||
-----
|
||||
|
||||
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.
|
||||
|
||||
* Using a Maven {POM} File
|
||||
|
||||
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>
|
||||
...
|
||||
</dependencies>
|
||||
</project>
|
||||
-----
|
||||
|
||||
~~explain ID
|
||||
|
||||
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:
|
||||
|
||||
* {{{dependencies.html} Dependency Mechanism}}
|
||||
|
||||
* {{{maven-settings/settings.html} Settings Reference}}
|
||||
|
||||
~~settings.xml
|
||||
~~reference
|
||||
~~exclusions
|
||||
|
||||
|
||||
|
|
@ -1,139 +0,0 @@
|
|||
<document>
|
||||
<properties>
|
||||
<title>Ant Tasks for Maven 2.0</title>
|
||||
<author email="brett@apache.org">Brett Porter</author>
|
||||
</properties>
|
||||
<body>
|
||||
<section name="Ant Tasks for Maven 2.0">
|
||||
<p>
|
||||
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:
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
<i>Dependency management</i> - including transitive dependencies, scope recognition and SNAPSHOT handling
|
||||
</li>
|
||||
<li>
|
||||
<i>Artifact deployment</i> - file and SSH based deployment to a Maven repository
|
||||
</li>
|
||||
<li>
|
||||
<i>POM processing</i> - for reading a Maven 2.0
|
||||
<code>pom.xml</code> file
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
The Ant tasks can be downloaded from the
|
||||
<a href="download.html#ant">Maven 2.0 download page</a>.
|
||||
</p>
|
||||
<subsection name="Installing the Ant Tasks">
|
||||
<p>
|
||||
For convenience, the Ant task and all its dependencies are packaged together as a single JAR file.
|
||||
While you can declare this in a classpath to pass to your own
|
||||
<code>typedef</code> element, this guide
|
||||
assumes you have installed the JAR in the
|
||||
<code>lib</code> directory of your Ant installation.
|
||||
</p>
|
||||
</subsection>
|
||||
</section>
|
||||
<section name="Using the Ant tasks">
|
||||
<subsection name="Including the Artifact Namespace">
|
||||
<p>
|
||||
To use the artifact tasks, assuming that the library has been installed in your Ant <code>lib</code>
|
||||
directory, add the following namespace to your <code>build.xml</code> file:
|
||||
</p>
|
||||
<source><![CDATA[<project ... xmlns:artifact="antlib:org.apache.maven.artifact.ant">]]></source>
|
||||
<p>
|
||||
Note, if you are using Ant 1.5 or below, the tasks should still continue to work by declaring
|
||||
them as <code>taskdef</code> elements - however this is unsupported.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Declaring Dependencies">
|
||||
<p>
|
||||
The main purpose of the Ant tasks is to allow you to specify dependencies inside your Ant script, for
|
||||
example:
|
||||
</p>
|
||||
<source><![CDATA[<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"/>
|
||||
<localRepository location="${basedir}/target/local-repo" />
|
||||
</artifact:dependencies>]]></source>
|
||||
<p>
|
||||
This will download the two dependencies given above, and additionally any dependencies they have (as long
|
||||
as they have the appropriate scope). The JAR files of all of the dependencies will be added to the
|
||||
Ant reference <code>dependency.classpath</code>, so that it can be used later, like so:
|
||||
</p>
|
||||
<source><![CDATA[<java ... classpathref="dependency.classpath" />]]></source>
|
||||
<p>
|
||||
You can also specify a <code>scope</code> 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 <a href="dependencies.html#Dependency_Scope">Dependency Mechanism</a>
|
||||
documentation in the Maven 2.0 site.
|
||||
</p>
|
||||
<p>
|
||||
The local repository given above is optional, and defaults to <code>${user.home}/.m2/repository</code>.
|
||||
This is where the downloaded JAR files are stored and referenced from.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Declaring Repositories">
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<p>
|
||||
These can be specified inline, or if you choose to reuse them, they can be declared with an id/refid
|
||||
combination.
|
||||
</p>
|
||||
<source><![CDATA[<artifact:remoteRepository id="remote.repository" url="http://repo1.maven.org/maven2" />]]></source>
|
||||
<p>
|
||||
If no remote repositories are specified, the default
|
||||
<a href="http://repo1.maven.org/maven2">http://repo1.maven.org/maven2/</a>
|
||||
is used. This is a complete copy of Ibiblio.
|
||||
</p>
|
||||
<p>
|
||||
<b>Note: </b> to work with transitive dependencies, you <i>must</i> use a Maven 2.0 style repository, not a
|
||||
Maven 1.0 style repository. Tools are available to convert a Maven 1.0 repository to Maven 2.0 - please
|
||||
contact the mailing lists if you require this as it has not yet been formally released.
|
||||
</p>
|
||||
<p>
|
||||
If your repository requires authentication, you can provide this as a nested element. It accepts the
|
||||
attributes <code>username</code>, <code>password</code>, and for SSH based repositories <code>privateKey</code>
|
||||
and <code>passphrase</code>. For example:
|
||||
</p>
|
||||
<source><![CDATA[<authentication username="brett" privateKey="${user.home}/.ssh/id_dsa" />]]></source>
|
||||
</subsection>
|
||||
<subsection name="Installing and Deploying Your Own Artifacts">
|
||||
<p>
|
||||
If you want to share your built artifacts between projects, you can use two other tasks: <code>install</code> for placing
|
||||
them in your local repository for access as dependencies in other scripts, and <code>deploy</code> for deploying
|
||||
them to an remote location you have set up to serve as a repository in your organisation.
|
||||
</p>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<p>
|
||||
Please refer to the sample script below for usage of the deployment tasks.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Sample Ant Script">
|
||||
<p>
|
||||
The file <a href="http://svn.apache.org/repos/asf/maven/components/trunk/maven-artifact-ant/sample.build.xml">sample.build.xml</a>
|
||||
is a sample Ant script showing some of the functionality in action.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Getting Help">
|
||||
<p>
|
||||
If you have any questions specific to the Ant tasks, please contact the <a href="mail-lists.html">Maven Users Mailing List</a>.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Why Won't it Work in Maven 1.0?">
|
||||
<p>
|
||||
This has not been completely tested and Maven 1.0 is based on Ant 1.5. In addition, it will not operate on
|
||||
Maven 1.0 project files, which may result in some confusion. It may be possible, but is not yet supported.
|
||||
</p>
|
||||
</subsection>
|
||||
</section>
|
||||
</body>
|
||||
</document>
|
||||
|
||||
Loading…
Reference in New Issue