You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by de...@apache.org on 2008/07/17 21:44:50 UTC
svn commit: r677700 - in
/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site: apt/index.apt
apt/installation.apt apt/usage.apt site.xml
Author: dennisl
Date: Thu Jul 17 12:44:49 2008
New Revision: 677700
URL: http://svn.apache.org/viewvc?rev=677700&view=rev
Log:
[MANTTASKS-114] Improve documentation
o Extract installation and usage to their own pages.
Added:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/installation.apt (with props)
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt (with props)
Modified:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/index.apt (contents, props changed)
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/site.xml (contents, props changed)
Modified: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/index.apt?rev=677700&r1=677699&r2=677700&view=diff
==============================================================================
--- maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/index.apt (original)
+++ maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/index.apt Thu Jul 17 12:44:49 2008
@@ -42,399 +42,7 @@
~~ TODO: What is the minimum version of Ant required to use Maven Ant tasks?
-Installing the Maven Ant Tasks
-
- For convenience, the Maven Ant tasks and all its dependencies are packaged together as a single JAR file.
-
- There are two ways to use the tasks from your scripts.
-
-* Installing 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">
- ...
-</project>
------
-
-* Declaring a <<<typedef>>>
-
- Using a <<<typedef>>> declaration allows you to store the Ant Tasks' 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" />
- ...
-</project>
------
-
-Using the Maven Ant Tasks
-
-* Declaring Dependencies
-
- The main purpose of the Maven Ant Tasks is to utilise Maven's {{{http://maven.apache.org/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="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 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 {{{./reference.html#pom} explained in the reference}}. This is the
- 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">
- <!-- 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 {{{http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html} 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)>
-
- * <<<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 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>>>.
-
-* 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>
- <!-- Your dependency definitions go here -->
- ...
- <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. 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" />
------
-
-* 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.
-
- A Maven 2.0 POM file is required for deploying your own artifact to a repository for use in the dependencies
- elements of other projects.
-
- It 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>junit</groupId>
- <artifactId>junit</artifactId>
- <version>3.8.2</version>
- <scope>test</scope>
- </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 that this 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 part of the POM as an Ant property, you must define it as a reference. For example, to access the version from a POM,
- you can 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 {{{http://maven.apache.org/maven-model/maven.html} descriptor reference}}.
-
-* Installing and Deploying Your Own Artifacts to a Repository
-
- If you want to share your built artifacts between projects, you can use two other tasks: <<<install>>> for
- installing 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.
-
- ~~ TODO: Write an introductory text explaining the example below
-
------
-...
- <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.
-
- ~~ TODO: Explain more thoroughly when you need to register a provider
-
- Maven Ant Tasks contain <<<wagon-file>>> and <<<wagon-http-lightweight>>> providers. The other available providers are:
-
-*--------------+--------------------------+-------------------+
-| Protocol | Artifact ID | Version |
-*--------------+--------------------------+-------------------+
-| <<<http>>> | <<<wagon-http>>> | <<<1.0-beta-2>>> |
-*--------------+--------------------------+-------------------+
-| <<<scp>>> | <<<wagon-ssh>>> | <<<1.0-beta-2>>> |
-*--------------+--------------------------+-------------------+
-| <<<scpexe>>> | <<<wagon-ssh-external>>> | <<<1.0-beta-2>>> |
-*--------------+--------------------------+-------------------+
-| <<<ftp>>> | <<<wagon-ftp>>> | <<<1.0-beta-2>>> |
-*--------------+--------------------------+-------------------+
-| <<<webdav>>> | <<<wagon-webdav>>> | <<<1.0-beta-2>>> |
-*--------------+--------------------------+-------------------+
-
-The Settings File
-
- The POM can be used to represent most of the information that the tasks have access to, including remote
- repositories. Information that are user or environment specific, such as the <<<authentication>>> tag, are
- specified in the <<<settings.xml>>> file in Maven, and can also be accessed from the Ant tasks.
-
- 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. Since 2.0.7, it is then looked for in
- <<<$\{ANT_HOME\}/etc/settings.xml>>>, then in <<<$\{M2_HOME\}/conf/settings.xml>>> so that the settings
- can be set for all users.
-
- Since 2.0.6, you can provide access to a settings file anywhere using <<<settingsFile>>> attribute:
-
------
-<artifact:dependencies settingsFile="/opt/maven/conf/settings.xml">
- ...
-</artifact:dependencies>
------
-
- 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>
------
-
- Or to specify a <<<central>>> mirror, you would specify the following <<<settings.xml>>> file:
-
------
-<settings>
- <mirrors>
- <mirror>
- <id>central.mirror</id>
- <url>http://mirror.host.net/maven2</url>
- <mirrorOf>central</mirrorOf>
- </mirror>
- </mirrors>
-</settings>
------
-
- For more information on configuring <<<settings.xml>>>, see:
-
- * {{{http://maven.apache.org/guides/mini/guide-configuring-maven.html} Configuring Maven}}.
-
- * {{{http://maven.apache.org/maven-settings/settings.html} Settings Descriptor Reference}}.
-
- * {{{http://maven.apache.org/guides/mini/guide-mirror-settings.html} Using Mirrors for Repositories}}.
-
- ~~ TODO: The link below is broken
-
- * There is a
- {{{http://svn.apache.org/repos/asf/maven/components/trunk/maven-embedder/src/conf/settings.xml} sample settings file}}
- in the Maven installation.
-
-Sample Ant Script
-
- The file
- {{{http://svn.apache.org/repos/asf/maven/ant-tasks/trunk/sample.build.xml} sample.build.xml}}
- is a sample Ant script showing some of the functionality in action.
-
-Getting Help
+* Getting Help
If you have any questions specific to the Ant tasks, please contact the
{{{http://maven.apache.org/mail-lists.html} Maven Users Mailing List}}.
Propchange: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:keywords = Date Revision Author Id
Added: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/installation.apt
URL: http://svn.apache.org/viewvc/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/installation.apt?rev=677700&view=auto
==============================================================================
--- maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/installation.apt (added)
+++ maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/installation.apt Thu Jul 17 12:44:49 2008
@@ -0,0 +1,70 @@
+ --------
+ Installation
+ --------
+ Brett Porter
+ Herve Boutemy
+ --------
+ 2008-07-17
+ --------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Installing Maven Ant Tasks
+
+ For convenience, Maven Ant Tasks and all its dependencies are packaged together as a single JAR file.
+
+ There are two ways to use the tasks from your scripts.
+
+* Installing 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">
+ ...
+</project>
+-----
+
+* Declaring a <<<typedef>>>
+
+ Using a <<<typedef>>> declaration allows you to store the Ant Tasks' 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" />
+ ...
+</project>
+-----
+
Propchange: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/installation.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/installation.apt
------------------------------------------------------------------------------
svn:keywords = Date Revision Author Id
Added: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt
URL: http://svn.apache.org/viewvc/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt?rev=677700&view=auto
==============================================================================
--- maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt (added)
+++ maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt Thu Jul 17 12:44:49 2008
@@ -0,0 +1,379 @@
+ ------
+ Usage
+ ------
+ Brett Porter
+ Herve Boutemy
+ ------
+ 2008-07-17
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+ ~~ NOTE: For help with the syntax of this file, see:
+ ~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Using Maven Ant Tasks
+
+* Declaring Dependencies
+
+ The main purpose of the Maven Ant Tasks is to utilise Maven's {{{http://maven.apache.org/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="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 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 {{{./reference.html#pom} explained in the reference}}. This is the
+ 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">
+ <!-- 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 {{{http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html} 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)>
+
+ * <<<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 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>>>.
+
+* 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>
+ <!-- Your dependency definitions go here -->
+ ...
+ <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. 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" />
+-----
+
+* 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.
+
+ A Maven 2.0 POM file is required for deploying your own artifact to a repository for use in the dependencies
+ elements of other projects.
+
+ It 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>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.2</version>
+ <scope>test</scope>
+ </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 that this 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 part of the POM as an Ant property, you must define it as a reference. For example, to access the version from a POM,
+ you can 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 {{{http://maven.apache.org/maven-model/maven.html} descriptor reference}}.
+
+* Installing and Deploying Your Own Artifacts to a Repository
+
+ If you want to share your built artifacts between projects, you can use two other tasks: <<<install>>> for
+ installing 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.
+
+ ~~ TODO: Write an introductory text explaining the example below
+
+-----
+...
+ <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.
+
+ ~~ TODO: Explain more thoroughly when you need to register a provider
+
+ Maven Ant Tasks contain <<<wagon-file>>> and <<<wagon-http-lightweight>>> providers. The other available providers are:
+
+*--------------+--------------------------+-------------------+
+| Protocol | Artifact ID | Version |
+*--------------+--------------------------+-------------------+
+| <<<http>>> | <<<wagon-http>>> | <<<1.0-beta-2>>> |
+*--------------+--------------------------+-------------------+
+| <<<scp>>> | <<<wagon-ssh>>> | <<<1.0-beta-2>>> |
+*--------------+--------------------------+-------------------+
+| <<<scpexe>>> | <<<wagon-ssh-external>>> | <<<1.0-beta-2>>> |
+*--------------+--------------------------+-------------------+
+| <<<ftp>>> | <<<wagon-ftp>>> | <<<1.0-beta-2>>> |
+*--------------+--------------------------+-------------------+
+| <<<webdav>>> | <<<wagon-webdav>>> | <<<1.0-beta-2>>> |
+*--------------+--------------------------+-------------------+
+
+* The Settings File
+
+ The POM can be used to represent most of the information that the tasks have access to, including remote
+ repositories. Information that are user or environment specific, such as the <<<authentication>>> tag, are
+ specified in the <<<settings.xml>>> file in Maven, and can also be accessed from the Ant tasks.
+
+ 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. Since 2.0.7, it is then looked for in
+ <<<$\{ANT_HOME\}/etc/settings.xml>>>, then in <<<$\{M2_HOME\}/conf/settings.xml>>> so that the settings
+ can be set for all users.
+
+ Since 2.0.6, you can provide access to a settings file anywhere using <<<settingsFile>>> attribute:
+
+-----
+<artifact:dependencies settingsFile="/opt/maven/conf/settings.xml">
+ ...
+</artifact:dependencies>
+-----
+
+ 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>
+-----
+
+ Or to specify a <<<central>>> mirror, you would specify the following <<<settings.xml>>> file:
+
+-----
+<settings>
+ <mirrors>
+ <mirror>
+ <id>central.mirror</id>
+ <url>http://mirror.host.net/maven2</url>
+ <mirrorOf>central</mirrorOf>
+ </mirror>
+ </mirrors>
+</settings>
+-----
+
+ For more information on configuring <<<settings.xml>>>, see:
+
+ * {{{http://maven.apache.org/guides/mini/guide-configuring-maven.html} Configuring Maven}}.
+
+ * {{{http://maven.apache.org/maven-settings/settings.html} Settings Descriptor Reference}}.
+
+ * {{{http://maven.apache.org/guides/mini/guide-mirror-settings.html} Using Mirrors for Repositories}}.
+
+ ~~ TODO: The link below is broken
+
+ * There is a
+ {{{http://svn.apache.org/repos/asf/maven/components/trunk/maven-embedder/src/conf/settings.xml} sample settings file}}
+ in the Maven installation.
+
+* Sample Ant Script
+
+ The file
+ {{{http://svn.apache.org/repos/asf/maven/ant-tasks/trunk/sample.build.xml} sample.build.xml}}
+ is a sample Ant script showing some of the functionality in action.
Propchange: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt
------------------------------------------------------------------------------
svn:keywords = Date Revision Author Id
Modified: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/site.xml
URL: http://svn.apache.org/viewvc/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/site.xml?rev=677700&r1=677699&r2=677700&view=diff
==============================================================================
--- maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/site.xml (original)
+++ maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/site.xml Thu Jul 17 12:44:49 2008
@@ -30,6 +30,8 @@
<menu name="Overview">
<item name="Introduction" href="index.html"/>
+ <item name="Installation" href="installation.html"/>
+ <item name="Usage" href="usage.html"/>
<item name="Task Reference" href="reference.html"/>
<item name="Release Notes" href="release-notes.html"/>
</menu>
Propchange: maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/site.xml
------------------------------------------------------------------------------
svn:keywords = Date Revision Author Id