You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by br...@apache.org on 2005/06/24 08:54:11 UTC
svn commit: r201573 - in /maven/components/trunk/maven-site/src/site:
apt/ant-tasks.apt xdoc/ant-tasks.xml
Author: brett
Date: Thu Jun 23 23:54:09 2005
New Revision: 201573
URL: http://svn.apache.org/viewcvs?rev=201573&view=rev
Log:
move to APT, improve ant task document
Added:
maven/components/trunk/maven-site/src/site/apt/ant-tasks.apt
- copied, changed from r201565, maven/components/trunk/maven-site/src/site/xdoc/ant-tasks.xml
Removed:
maven/components/trunk/maven-site/src/site/xdoc/ant-tasks.xml
Copied: maven/components/trunk/maven-site/src/site/apt/ant-tasks.apt (from r201565, maven/components/trunk/maven-site/src/site/xdoc/ant-tasks.xml)
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/ant-tasks.apt?p2=maven/components/trunk/maven-site/src/site/apt/ant-tasks.apt&p1=maven/components/trunk/maven-site/src/site/xdoc/ant-tasks.xml&r1=201565&r2=201573&rev=201573&view=diff
==============================================================================
--- maven/components/trunk/maven-site/src/site/xdoc/ant-tasks.xml (original)
+++ maven/components/trunk/maven-site/src/site/apt/ant-tasks.apt Thu Jun 23 23:54:09 2005
@@ -1,139 +1,222 @@
-<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>
+ --------
+ 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
+
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org