Author: pgier
Date: Wed May 6 18:30:13 2009
New Revision: 772397
URL: http://svn.apache.org/viewvc?rev=772397&view=rev
Log:
[MANTTASKS-146] Split content of usage page into a few examples pages. Other
general site updates.
Added:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/dependencies.apt
(with props)
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/install-deploy.apt
(with props)
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/pom.apt
(with props)
Modified:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/index.apt
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/reference.apt
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/site.xml
Added:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/dependencies.apt
URL:
http://svn.apache.org/viewvc/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/dependencies.apt?rev=772397&view=auto
==============================================================================
---
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/dependencies.apt
(added)
+++
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/dependencies.apt
Wed May 6 18:30:13 2009
@@ -0,0 +1,133 @@
+ ------
+ Dependencies
+ ------
+ Brett Porter
+ Herve Boutemy
+ Paul Gier
+ ------
+ 2009-05-06
+ ------
+
+ ~~ 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
+
+Basic Example
+
+ The following example declares three dependencies and adds them to the
pathId <<<dependency.classpath>>>.
+
+-----
+<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
{{{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)>
+
+ * {<<<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 {{{../installation.html#typedef} declaring a <<<typedef>>>}}.
+ It can be omitted if Maven Ant Tasks was
+ {{{../installation.html#lib} 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}"/>
+-----
+
Propchange:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/dependencies.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/dependencies.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/install-deploy.apt
URL:
http://svn.apache.org/viewvc/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/install-deploy.apt?rev=772397&view=auto
==============================================================================
---
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/install-deploy.apt
(added)
+++
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/install-deploy.apt
Wed May 6 18:30:13 2009
@@ -0,0 +1,93 @@
+ ------
+ Install and Deploy
+ ------
+ Brett Porter
+ Herve Boutemy
+ Paul Gier
+ ------
+ 2009-05-06
+ ------
+
+ ~~ 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
+
+Install and Deploy
+
+ 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.
+
+ The following example shows basic use of the <<<install>>> and <<<deploy>>>
tasks.
+
+-----
+...
+ <artifact:pom id="mypom" file="pom.xml" />
+
+ <artifact:install file="target/my-project-1.0.jar">
+ <pom refid="mypom"/>
+ </artifact:install>
+
+ <artifact:deploy file="target/my-project-1.0.jar">
+ <remoteRepository url="file://localhost/www/repository"/>
+ <pom refid="mypom"/>
+ </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/my-project-1.0.jar">
+ <remoteRepository url="scp://localhost/www/repository">
+ <authentication username="${repository.username}"
privateKey="${user.home}/.ssh/id_dsa"/>
+ </remoteRepository>
+ <pom refid="mypom"/>
+ </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>>> |
+*--------------+--------------------------+-------------------+
Propchange:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/install-deploy.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/install-deploy.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/pom.apt
URL:
http://svn.apache.org/viewvc/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/pom.apt?rev=772397&view=auto
==============================================================================
---
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/pom.apt
(added)
+++
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/pom.apt
Wed May 6 18:30:13 2009
@@ -0,0 +1,135 @@
+ ------
+ Pom
+ ------
+ Brett Porter
+ Herve Boutemy
+ Paul Gier
+ ------
+ 2009-05-06
+ ------
+
+ ~~ 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
+
+The Pom Task
+
+ In order to use the pom task, you will first need to define a pom (typically
pom.xml).
+ An example pom is provided here:
+
+-----
+<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="mypom" file="pom.xml" />
+
+ <echo>The version is ${mypom.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="mypom" file="pom.xml" />
+
+ <echo>The build directory is ${mypom.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}}.
+
+Accessing dependencies in the POM
+
+ The <<<pom>>> task can be used in combination with the <<<dependencies>>>
task to declare a list of dependencies.
+
+-----
+ <artifact:pom id="mypom" file="pom.xml" />
+
+ <artifact:dependencies filesetId="mydeps" pomRefId="mypom" />
+-----
+
+ In this example, the <<<dependencies>>> task will resolve the list of
dependencies in the pom
+ and add them to the fileset.
+
+Using profiles in the POM
+
+ POM profiles can be activated or deactivated using the nested profile
element. For example
+ to activate a profile called <<my-profile>>.
+
+-----
+ <artifact:pom id="maven.project" file="pom.xml">
+ <profile id="my-profile"/>
+ </artifact:pom>
+-----
+
+ This can also be used to deactivate a POM profile that is active by default.
+
+-----
+ <artifact:pom id="maven.project" file="pom.xml">
+ <profile id="my-default-profile" active="false"/>
+ </artifact:pom>
+-----
+
Propchange:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/pom.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/examples/pom.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
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=772397&r1=772396&r2=772397&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 Wed
May 6 18:30:13 2009
@@ -27,10 +27,10 @@
~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html
-Ant Tasks for Maven
+Maven Ant Tasks
- Maven comes with a set of Ant tasks that can be used to utilize Maven's
artifact handling features
- from within Ant. This includes:
+ The Mavent Ant Tasks allow many of Maven's artifact handling features to be
used
+ from within Ant. These include:
* <Dependency management> - including transitive dependencies, scope
recognition and SNAPSHOT handling
@@ -38,10 +38,25 @@
* <POM processing> - for reading a Maven 2.0.x <<<pom.xml>>> file
- The Ant tasks can be downloaded from
{{{http://maven.apache.org/download.html} Maven 2.0 download page}}.
+ The Ant tasks can be downloaded from the
{{{http://maven.apache.org/download.html} Maven 2.0 download page}}.
Ant 1.6.x or 1.7.x is required to use Maven Ant tasks.
+* Usage
+
+ Instructions for installing and using the maven ant tasks can be found on
the {{{installation.html}installation page}}
+ and the {{{usage.html}usage page}} respectively.
+
+* Examples
+
+ Several common usage examples are provided for the following tasks:
+
+ * {{{examples/dependencies.html}Dependencies task}}
+
+ * {{{examples/install-deploy.html}Install and Deploy tasks}}
+
+ * {{{examples/pom.html}Pom task}}
+
* Getting Help
If you have any questions specific to the Ant tasks, please contact the
Modified:
maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/reference.apt
URL:
http://svn.apache.org/viewvc/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/reference.apt?rev=772397&r1=772396&r2=772397&view=diff
==============================================================================
--- maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/reference.apt
(original)
+++ maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/reference.apt
Wed May 6 18:30:13 2009
@@ -247,7 +247,7 @@
| <<<active>>> | Set to <<<true>>> or <<<false>>> to determine whether the
profile should be active. Default is <<<true>>>. | No |
*------------------+--------------------------------------------------------+--------------+
-* <<<{VersionMapper}>>> <(since 2.0.7)>
+* <<<{versionMapper}>>> <(since 2.0.7)>
This is a {{{http://ant.apache.org/manual/CoreTypes/mapper.html}filename
mapper}}
that removes version info from the filename when copying dependencies. It can
@@ -264,4 +264,4 @@
| <<<to>>> | If this is set to <<<flatten>>> the directory info is
also removed from the filename. | No |
*------------------+--------------------------------------------------------+--------------+
- You can see a full working example in the {{{usage.html#versionsId} Usage}}
page.
\ No newline at end of file
+ You can see a full working example in the {{{examples/dependencies.html}
examples}}.
Modified: 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=772397&r1=772396&r2=772397&view=diff
==============================================================================
--- maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt
(original)
+++ maven/ant-tasks/branches/maven-ant-tasks-2.0.x/src/site/apt/usage.apt Wed
May 6 18:30:13 2009
@@ -47,98 +47,35 @@
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.
+ You can also use a Maven 2.0 POM to declare your dependencies, which is
{{{examples/pom.html} described in the examples}}.
+ This is the recommended practice so that you can reuse the file to deploy
your own artifacts.
- Other options are:
+ For more examples of using the dependencies task, see the
{{{examples/dependencies.html} examples page}}.
- * <<<sourcesFilesetId>>>, which will give you a fileset reference
containing sources artifacts, <(since 2.0.6)>
+* Installing and Deploying Your Own Artifacts to a Repository
- * <<<javadocFilesetId>>>, which will give you a fileset reference
containing javadoc artifacts, <(since 2.0.9)>
+ Maven allows artifacts to be shared between projects by using local and
remote repository.
+ The <<<install>>> task allows an artifact to be copied to the local maven
repository (typically
+ located in ~/.m2/repository).
+
+ The <<<deploy>>> task allows artifacts to be deployed to a remote maven
repository where they will
+ be available to other projects.
+
+ For examples of using the install and deploy tasks, see the
{{{examples/install-deploy.html} examples page}}.
- * {<<<versionsId>>>}, which can be used to drop version numbers in
filenames <(since 2.0.7)>
+* Using a Maven {POM} File
- 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:
+ In Maven, the Project Object Model (POM) represents a unit of work - one
exists for each artifact that is built.
------
-<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>
------
+ 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.
- <<Note:>> In the above example you only need to specify
- <<<classpathref="maven-ant-tasks.classpath">>> if are using Maven Ant Tasks
- by {{{installation.html#typedef} declaring a <<<typedef>>>}}.
- It can be omitted if Maven Ant Tasks was
- {{{installation.html#lib} installed in Ant's <<<lib>>> directory}}.
-
-** Accessing dependencies using properties
-
- <(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:
+ It can also be reused for declaring your own dependencies, instead of
specifying the inline version given earlier.
------
-<echo message="JUnit jar file downloaded to ${junit:junit:jar}"/>
------
+ For examples of creating a pom and using the <<<pom>>> task, see the
{{{examples/pom.html}examples page}}.
* Declaring Repositories
@@ -174,181 +111,6 @@
<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="mypom" file="pom.xml" />
-
- <echo>The version is ${mypom.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="mypom" file="pom.xml" />
-
- <echo>The build directory is ${mypom.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}}.
-
-** Accessing dependencies in the POM
-
- The <<<pom>>> task can be used in combination with the <<<dependencies>>>
task to declare a list of dependencies.
-
------
- <artifact:pom id="mypom" file="pom.xml" />
-
- <artifact:dependencies filesetId="mydeps" pomRefId="mypom" />
------
-
- In this example, the <<<dependencies>>> task in this example will resolve
the list of dependencies in the pom
- and add them to the fileset.
-
-** Using profiles in the POM
-
- POM profiles can be activated or deactivated using the nested profile
element. For example
- to activate a profile called <<my-profile>>.
-
------
- <artifact:pom id="maven.project" file="pom.xml">
- <profile id="my-profile"/>
- </artifact:pom>
------
-
- This can also be used to deactivate a POM profile that is active by default.
-
------
- <artifact:pom id="maven.project" file="pom.xml">
- <profile id="my-default-profile" active="false"/>
- </artifact:pom>
------
-
-* 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
@@ -411,6 +173,12 @@
* Examples
+ * {{{examples/dependencies.html} dependencies task}}
+
+ * {{{examples/install-deploy.html} install and deploy tasks }}
+
+ * {{{examples/pom.html} pom task }}
+
* Maven Ant Tasks's
{{{http://svn.apache.org/repos/asf/maven/ant-tasks/branches/maven-ant-tasks-2.0.x/sample.build.xml}
sample.build.xml}}
is a sample Ant script showing most of the functionality in action (it's
used as unit-tests).
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=772397&r1=772396&r2=772397&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 Wed May 6
18:30:13 2009
@@ -28,17 +28,18 @@
<item name="Release Notes" href="release-notes.html"/>
<item name="FAQ" href="faq.html"/>
</menu>
- <menu name="References">
- <item name="Task Reference" href="reference.html#Task">
- <item name="dependencies" href="reference.html#dependencies"/>
- <item name="install, deploy" href="reference.html#install"/>
- <item name="install-provider" href="reference.html#install-provider"/>
- </item>
- <item name="Type Reference" href="reference.html#Type">
- <item name="localRepository" href="reference.html#localRepository"/>
- <item name="remoteRepository" href="reference.html#remoteRepository"/>
- <item name="pom" href="reference.html#pom"/>
- </item>
+ <menu name="Examples">
+ <item name="dependencies" href="examples/dependencies.html"/>
+ <item name="install, deploy" href="examples/install-deploy.html"/>
+ <item name="pom" href="examples/pom.html"/>
+ </menu>
+ <menu name="Reference">
+ <item name="dependencies" href="reference.html#dependencies"/>
+ <item name="install, deploy" href="reference.html#install"/>
+ <item name="install-provider" href="reference.html#install-provider"/>
+ <item name="localRepository" href="reference.html#localRepository"/>
+ <item name="remoteRepository" href="reference.html#remoteRepository"/>
+ <item name="pom" href="reference.html#pom"/>
<item name="VersionMapper" href="reference.html#VersionMapper"/>
</menu>
</body>
