------
 Usage
 ------
 Kenney Westerhof, Franz Allan Valencia See, Vincent Siveton
 ------
 September 2006
 ------

 ~~ 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

Usage

* Run

  The maven-antrun-plugin has only one goal, <<<run>>>.

  This allows Maven to run Ant tasks. To do so, there must be an existing
  project and maven-antrun-plugin must have its <<<\<target\>>>> tag
  configured (although it would still execute without the <<<\<target\>>>> tag,
  it would not do anything). Below is the template for
  <<<maven-antrun-plugin>>>'s <<<pom.xml>>>.

------
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-antrun-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <phase> <!-- a lifecycle phase --> </phase>
            <configuration>
              <target>

                <!--
                  Place any Ant task here. You can add anything
                  you can add between <target> and </target> in a
                  build.xml.
                -->

              </target>
            </configuration>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
------

  Moreover, you can add a script to each lifecycle phase, by duplicating the
  <<<\<execution/\>>>> section and specifying a new phase.

  Ultimately, you could specify some Ant {{{http://ant.apache.org/manual/using.html#targets}<<<\<target/\>>>>}}
  attributes in the <<<\<target/\>>>> tag. Only <<<depends>>> attribute in Ant <<<\<target/\>>>> is not wrapped.

------
[...]
<configuration>
  <target name="The name of the target"
    if="The name of the property that must be set in order for this task"
    unless="The name of the property that must NOT be set in order for this task"
    description="A short description of this target's function">

    <!--
      Place any Ant task here. You can add anything
      you can add between <target> and </target> in a
      build.xml.
    -->

  </target>
<configuration>
[...]
------

* Additional source directories

  If your Ant tasks generate additional source code that needs to be added 
  to the build, you can use the 
  {{{http://www.mojohaus.org/build-helper-maven-plugin/}build-helper-maven-plugin}}.  
  The <<<sourceRoot>>> and <<<testSourceRoot>>> options of the antrun plugin are removed as of version 3.0.0.

* Using Maven properties

  All of the properties available to Maven are also available in the target
  configuration.  However, you may want to call an external Ant build script
  using the <ant> task.  To avoid name conflicts, only a subset of the properties
  are passed to the external Ant build.  These include all properties defined in
  the <properties> section of the POM.  It also includes prefixed versions of
  some of the commonly used Maven properties.
  
------
  maven.project.groupId
  maven.project.artifactId
  maven.project.name
  etc.
------
  
  If the Maven property you want to use is not available in an external file, you
  will have to redefine the property before calling <ant>.
  
------
  <property name="maven.project.url" value="\${project.url}"/>
  <ant antfile="build.xml"/>
------

* Ant Expressions to Maven Expressions Mapping

  Some Ant expressions have their respective counterparts in Maven. Thus, one
  can simply invoke the corresponding Maven expression instead of using
  maven-antrun-plugin to avoid the unneccessary overhead.

*-----------------------------------+-----------------------------------+
| <<Ant Expression>>                | <<Maven Expression>>              |
*-----------------------------------+-----------------------------------+
| Built-in Tasks                    |                                   |
*-----------------------------------+-----------------------------------+
| <<<Ant>>>                         | {{{../maven-antrun-plugin/}<<<maven-antrun-plugin>>>}}               |
*-----------------------------------+-----------------------------------+
| <<<AntCall>>>                     | {{{../maven-antrun-plugin/}<<<maven-antrun-plugin>>>}}               |
*-----------------------------------+-----------------------------------+
| <<<Available>>>                   | {{{http://maven.apache.org/guides/introduction/introduction-to-profiles.html}<<<profiles>>>}}                         |
*-----------------------------------+-----------------------------------+
| <<<BUnzip2>>>                     | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<BZip2>>>                       | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<Chmod>>>                       | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<Condition>>>                   | {{{http://maven.apache.org/guides/introduction/introduction-to-profiles.html}<<<profiles>>>}}                         |
*-----------------------------------+-----------------------------------+
| <<<Copy>>>                        | {{{../maven-resources-plugin/}<<<maven-resources-plugin>>>}}            |
*-----------------------------------+-----------------------------------+
| <<<Dependset>>>                   | {{{../maven-dependency-plugin/}<<<maven-dependency-plugin>>>}}         |
*-----------------------------------+-----------------------------------+
| <<<Ear>>>                         | {{{../maven-ear-plugin/}<<<maven-ear-plugin>>>}}                  |
*-----------------------------------+-----------------------------------+
| <<<Filter>>>                      | {{{../maven-resources-plugin/}<<<maven-resources-plugin>>>}}            |
|                                   | <Note: Filter uses the @...@ token while maven-resources-plugin uses the \${...} token> |
*-----------------------------------+-----------------------------------+
| <<<FixCRLF>>>                     | {{{../maven-resources-plugin/}<<<maven-resources-plugin>>>}}            |
*-----------------------------------+-----------------------------------+
| <<<GenKey>>>                      | {{{../maven-jar-plugin/}<<<maven-jar-plugin>>>}}                  |
*-----------------------------------+-----------------------------------+
| <<<GUnzip>>>                      | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<GZip>>>                        | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<Jar>>>                         | {{{../maven-jar-plugin/}<<<maven-jar-plugin>>>}}                  |
*-----------------------------------+-----------------------------------+
| <<<Javac>>>                       | {{{../maven-compiler-plugin/}<<<maven-compiler-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<Javadoc/Javadoc2>>>            | {{{../maven-javadoc-plugin/}<<<maven-javadoc-plugin>>>}}               |
*-----------------------------------+-----------------------------------+
| <<<LoadProperties>>>              | {{{../maven-resources-plugin/}<<<maven-resources-plugin>>>}}            |
*-----------------------------------+-----------------------------------+
| <<<Manifest>>>                    | {{{../maven-jar-plugin/}<<<maven-jar-plugin>>>}}                  |
*-----------------------------------+-----------------------------------+
| <<<Property>>>                    | {{{../maven-resources-plugin/}<<<maven-resources-plugin>>>}}            |
*-----------------------------------+-----------------------------------+
| <<<Replace>>>                     | {{{../maven-resources-plugin/}<<<maven-resources-plugin>>>}}            |
|                                   | <Note: Replace can specify its token while maven-resources-plugin uses the \${...} token> |
*-----------------------------------+-----------------------------------+
| <<<Tar>>>                         | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<Unjar>>>                       | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<Untar>>>                       | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<Unwar>>>                       | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<Unzip>>>                       | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<War>>>                         | {{{../maven-war-plugin/}<<<maven-war-plugin>>>}}                  |
*-----------------------------------+-----------------------------------+
| <<<Zip>>>                         | {{{../maven-assembly-plugin/}<<<maven-assembly-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| Optional Tasks                                                        |
*-----------------------------------+-----------------------------------+
| <<<Antlr>>>                       | {{{../maven-antlr-plugin/}<<<maven-antlr-plugin>>>}}                |
*-----------------------------------+-----------------------------------+
| <<<Depend>>>                      | {{{../maven-dependency-plugin/}<<<maven-dependency-plugin>>>}}         |
*-----------------------------------+-----------------------------------+
| <<<EJB Tasks>>>                   | {{{../maven-ejb-plugin/}<<<maven-ejb-plugin>>>}}                  |
*-----------------------------------+-----------------------------------+
| <<<FTP>>>                         | {{{../maven-deploy-plugin/}<<<maven-deploy-plugin>>>}}               |
|                                   | <Note: maven-deploy-plugin can only deploy unto the FTP> |
*-----------------------------------+-----------------------------------+
| <<<JavaCC>>>                      | {{{../maven-compiler-plugin/}<<<maven-compiler-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<JJDoc>>>                       | {{{../maven-compiler-plugin/}<<<maven-compiler-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<JJTree>>>                      | {{{../maven-compiler-plugin/}<<<maven-compiler-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<JUnit>>>                       | {{{../maven-surefire-plugin/}<<<maven-surefire-plugin>>>}}             |
*-----------------------------------+-----------------------------------+
| <<<JUnitReport>>>                 | {{{../maven-surefire-report-plugin/}<<<maven-surefire-report-plugin>>>}}      |
*-----------------------------------+-----------------------------------+
| <<<ServerDeploy>>>                | {{{../maven-deploy-plugin/}<<<maven-deploy-plugin>>>}}               |
*-----------------------------------+-----------------------------------+
| <<<Setproxy>>>                    | {{{../maven-deploy-plugin/}<<<maven-deploy-plugin>>>}}               |
*-----------------------------------+-----------------------------------+
| <<<Translate>>>                   | {{{../maven-resources-plugin/}<<<maven-resources-plugin>>>}}            |
|                                   | <Note: Translate can specify its own tokens and can have a different encoding scheme for reading and writing files. maven-resources-plugin however uses the \${...} annotation only and has only one encoding scheme for reading and writing> |
*-----------------------------------+-----------------------------------+