From 5ce4088294a82ec89f9a0b3c30f6d77fc17c14c1 Mon Sep 17 00:00:00 2001 From: Conor MacNeill Date: Thu, 11 Jan 2001 00:40:32 +0000 Subject: [PATCH] Major documentation update. Submitted by: Diane Holt [holtdl@yahoo.com] git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@268428 13f79535-47bb-0310-9956-ffa450edef68 --- docs/index.html | 1522 ++++++++++++++++++++++++++++------------------- 1 file changed, 895 insertions(+), 627 deletions(-) diff --git a/docs/index.html b/docs/index.html index 0370fade2..e4139d86c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -7,8 +7,10 @@ +

Ant User Manual

by

+
-

Version: @VERSION@

-

$Id$

+
+

Version: @VERSION@
+$Id$

+

Table of Contents

@@ -40,45 +44,55 @@
  • Installing Ant
  • Building Ant
  • Running Ant
    • -
  • Writing a simple buildfile -
  • Directory based tasks
    • -
  • Built in Tasks +
  • Writing a Simple Buildfile +
  • Directory-based Tasks
    • +
  • Built-in Tasks
  • Optional Tasks
  • Build Events -
  • Writing your own task
    • -
  • FAQ, DTD, external resources +
  • Writing Your Own Task
    • +
  • FAQ, DTD, External Resources
  • License
  • Feedback

    • Introduction

    -

    Ant is a Java based build tool. In theory it is kind of like make without -make's wrinkles.

    +

    Ant is a Java-based build tool. In theory, it is kind of like +make, without make's wrinkles.

    Why?

    -

    Why another build tool when there is already make, gnumake, nmake, jam, and -others? Because all of those tools have limitations that its original author -couldn't live with when developing software across multiple platforms. Make like -tools are inherently shell based. They evaluate a set of dependencies and then -execute commands not unlike what you would issue on a shell. This means that you +

    Why another build tool when there is already +make, +gnumake, +nmake, +jam, +and +others? Because all those tools have limitations that Ant's original author +couldn't live with when developing software across multiple platforms. +Make-like +tools are inherently shell-based: they evaluate a set of dependencies, +then execute commands not unlike what you would issue on a shell. +This means that you can easily extend these tools by using or writing any program for the OS that -you are working on. However, this also means that you limit yourself to the OS, -or at least the OS type such as Unix, that you are working on.

    +you are working on; however, this also means that you limit yourself to the OS, +or at least the OS type, such as Unix, that you are working on.

    Makefiles are inherently evil as well. Anybody who has worked on them for any time has run into the dreaded tab problem. "Is my command not executing -because I have a space in front of my tab!!!" said the original author of +because I have a space in front of my tab?!!" said the original author of Ant way too many times. Tools like Jam took care of this to a great degree, but -still use yet another format to use and remember.

    -

    Ant is different. Instead a model where it is extended with shell based -commands, it is extended using Java classes. Instead of writing shell commands, -the configuration files are XML based calling out a target tree where various -tasks get executed. Each task is run by an object which implements a particular +still have yet another format to use and remember.

    +

    Ant is different. Instead of a model where it is extended with shell-based +commands, Ant is extended using Java classes. Instead of writing shell commands, +the configuration files are XML-based, calling out a target tree where various +tasks get executed. Each task is run by an object that implements a particular Task interface.

    -

    Granted, this removes some of the expressive power that is inherent by being -able to construct a shell command such as `find . -name foo -exec rm {}` but it -gives you the ability to be cross platform. To work anywhere and everywhere. And -hey, if you really need to execute a shell command, Ant has an exec rule that -allows different commands to be executed based on the OS that it is executing +

    Granted, this removes some of the expressive power that is inherent in being +able to construct a shell command such as +`find . -name foo -exec rm {}`, but it +gives you the ability to be cross-platform – to work anywhere and +everywhere. And +hey, if you really need to execute a shell command, Ant has an +<exec> task that +allows different commands to be executed based on the OS it is executing on.

    @@ -89,7 +103,7 @@ href="http://jakarta.apache.org/builds/ant/release/v1.2/bin/"> http://jakarta.apache.org/builds/ant/release/v1.2/bin/. If you like living on the edge, you can download the latest version from http://jakarta.apache.org/builds/ant/nightly/.

    -

    Source edition

    +

    Source Edition

    If you prefer the source edition, you can download Ant from http://jakarta.apache.org/builds/ant/release/v1.2/src/ @@ -101,30 +115,38 @@ build Ant from the source code.

    System Requirements

    - To build and use Ant you must have a JAXP compliant XML parser installed and available on your classpath. -

    - Both the binary and source distributions of Ant include the reference implementation of JAXP 1.0. - Please see http://java.sun.com/xml/ for more information. - If you wish to use a different, JAXP-compliant parser, you should remove jaxp.jar and parser.jar - from Ant's lib/core directory. You can then either put the jars from your preferred parser into Ant's - lib/core directory or put the jars on the system classpath. -

    - For the current version of Ant, you will also need the JDK installed on your system, version 1.1 - or later. A future version of Ant will require JDK 1.2 or later. -

    +To build and use Ant, you must have a JAXP-compliant XML parser installed and available on your classpath. +

    +Both the binary and source distributions of Ant include the reference implementation of JAXP 1.0. +Please see http://java.sun.com/xml/ for more information. +If you wish to use a different JAXP-compliant parser, you should remove +jaxp.jar and parser.jar +from Ant's lib/core directory. +You can then either put the jars from your preferred parser into Ant's +lib/core directory or put the jars on the system classpath. +

    +For the current version of Ant, you will also need a JDK installed on +your system, version 1.1 or later. A future version of Ant will require +JDK 1.2 or later. +

    Installing Ant

    -

    The binary distribution of Ant consists of four directories: bin, -docs, lib and src. Only the bin -and lib directory are required for running Ant. To run Ant, the +

    The binary distribution of Ant consists of four directories: +bin, +docs, +lib and +src. Only the bin +and lib directories are required for running Ant. To run Ant, the following must be done:

    Windows

    Assume Ant is installed in c:\ant\. The following sets up the @@ -138,92 +160,112 @@ the environment:

    export ANT_HOME=/usr/local/ant
 export JAVA_HOME=/usr/local/jdk-1.2.2
 export PATH=${PATH}:${ANT_HOME}/bin
    +

    Advanced

    +

    There are lots of variants that can be used to run Ant. What you need is at least the following:

    -

    The classpath for Ant must contain ant.jar and any jars/classes -needed for your chosen JAXP compliant XML parser.

    -

    When you need JDK functionality (like a javac task, or a +

    +The classpath for Ant must contain ant.jar and any jars/classes +needed for your chosen JAXP-compliant XML parser.

    +

    When you need JDK functionality +(such as for the javac task or the rmic task), then for JDK 1.1, the classes.zip file of the JDK must be added to the classpath; for JDK 1.2 or JDK 1.3, tools.jar -must be added. The scripts supplied with ant, in the bin directory, will add -tools.jar automatically if the JAVA_HOME environment variable is set.

    -

    When you are executing platform specific applications (like the exec task, or the cvs task), the property ant.home -must be set to the directory containing a bin directory, which contains the antRun -shell script necessary to run execs on Unix.

    - +must be added. The scripts supplied with Ant, +in the bin directory, will add +the required JDK classes automatically, if the JAVA_HOME +environment variable is set.

    +

    When you are executing platform-specific applications (such as the exec task or the cvs task), the property ant.home +must be set to the directory containing +the antRun shell script necessary to run exec's on Unix.

    +

    Building Ant

    -

    To build ant you should install the Ant source distribution. Whilst the binary distribution -includes the Ant source code, it is intended for reference purposes only. The boostrap and -build scripts used to build ant itself are not included in the binary distribution +

    To build Ant, you should install the Ant source distribution. +While the binary distribution +includes the Ant source code, it is intended for reference purposes only. +The bootstrap and build scripts used to build Ant itself are not included +in the binary distribution.

    Once you have installed the source distribution, go to the -directory jakarta-ant.

    -

    Set the JAVA_HOME environment variable. This should be set to the -directory where the JDK is installed. See Installing Ant +jakarta-ant directory.

    +

    Set the JAVA_HOME environment variable +to the directory where the JDK is installed. +See Installing Ant for examples on how to do this for your operating system.

    -

    Make sure you have downloaded any auxilliary jars required to build tasks you are -interested in. These should either be available on the classpath or added to Ant's lib -directory. The list of auxilliary tasks and requirements is in lib/README

    +

    Make sure you have downloaded any auxilliary jars required to +build tasks you are interested in. These should either be available +on the classpath or added to Ant's lib +directory. The list of auxilliary tasks and requirements is in +lib/README.

    Run bootstrap.bat (Windows) or bootstrap.sh (UNIX) to build a bootstrap version of Ant.

    -

    When finished, use

    +

    When finished, use:

    -

    build -Dant.dist.dir=<directory to contain Ant distribution> dist

    +

    build -Dant.dist.dir=<directory_to_contain_Ant_distribution> dist    (Windows)

    +

    build.sh -Dant.dist.dir=<directory_to_contain_Ant_distribution> dist    (Unix)

    -

    for Windows, and

    -
    -

    build.sh -Dant.dist.dir=<directory to Ant distribution> dist

    -
    -

    for UNIX, to create a binary distribution of Ant. This distribution can be +

    to create a binary distribution of Ant. This distribution can be found in the directory you specified.

    -If you wish to install the build into the current ANT_HOME directory, you can use +If you wish to install the build into the current ANT_HOME +directory, you can use:
    -

    build install    (Windows)

    -

    build.sh install    (Unix)

    +

    build install    (Windows)

    +

    build.sh install    (Unix)

    -You can avoid the length Javadoc step, if desired, with +You can avoid the lengthy Javadoc step, if desired, with:
    -

    build mininstall    (Windows)

    -

    build.sh mininstall    (Unix)

    +

    build mininstall    (Windows)

    +

    build.sh mininstall    (Unix)

    -This will only install the bin and lib directories. +This will only install the bin and lib directories.

    Both the install and mininstall targets will overwrite -the current ant version in ANT_HOME. +the current Ant version in ANT_HOME.

    Running Ant

    Running Ant is simple, when you installed it as described in the previous section. Just type ant.

    When nothing is specified, Ant looks for a build.xml -file in the current directory. When found, it uses that file as a -buildfile. If you use the -find option, Ant will search for a build file in -the parent directory and so on until the root of the filesystem +file in the current directory. If found, it uses that file as the +buildfile. If you use the -find option, +Ant will search for a buildfile in +the parent directory, and so on, until the root of the filesystem has been reached. To make Ant use -another buildfile, use the commandline option -buildfile -<file>, where <file> is the buildfile you want -to use.

    -

    You can also set properties which override properties specified in the -buildfile (see the property task). -This can be done with the -D<property>=<value> -option, where <property> is the name of the property and <value> -the value. This can also be used (and is the only way since Java can not access them) -to have access to your environment variables, just pass -DMYVAR=%MYVAR% (Windows) or --DMYVAR=$MYVAR (Unix) to Ant, you can then access these variables inside your build-file -as ${MYVAR}.

    -

    Two more options are -quiet which instructs Ant to print less -information on the console when running. The option -verbose on the other -hand makes Ant print more information on the console.

    -

    It is also possible to specify one or more targets that should be executed. When omitted the target that is mentioned in the default attribute of the project is +another buildfile, use the command-line +option -buildfile file, +where file is the buildfile you want to use.

    +

    You can also set properties that override properties specified in the +buildfile (see the property task). +This can be done with +the -Dproperty=value option, +where property is the name of the property, +and value is the value for that property. +This can also be used to have access to your environment variables +(and is the only way, since Java cannot access them). +Just pass -DMYVAR=%MYVAR% (Windows) or +-DMYVAR=$MYVAR (Unix) +to Ant – you can then access +these variables inside your buildfile as ${MYVAR}.

    +

    Two more options are: -quiet, +which instructs Ant to print less +information on the console when running, and +-verbose, which causes Ant to print +additional information to the console.

    +

    It is also possible to specify one or more targets that should be executed. +When omitted, the target that is specified in the +default attribute of the <project> tag is used.

    -

    The -projecthelp option gives a list of this projects targets. First those with a description and then those without one.

    -

    Commandline option summary:

    +

    The -projecthelp +option gives a list of this project's +targets. First those with a description, then those without one.

    +

    Command-line option summary:

    ant [options] [target [target2 [target3] ...]]
 Options:
 -help                  print this message
@@ -233,12 +275,13 @@ Options:
 -verbose               be extra verbose
 -debug                 print debugging information
 -emacs                 produce logging information without adornments
--logfile <file>        use given file for log
--logger <classname>    the class which is to perform logging
--listener <classname>  add an instance of class as a project listener
--buildfile <file>      use given buildfile
--find <file>           search for buildfile towards the root of the filesystem and use it
--D<property>=<value>   use value for given property
    +-logfile file use given file for log output +-logger classname the class that is to perform logging +-listener classname add an instance of class as a project listener +-buildfile file use specified buildfile +-find file search for buildfile towards the root of the filesystem and use the first one found +-Dproperty=value set property to value +

    Examples

    ant
    @@ -259,10 +302,11 @@ target called dist.

    ant -buildfile test.xml -Dbuild=build/classes dist

    runs Ant using the test.xml file in the current directory, on a -target called dist. It also sets the build property to the -value build/classes.

    -

    Running Ant by hand

    -

    When you have installed Ant in the do-it-yourself way, Ant can be started +target called dist, setting the build property to the +value build/classes.

    + +

    Running Ant by Hand

    +

    If you have installed Ant in the do-it-yourself way, Ant can be started with:

    java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]
    @@ -270,20 +314,21 @@ with:

    These instructions actually do exactly the same as the ant command. The options and target are the same as when running Ant with the ant -command. This example assumes you have set up your classpath to include +command. This example assumes you have set your classpath to include:

    -

    Writing a simple buildfile

    -

    The buildfile is written in XML. Each buildfile contains one project.

    -

    Each element of the buildfile can have an id attribute and +

    Writing a Simple Buildfile

    +

    Ant's buildfiles are written in XML. Each buildfile contains one project.

    +

    Each task element of the buildfile can have an id attribute and can later be referred to by the value supplied to this. The value has -to be unique.

    +to be unique. (For additional information, see the + Tasks section below.)

    Projects

    -

    A project has three attributes:

    +

    A project has three attributes:

    @@ -303,22 +348,32 @@ to be unique.

    + done. This attribute might be overridden by setting + the "basedir" + property beforehand. When this is done, it must be omitted in the + project tag. If neither the attribute nor the property have + been set, the parent directory of the buildfile will be used.
    Attribute
    basedir the base directory from which all path calculations are - done. This attribute might be overridden by setting the "basedir" - property on forehand. When this is done, it must be omitted in the - project tag. If neither the attribute not the property have - been set, the parent directory of the build file will be used. No
    -

    Each project defines one or more targets. A target is a set of tasks you want -to be executed. When starting Ant, you can select which target you want to have -executed. When no target is given, the project's default is used.

    +

    Each project defines one or more targets. +A target is a set of tasks you want +to be executed. When starting Ant, you can select which target(s) you +want to have executed. When no target is given, +the project's default is used.

    +

    Targets

    A target can depend on other targets. You might have a target for compiling, -for instance, and a target for creating a distributable. You can only build a -distributable when you have compiled first, so the distribute target depends on -the compile target. Ant resolves all these dependencies.

    -

    Ant tries to execute the targets in the depends attribute in the order +for example, and a target for creating a distributable. You can only build a +distributable when you have compiled first, so the distribute target +depends on the compile target. Ant resolves these dependencies.

    +

    It should be noted, however, that Ant's depends attribute +only specifies the order in which targets should be executed – it +does not affect whether the target that specifies the dependency(s) gets +executed if the dependent target(s) did not (need to) run. +

    +

    Ant tries to execute the targets in the depends +attribute in the order they appear (from left to right). Keep in mind that it is possible that a target can get executed earlier when an earlier target depends on it:

    @@ -327,30 +382,33 @@ can get executed earlier when an earlier target depends on it:

    <target name="C" depends="B"/> <target name="D" depends="C,B,A"/>
    -

    Suppose we want to execute target D. From its depends attribute, you -might think that first target C, then B and then A is executed. Wrong! C depends -on B, and B depends on A, so first A is executed, then B, then C, and finally D.

    -

    A target gets executed only once. Even when more targets depend on it (see -the previous example).

    -

    A target has also the ability to perform its execution if (or +

    Suppose we want to execute target D. From its +depends attribute, you +might think that first target C, then B and then A is executed. +Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.

    +

    A target gets executed only once, even when more than one target +depends on it (see the previous example).

    +

    A target also has the ability to perform its execution if (or unless) a property has been set. This allows, for example, better control on the building process depending on the state of the system -(java version, OS, command line properties, etc...). To make target -sense this property you should add the if (or -unless) attribute with the name of the property that the target -should react to, for example

    +(java version, OS, command-line property defines, etc.). To make a target +sense this property, you should add the if (or +unless) attribute with the name of the property that the target +should react to. For example:

    <target name="build-module-A" if="module-A-present"/>
    <target name="build-own-fake-module-A" unless="module-A-present"/>
    -

    If no if and no unless attribute is present, the target will -always be executed.

    +

    If no if and no unless attribute is present, +the target will always be executed.

    +

    The optional description attribute can be used to provide a one-line description of this target, which is printed by the +-projecthelp command-line option.

    It is a good practice to place your tstamp tasks in a so called initialization target, on which +href="#tstamp">tstamp tasks in a so-called +initialization target, on which all other targets depend. Make sure that target is always the first one in the depends list of the other targets. In this manual, most initialization targets have the name "init".

    -

    The optional description attribute can be used to provide a one line description of this target that is printed by the -projecthelp commandline option.

    A target has the following attributes:

    @@ -365,7 +423,7 @@ have the name "init".

    - @@ -383,178 +441,223 @@ have the name "init".

    - +
    dependsa comma separated list of names of targets on which this + a comma-separated list of names of targets on which this target depends. No
    descriptiona short description of this targets function.a short description of this target's function. No
    + +

    Tasks

    +

    A task is a piece of code that can be executed.

    -

    A task can have multiple attributes (or arguments if you prefer). The value +

    A task can have multiple attributes (or arguments, if you prefer). The value of an attribute might contain references to a property. These references will be resolved before the task is executed.

    Tasks have a common structure:

    - 
    <name attribute1="value1" attribute2="value2" ... />
    + 
    <name attribute1="value1" attribute2="value2" ... />
    -

    where name is the name of the task, attribute-x the attribute name, and -value-x the value of this attribute.

    -

    There is a set of built in tasks, but it is also very +

    where name is the name of the task, +attributeN is the attribute name, and +valueN is the value for this attribute.

    +

    There is a set of built-in tasks, along with a +number of + optional tasks, but it is also very easy to write your own.

    -

    All tasks share a taskname attribute. The value of +

    All tasks share a task name attribute. The value of this attribute will be used in the logging messages generated by Ant.

    +Tasks can be assigned an id attribute: +
    +
    <taskname id="taskID" ... />
    +
    +where taskname is the name of the task, and taskID is +a unique name for this task. +You can refer to the +corresponding task object in scripts or other tasks via this name. +For example, in scripts you could do: +
    +
    +<script ... >
+  task1.setFoo("bar");
+</script>
+
    +
    +to set the foo attribute of this particular task instance. +In another task (written in Java), you can access the instance via +project.getReference("task1"). +

    +Note1: If "task1" has not been run yet, then +it has not been configured (ie., no attributes have been set), and if it is +going to be configured later, anything you've done to the instance may +be overwritten. +

    +

    +Note2: Future versions of Ant will most likely not +be backward-compatible with this behaviour, since there will likely be no +task instances at all, only proxies. +

    +

    Properties

    A project can have a set of properties. These might be set in the buildfile by the property task, or might be set outside Ant. A -property has a name and a value. Properties might be used in in the value of +property has a name and a value. Properties may be used in the value of task attributes. This is done by placing the property name between -"${" and "}" in the attribute value.

    -

    If there is a property called "builddir" with the value -"build", then this could be used in an attribute like this: "${builddir}/classes". -This is resolved as "build/classes".

    -

    Built in Properties

    +"${" and "}" in the +attribute value. For example, +if there is a "builddir" property with the value +"build", then this could be used in an attribute like this: +${builddir}/classes. +This is resolved as build/classes.

    + +

    Built-in Properties

    Ant provides access to all system properties as if they had been -defined using a property task, for example ${os.name} expands to the +defined using a <property> task. +For example, ${os.name} expands to the name of the operating system.

    -

    In addition Ant knows some built in properties:

    - +

    In addition, Ant has some built-in properties:

    +
    +basedir             the absolute path of the project's basedir (as set
+                    with the basedir attribute of <project>).
+ant.file            the absolute path of the buildfile.
+ant.project.name    the name of the project that is currently executing;
+                    it is set in the name attribute of <project>.
+ant.java.version    the JVM version Ant detected; currently it can hold
+                    the values "1.1", "1.2" and "1.3".
+
    +

    Example

    -
    - 
    +
     <project name="MyProject" default="dist" basedir=".">
 
   <!-- set global properties for this build -->
-  <property name="src" value="." />
-  <property name="build" value="build" />
-  <property name="dist"  value="dist" />
+  <property name="src" value="."/>
+  <property name="build" value="build"/>
+  <property name="dist"  value="dist"/>
 
-  <target name="prepare">
+  <target name="init">
     <!-- Create the time stamp -->
     <tstamp/>
     <!-- Create the build directory structure used by compile -->
-    <mkdir dir="${build}" />
+    <mkdir dir="${build}"/>
   </target>
 
-  <target name="compile" depends="prepare">
+  <target name="compile" depends="init">
     <!-- Compile the java code from ${src} into ${build} -->
-    <javac srcdir="${src}" destdir="${build}" />
+    <javac srcdir="${src}" destdir="${build}"/>
   </target>
 
   <target name="dist" depends="compile">
-    <!-- Create the ${dist}/lib directory -->
-    <mkdir dir="${dist}/lib" />
+    <!-- Create the distribution directory -->
+    <mkdir dir="${dist}/lib"/>
 
     <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
-    <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}" />
+    <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
   </target>
 
   <target name="clean">
     <!-- Delete the ${build} and ${dist} directory trees -->
-    <delete dir="${build}" />
-    <delete dir="${dist}" />
+    <delete dir="${build}"/>
+    <delete dir="${dist}"/>
   </target>
 </project>
-  
    
-
    +

    Token Filters

    A project can have a set of tokens that might be automatically expanded if found when a file is copied, when the filtering-copy behavior is selected in the tasks that support this. These might be set in the buildfile by the filter task. 

    -

    Since this can be a very harmful behavior, the tokens in the files must -be of the form @token@ where token is the token name that is set +

    Since this can potentially be a very harmful behavior, +the tokens in the files must +be of the form @token@, where +token is the token name that is set in the filter task. This token syntax matches the syntax of other build systems that perform such filtering and remains sufficiently orthogonal to most -programming and scripting languages, as well with documentation systems.

    -

    Note: in case a token with the format @token@ is found in a file but no -filter is associated with that token, no changes take place. So, no escaping -method is present, but as long as you choose appropriate names for your tokens, -this should not cause problems.

    - -

    PATH like structures

    -

    You can specify PATH and CLASSPATH variables using both -":" and ";" as separator characters, Ant will -convert it to the correct character of the current operating +programming and scripting languages, as well as with documentation systems.

    +

    Note: If a token with the format @token@ +is found in a file, but no +filter is associated with that token, no changes take place; +therefore, no escaping +method is available – but as long as you choose appropriate names for your +tokens, this should not cause problems.

    + +

    Path-like Structures

    +

    You can specify PATH- and CLASSPATH-type +references using both +":" and ";" as separator +characters. Ant will +convert the separator to the correct character of the current operating system.

    -

    Wherever PATH like values need to be specified a nested element can -be used. This takes the general form of

    +

    Wherever path-like values need to be specified, a nested element can +be used. This takes the general form of:

         <classpath>
-      <pathelement path="${classpath}" />
-      <pathelement location="lib/helper.jar" />
+      <pathelement path="${classpath}"/>
+      <pathelement location="lib/helper.jar"/>
     </classpath>

    The location attribute specifies a single file or directory relative to the project's base directory (or an absolute -filename), while the path attribute accepts ":" -or ";" separated lists of locations. The path -attribute is intended to be used with predefined paths - in any other -case multiple elements with location attributes should be +filename), while the path attribute accepts colon- +or semicolon-separated lists of locations. The path +attribute is intended to be used with predefined paths – in any other +case, multiple elements with location attributes should be preferred.

    -

    As a shortcut the surrounding PATH element supports path and -location attributes of its own, so

    +

    As a shortcut, the <classpath> tag +supports path and +location attributes of its own, so:

         <classpath>
-      <pathelement path="${classpath}" />
+      <pathelement path="${classpath}"/>
     </classpath>
    -

    can be abreviated to

    +

    can be abreviated to:

    -    <classpath path="${classpath}" />
+    <classpath path="${classpath}"/>

    In addition, FileSets can be specified via nested <fileset> elements. The order in which the files -building up FileSet are added to the PATH like structure is not +building up a fileset are added to the path-like structure is not defined.

         <classpath>
-      <pathelement path="${classpath}" />
+      <pathelement path="${classpath}"/>
       <fileset dir="lib">
-        <include name="**/*.jar" />
+        <include name="**/*.jar"/>
       </fileset>
-      <pathelement location="classes" />
+      <pathelement location="classes"/>
     </classpath>
    -

    Builds a PATH which holds the value of ${classpath} -followed by all JAR files in the lib directory, followed +

    Builds a path that holds the value of ${classpath}, +followed by all jar files in the lib directory, followed by the classes directory.

    -

    If you want to use the same PATH like structure for several tasks, +

    If you want to use the same path-like structure for several tasks, you can define them with a <path> element at the -same level as targets and reference them via their -id attribute - see References for an +same level as targets, and reference them via their +id attribute – see References for an example.

    -

    A PATH like structure can include a reference to another PATH like -structure via a nested <path> elements.

    +

    A path-like structure can include a reference to another path-like +structure via nested <path> elements:

         <path id="base.path">
-      <pathelement path="${classpath}" />
+      <pathelement path="${classpath}"/>
       <fileset dir="lib">
-        <include name="**/*.jar" />
+        <include name="**/*.jar"/>
       </fileset>
-      <pathelement location="classes" />
+      <pathelement location="classes"/>
     </path>
 
     <path id="tests.path">
-      <path refid="base.path" />
-      <pathelement location="testclasses" />
+      <path refid="base.path"/>
+      <pathelement location="testclasses"/>
     </path>
    -

    Command line arguments

    - -

    Several tasks take arguments that shall be passed to another +

    Command-line Arguments

    +

    Several tasks take arguments that will be passed to another process on the command line. To make it easier to specify arguments -that contain space characters, nested elements can be used.

    +that contain space characters, nested arg elements can be used.

    @@ -563,58 +666,59 @@ that contain space characters, nested elements can be used.

    - - + - + -
    Attribute
    valuea single command line argument, can contain space + a single command-line argument; can contain space characters. Exactly one of these.
    linea space delimited list of command line arguments.a space-delimited list of command-line arguments.
    fileThe name of a file as a single command line - argument. Will be replaced with the absolute filename of the file - by Ant.The name of a file as a single command-line + argument; will be replaced with the absolute filename of the file.
    pathA string that shall be treated as a PATH like - string as a single command line argument. You can use ; or : as + A string that will be treated as a path-like + string as a single command-line argument; you can use ; + or : as path separators and Ant will convert it to the platform's local conventions.

    Examples

    -  <arg value="-l -a" />
+  <arg value="-l -a"/>
    -

    is a single command line argument containing a space character.

    +

    is a single command-line argument containing a space character.

    -  <arg line="-l -a" />
+  <arg line="-l -a"/>
    -

    stands for two separate command line arguments.

    +

    represents two separate command-line arguments.

    -  <arg path="/dir;/dir2:\dir3" />
+  <arg path="/dir;/dir2:\dir3"/>
    -

    is a single command line argument with value -\dir;\dir2;\dir3 on DOS based systems and -/dir:/dir2:/dir3 on Unix like systems.

    +

    is a single command-line argument with the value +\dir;\dir2;\dir3 on DOS-based systems and +/dir:/dir2:/dir3 on Unix-like systems.

    +

    References

    The id attribute of the buildfile's elements can be used to refer to them. This can useful if you are going to replicate -the same snippet of XML over and over again - using a +the same snippet of XML over and over again – using a <classpath> structure more than once for example.

    -

    The following example

    +

    The following example:

     <project ... >
   <target ... >
     <rmic ...>
       <classpath>
-        <pathelement location="lib/" />
-        <pathelement path="${java.class.path}/" />
-        <pathelement path="${additional.path}" />
+        <pathelement location="lib/"/>
+        <pathelement path="${java.class.path}/"/>
+        <pathelement path="${additional.path}"/>
       </classpath>
     </rmic>
   </target>
@@ -622,165 +726,202 @@ example.
    
   <target ... >
     <javac ...>
       <classpath>
-        <pathelement location="lib/" />
-        <pathelement path="${java.class.path}/" />
-        <pathelement path="${additional.path}" />
+        <pathelement location="lib/"/>
+        <pathelement path="${java.class.path}/"/>
+        <pathelement path="${additional.path}"/>
       </classpath>
     </javac>
   </target>
 </project>
    -

    could be rewritten as

    +

    could be rewritten as:

     <project ... >
   <path id="project.class.path">
-    <pathelement location="lib/" />
-    <pathelement path="${java.class.path}/" />
-    <pathelement path="${additional.path}" />
+    <pathelement location="lib/"/>
+    <pathelement path="${java.class.path}/"/>
+    <pathelement path="${additional.path}"/>
   </path>
 
   <target ... >
     <rmic ...>
-      <classpath refid="project.class.path" />
+      <classpath refid="project.class.path"/>
     </rmic>
   </target>
 
   <target ... >
     <javac ...>
-      <classpath refid="project.class.path" />
+      <classpath refid="project.class.path"/>
     </javac>
   </target>
 </project>

    All tasks that use nested elements for PatternSets, FileSets or -PATH like structures accept references to these +path-like structures accept references to these structures as well.

    +
    -

    Directory based tasks

    -

    Some tasks use directory trees for the task they perform. For instance, the Javac task which works upon a directory tree with .java files. +

    Directory-based Tasks

    +

    Some tasks use directory trees for the task they perform. +For example, the javac task, which works upon a directory tree +with .java files. Sometimes it can be very useful to work on a subset of that directory tree. This section describes how you can select a subset of such a directory tree.

    Ant gives you two ways to create a subset, both of which can be used at the same time:

    When both inclusion and exclusion are used, only files/directories that match -the include patterns, and don't match the exclude patterns are used.

    +the include patterns, and don't match the exclude patterns, are used.

    Patterns can be specified inside the buildfile via task attributes or nested elements and via external files. Each line of the external file -is taken as pattern that is added to the list of include or exclude +is taken as a pattern that is added to the list of include or exclude patterns.

    Patterns

    As described earlier, patterns are used for the inclusion and exclusion. These patterns look very much like the patterns used in DOS and UNIX:

    '*' matches zero or more characters, '?' matches one character.

    -

    Examples:

    -

    '*.java' matches '.java', 'x.java' and 'FooBar.java', but not 'FooBar.xml' -(does not end with '.java').

    -

    '?.java' matches 'x.java', 'A.java', but not '.java' or 'xyz.java' (both -don't have one character before '.java').

    -

    Combinations of '*'s and '?'s are allowed.

    +

    Examples:

    +

    +*.java  matches  .java, +x.java and FooBar.java, but +not FooBar.xml (does not end with .java).

    +

    +?.java  matches  x.java, +A.java, but not .java or xyz.java +(both don't have one character before .java).

    +

    +Combinations of *'s and ?'s are allowed.

    Matching is done per-directory. This means that first the first directory in the pattern is matched against the first directory in the path to match. Then -the second directories are matched, and so on. E.g. when we have the pattern '/?abc/*/*.java' -and the path '/xabc/foobar/test.java', then first '?abc' is matched with 'xabc', -then '*' is matched with 'foobar' and finally '*.java' is matched with 'test.java'. -They all match so the path matches the pattern.

    -

    Too make things a bit more flexible, we add one extra feature, which makes it +the second directory is matched, and so on. For example, when we have the pattern /?abc/*/*.java +and the path /xabc/foobar/test.java, +the first ?abc is matched with xabc, +then * is matched with foobar, +and finally *.java is matched with test.java. +They all match, so the path matches the pattern.

    +

    To make things a bit more flexible, we add one extra feature, which makes it possible to match multiple directory levels. This can be used to match a -complete directory tree, or a file anywhere in the directory tree. To do this, '**' -must be used as the name of a directory. When '**' is used as the name of a -directory in the pattern, it matches zero or more directories. For instance: -'/test/**' matches all files/directories under '/test/', such as '/test/x.java', -or '/test/foo/bar/xyz.html', but not '/xyz.xml'.

    -

    There is one "shorthand", if a pattern ends with '/' or '\', then '**' -is appended. E.g. "mypackage/test/" is interpreted as were it "mypackage/test/**".

    -

    Examples:

    +complete directory tree, or a file anywhere in the directory tree. +To do this, ** +must be used as the name of a directory. +When ** is used as the name of a +directory in the pattern, it matches zero or more directories. +For example: +/test/** matches all files/directories under /test/, +such as /test/x.java, +or /test/foo/bar/xyz.html, but not /xyz.xml.

    +

    There is one "shorthand" – if a pattern ends +with / +or \, then ** +is appended. +For example, mypackage/test/ is interpreted as if it were +mypackage/test/**.

    +

    Example patterns:

    - - - - - - - - - - - - - - + + + + + + + + + + + + + + +
    **/CVS/*Matches all files in CVS directories, that can be located - anywhere in the directory tree. -

    Matches:

    -

    CVS/Repository
    - org/apache/CVS/Entries
    - org/apache/jakarta/tools/ant/CVS/Entries

    -

    But not:

    -

    org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)

    org/apache/jakarta/**Matches all files in the org/apache/jakarta directory tree. -

    Matches:

    -

    org/apache/jakarta/tools/ant/docs/index.html
    - org/apache/jakarta/test.xml

    -

    But not:

    -

    org/apache/xyz.java ('jakarta'/' part is missing)

    org/apache/**/CVS/*Matches all files in CVS directories, that are located - anywhere in the directory tree under org/apache. -

    Matches:

    -

    org/apache/CVS/Entries
    - org/apache/jakarta/tools/ant/CVS/Entries

    -

    But not:

    -

    org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)

    **/test/**Matches all files which have a directory 'test' in their - path, including 'test' as a filename.**/CVS/*Matches all files in CVS directories that can be located + anywhere in the directory tree.
    + Matches: + 
    +      CVS/Repository
+      org/apache/CVS/Entries
+      org/apache/jakarta/tools/ant/CVS/Entries
+
    + But not: + 
    +      org/apache/CVS/foo/bar/Entries (foo/bar/ part does not match)
    org/apache/jakarta/**Matches all files in the org/apache/jakarta directory tree.
    + Matches: + 
    +      org/apache/jakarta/tools/ant/docs/index.html
+      org/apache/jakarta/test.xml
+
    + But not: + 
    +      org/apache/xyz.java
+
    + (jakarta/ part is missing).
    org/apache/**/CVS/*Matches all files in CVS directories + that are located anywhere in the directory tree under + org/apache.
    + Matches: + 
    +      org/apache/CVS/Entries
+      org/apache/jakarta/tools/ant/CVS/Entries
+
    + But not: + 
    +      org/apache/CVS/foo/bar/Entries
+
    + (foo/bar/ part does not match)
    **/test/**Matches all files that have a test + element in their path, including test as a filename.

    When these patterns are used in inclusion and exclusion, you have a powerful way to select just the files you want.

    +

    Examples

      
-<copy todir="${dist}" >
+<copy todir="${dist}">
   <fileset dir="${src}" 
            includes="**/images/*" 
            excludes="**/*.gif" 
   />
 </copy>
    -

    This copies all files in directories called "images", that are -located in the directory tree "${src}" to the destination "${dist}", -but excludes all "*.gif" files from the copy.

    -

    This example can also be expressed using nested elements as +

    This copies all files in directories called images that are +located in the directory tree defined by ${src} to the +destination directory defined by ${dist}, +but excludes all *.gif files from the copy.

    +

    This example can also be expressed using nested elements: 

    -<copy todir="${dist}" >
-  <fileset dir="${src}" />
+<copy todir="${dist}">
+  <fileset dir="${src}"/>
     <include name="**/images/*"/>
-    <exclude name="**/*.gif" />
+    <exclude name="**/*.gif"/>
   </fileset>
 </copy>

    Default Excludes

    -

    There are a set of definitions which are excluded by default from all directory based tasks. +

    There are a set of definitions that are excluded by default from all directory-based tasks. They are: -

            "**/*~",
-        "**/#*#",
-        "**/%*%",
-        "**/CVS",
-        "**/CVS/**",
-        "**/.cvsignore"
+
    +     **/*~
+     **/#*#
+     **/%*%
+     **/CVS
+     **/CVS/**
+     **/.cvsignore
 
    
 If you do not want these default excludes applied, you may disable them with the 
 defaultexcludes="no" attribute.
 
    PatternSets
    
-
    Patterns can be grouped to sets and later be referenced by their id
-attribute. They are defined via a patternset element -
+
    Patterns can be grouped to sets and later be referenced by their
+id
+attribute. They are defined via a patternset element,
 which can appear nested into a FileSet or a
-directory based task that constitutes an implicit FileSet. In addition
+directory-based task that constitutes an implicit FileSet. In addition,
 patternsets can be defined at the same level as
-target - i.e. as children of project
    
+target — i.e., as children of project.
    
 
    Patterns can be specified by nested <include> or
 <exclude> elements or the following attributes.
    
 
@@ -790,53 +931,56 @@ directory based task that constitutes an implicit FileSet. In addition
   
-    
-    
+    
-    
+    
-    
+    
    
   
    
     includescomma separated list of patterns of files that must be
+    comma-separated list of patterns of files that must be
       included. All files are included when omitted.
   
    
   
    
     includesfilethe name of a file. Each line of this file is
-      taken to be an include patternthe name of a file; each line of this file is
+      taken to be an include pattern.
   
    
   
    
     excludescomma separated list of patterns of files that must be
-      excluded. No files (except default excludes) are excluded when omitted.comma-separated list of patterns of files that must be
+      excluded; no files (except default excludes) are excluded when omitted.
   
    
   
    
     excludesfilethe name of a file. Each line of this file is
-      taken to be an exclude patternthe name of a file; each line of this file is
+      taken to be an exclude pattern.
   
    
 
    
+
 
    Examples
    
 
     <patternset id="non.test.sources" >
-  <include name="**/*.java" />
-  <exclude name="**/*Test*" />
+  <include name="**/*.java"/>
+  <exclude name="**/*Test*"/>
 </patternset>
 
    
-
    Builds a set of patterns, that matches all .java files
+
    Builds a set of patterns that matches all .java files
 that do not contain the text Test in their name. This set
 can be referred to via
-<patternset refid="non.test.sources"
-/> by tasks that support this feature or by FileSets.
    
-
    Note that while the includes and excludes attributes accept
+<patternset refid="non.test.sources"/>,
+by tasks that support this feature, or by FileSets.
    
+
    Note that while the includes and
+excludes attributes accept
 multiple elements separated by commas or spaces, the nested
 <include> and <exclude> elements expect their name
 attribute to hold a single pattern.
    
+
 
    FileSets
    
 
    FileSets are groups of files. These files can be found in a
 directory tree starting in a base directory and are matched by
 patterns taken from a number of PatternSets. FileSets can appear inside task
+href="#patternset">PatternSets. FileSets can appear inside tasks
 that support this feature or at the same level as target
-- i.e. as children of project.
    
+– i.e., as children of project.
    
 
    PatternSets can be specified as nested
 <patternset> 
-elements. In addition FileSet holds an implicit PatternSet and
+elements. In addition, FileSet holds an implicit PatternSet and
 supports the nested <include> and
-<exclude> elements of PatternSet directly as well
+<exclude> elements of PatternSet directly, as well
 as PatternSet's attributes.
    
 
@@ -846,46 +990,47 @@ as PatternSet's attributes.
    
-    
+    
+      (yes | no); default excludes are used when omitted.
-    
+    
-    
+    
-    
+    
-    
+    
    
   
    
   
    
   
    
     dirThe root of the directory tree of this FileSet.the root of the directory tree of this FileSet.
     Yes
   
    
   
    
     defaultexcludes
     indicates whether default excludes should be used or not
-      ("yes"/"no"). Default excludes are used when omitted.
     No
   
    
   
    
     includescomma separated list of patterns of files that must be
-      included. All files are included when omitted.comma-separated list of patterns of files that must be
+      included; all files are included when omitted.
     No
   
    
   
    
     includesfilethe name of a file. Each line of this file is
-      taken to be an include patternthe name of a file; each line of this file is
+      taken to be an include pattern.
     No
   
    
   
    
     excludescomma separated list of patterns of files that must be
-      excluded. No files (except default excludes) are excluded when omitted.comma-separated list of patterns of files that must be
+      excluded; no files (except default excludes) are excluded when omitted.
     No
   
    
   
    
     excludesfilethe name of a file. Each line of this file is
-      taken to be an exclude patternthe name of a file; each line of this file is
+      taken to be an exclude pattern.
     No
   
    
 
    
+
 
    Examples
    
 
     <fileset dir="${server.src}" >
   <patternset id="non.test.sources" >
-    <include name="**/*.java" />
-    <exclude name="**/*Test*" />
+    <include name="**/*.java"/>
+    <exclude name="**/*Test*"/>
   </patternset>
 </fileset>
 
    
@@ -894,26 +1039,26 @@ source files and don't have the text Test in their
 name.
    
 
     <fileset dir="${client.src}" >
-  <patternset refid="non.test.sources" />
+  <patternset refid="non.test.sources"/>
 </fileset>
 
    
-
    Groups all files in directory ${client.src} using the
-same patterns as the example before.
    
-
    Mapping file names
    
+
    Groups all files in directory ${client.src}, using the
+same patterns as the example above.
    
+
+
    Mapping File Names
    
 
    Some tasks take source files and create target files. Depending on
-the task it may be quite obvious which name a target file will have
+the task, it may be quite obvious which name a target file will have
 (using javac, you know there will be
-.class files for your .java files) - in
-other cases you may want to specify the target files either to help
+.class files for your .java files) – in
+other cases you may want to specify the target files, either to help
 Ant or to get an extra bit of functionality.
    
 
    While source files are usually specified as filesets, you don't specify target files directly,
-but tell Ant how to find the target file(s) for one source file. An
+href="#fileset">filesets, you don't specify target files directly –
+instead, you tell Ant how to find the target file(s) for one source file. An
 instance of org.apache.tools.ant.util.FileNameMapper is
 responsible for this. It constructs target file names based on rules
 that can be parameterized with from and to
-attributes - the exact meaning of which is implementation
-dependent.
    
+attributes – the exact meaning of which is implementation-dependent.
    
 
    These instances are defined in <mapper> elements
 with the following attributes:
    
 
@@ -924,12 +1069,12 @@ with the following attributes:
    
-    
+    
-    
+     
@@ -940,32 +1085,32 @@ with the following attributes:
    
+      href="#references">reference to a path defined elsewhere. 
-    
+     
-    
+    
    
   
   
    
     typeSpecify one of the built in implementationsspecifies one of the built-in implementations.
     Exactly one of both
   
    
   
    
     classnameSpecify the implementation by class namespecifies the implementation by class name.
   
    
   
    
     classpath
   
    
     classpathref
     the classpath to use, given as reference to a PATH defined elsewhere.
     No
   
    
   
    
     fromThe "from" attribute for the given
-      implementationthe from attribute for the given
+      implementation.
     Depends on implementation.
   
    
   
    
     toThe "to" attribute for the given
-      implementationthe to attribute for the given
+      implementation.
     Depends on implementation.
   
    
 
    
-
    The classpath can as well be specified via a nested
-<classpath>, that is a PATH
-like structure.
    
-
    The built in mapper types are:
    
+
    The classpath can be specified via a nested
+<classpath>, as well – that is,
+a path-like structure.
    
+
    The built-in mapper types are:
    
 
    identity
    
 
    The target file name is identical to the source file name. Both
 to and from will be ignored.
    
-
    Examples:
    
+Examples:
 
    -<mapper type="identity" />
+<mapper type="identity"/>
 
    
 
@@ -990,12 +1135,12 @@ like structure.
    
   
    
   
    
 
    
 
    flatten
    
-
    The target file name is identical to the source file name with all
-leading directory information stripped of. Both to and
+
    The target file name is identical to the source file name, with all
+leading directory information stripped off. Both to and
 from will be ignored.
    
-
    Examples:
    
+Examples:
 
    -<mapper type="flatten" />
+<mapper type="flatten"/>
 
    
 
@@ -1020,11 +1165,11 @@ leading directory information stripped of. Both to and
   
    
   
    
 
    
 
    merge
    
-
    The target file name will always be the same - as defined by
-to, from will be ignored.
    
+
    The target file name will always be the same, as defined by
+to – from will be ignored.
    
 
    Examples:
    
 
    -<mapper type="merge" to="archive.tar" />
+<mapper type="merge" to="archive.tar"/>
 
    
 
@@ -1051,14 +1196,14 @@ leading directory information stripped of. Both to and
 
    glob
    Both to and from define patterns that may
 contain at most one *. For each source file that matches
-the from pattern a target file name will be constructed
+the from pattern, a target file name will be constructed
 from the to pattern by substituting the * in
-the to pattern by the text that matches the
+the to pattern with the text that matches the
 * in the from pattern. Source file names
 that don't match the from pattern will be ignored.
    
-
    Examples:
    
+Examples:
    -<mapper type="glob" from="*.java" to="*.java.bak" />
+<mapper type="glob" from="*.java" to="*.java.bak"/>
 
    
   
    
 
 
 
    
@@ -1083,7 +1228,7 @@ that don't match the from pattern will be ignored.
    
   
    
   
    
 
    
 
    -<mapper type="glob" from="C*ies" to="Q*y" />
+<mapper type="glob" from="C*ies" to="Q*y"/>
 
    
 
@@ -1110,33 +1255,41 @@ that don't match the from pattern will be ignored.
    regexp
    Both to and from define regular
 expressions. If the source file name matches the from
-pattern, the target file name will constructed from the
-to pattern using \0 to \9 as back references for the full
-match (\0) or the matches of the subexpressions in parens. Source
+pattern, the target file name will be constructed from the
+to pattern, using \0 to \9 as
+back-references for the full
+match (\0) or the matches of the subexpressions in
+parentheses.
+Source
 files not matching the from pattern will be ignored.
    
-
    Note that you need to escape a $-sign with another $-sign in
-Ant.
    
+
    Note that you need to escape a dollar-sign ($) with
+another dollar-sign in Ant.
    The regexp mapper needs a supporting library and an implementation
 of org.apache.tools.ant.util.regexp.RegexpMatcher that
 hides the specifics of the library. Ant comes with implementations for
 jakarta-regexp and jakarta-ORO - if you compile
+href="http://jakarta.apache.org/oro/">jakarta-ORO. If you compile
 from sources and plan to use one of them, make sure the libraries are
-in your CLASSPATH. For information about using CLASSPATH. For information about using gnu.regexp or gnu.rex with Ant, see this
 article.
    
-
    Ant will choose the regular expression library based on the
-following algorithm: if the system property
+
    Ant will choose the regular-expression library based on the
+following algorithm:
+
      
+
    • If the system property
 ant.regexp.matcherimpl has been set, it is taken as the
 name of the class implementing
 org.apache.tools.ant.util.regexp.RegexpMatcher that
-should be used. If it has not been set, first try jakarta-ORO, if that
-cannot be found, try jakarta-regexp.
      
-
      Examples:
      
+should be used.
      • 
+
    • If it has not been set, first try jakarta-ORO; if that
+cannot be found, try jakarta-regexp.
      • 
+
    
+
    
+Examples:
    -<mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak" />
+<mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/>
 
    
   
    
 
 
 
 
 
    
@@ -1161,7 +1314,7 @@ cannot be found, try jakarta-regexp.
    
   
    
   
    
 
    
 
    -<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3" />
+<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/>
 
    
 
@@ -1186,7 +1339,7 @@ cannot be found, try jakarta-regexp.
    
   
    
   
    
 
    
 
    -<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1" />
+<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/>
 
    
 
@@ -1212,7 +1365,7 @@ cannot be found, try jakarta-regexp.
    
   
    
 
    
 
 
    
-
    Built in tasks
    
+
    Built-in Tasks
    
 
      
   
    • Ant
      • 
   
    • AntCall
      • 
@@ -1308,13 +1461,13 @@ allows you to parameterize your subprojects.
      
 
 
      Examples
      
 
      -  <ant antfile="subproject/subbuild.xml" dir="subproject" target="compile" />
+  <ant antfile="subproject/subbuild.xml" dir="subproject" target="compile"/>
 
-  <ant dir="subproject" />
+  <ant dir="subproject"/>
 
   <ant antfile="subproject/property_based_subbuild.xml">
-    <property name="param1" value="version 1.x" />
-    <property file="config/subproject/default.properties" />
+    <property name="param1" value="version 1.x"/>
+    <property file="config/subproject/default.properties"/>
   </ant>
 
      
 
      
@@ -1355,7 +1508,7 @@ href="#property">property for usage guidelines.
      
 
      
 
      AntStructure
      
 
      Description
       
-
      Generates a DTD for Ant build files which contains information
+
      Generates a DTD for Ant buildfiles which contains information
 about all tasks currently known to Ant.
       
 
      Note that the DTD generated by this task is incomplete, you can
 always add XML entities using #IMPLIED.
      
 
 
      Examples
      
 
      -<antstructure output="project.dtd" />
+<antstructure output="project.dtd"/>
 
      
 
      
 
      Available
      
@@ -1429,11 +1582,11 @@ execution depending on system parameters.
      
 
 
      Parameters specified as nested elements
      
 
      classpath
      
-
      Available's classpath attribute is a PATH like structure and can also be set via a nested
-classpath element.
      
+
      Available's classpath attribute is a path-like structure and can also be set via a nested
+classpath element.
      
 
      Examples
      
-
        <available classname="org.whatever.Myclass" property="Myclass.present" />
      
+
        <available classname="org.whatever.Myclass" property="Myclass.present"/>
      
 
      sets the property Myclass.present to the value "true"
 if the org.whatever.Myclass is found in Ant's classpath.
      
 
      
@@ -1509,11 +1662,11 @@ directly. More FileSets can be specified using nested
   
   
     type
-    One of file, dir or
-      both. If set to file, only the permissions of
-      plain files are going to be changed. If set to dir, only
+    One of file, dir or
+      both. If set to file, only the permissions of
+      plain files are going to be changed. If set to dir, only
       the directories are considered.
-    No, default is file
+    No, default is file
   
 
 
      Examples
      
@@ -1525,18 +1678,18 @@ directly. More FileSets can be specified using nested
 UNIX system.
      
 
      
 
      -    <chmod dir="${dist}/bin" perm="ugo+rx" includes="**/*.sh" />
+    <chmod dir="${dist}/bin" perm="ugo+rx" includes="**/*.sh"/>
 
      
 
      
 
      makes all ".sh" files below ${dist}/bin
 readable and executable for anyone on a UNIX system.
      
 
      
 
      -<chmod perm="g+w" />
+<chmod perm="g+w"/>
   <fileset dir="shared/sources1" >
-    <exclude name="**/trial/**" />
+    <exclude name="**/trial/**"/>
   </fileset>
-  <fileset refid="other.shared.sources" />
+  <fileset refid="other.shared.sources"/>
 </chmod>
 
      
 
      
@@ -1620,11 +1773,11 @@ href="#identity-mapper">identity.
      
 
      Examples
      
 
      Copy a single file
      
 
      -  <copy file="myfile.txt" tofile="mycopy.txt" />
+  <copy file="myfile.txt" tofile="mycopy.txt"/>
 
      
 
      Copy a file to a directory
      
 
      -  <copy file="myfile.txt" todir="../some/dir/tree" />
+  <copy file="myfile.txt" todir="../some/dir/tree"/>
 
      
 
      Copy a directory to another directory
      
 
      @@ -1636,12 +1789,12 @@ href="#identity-mapper">identity.
      
 
         <copy todir="../dest/dir" >
     <fileset dir="src_dir" >
-      <exclude name="**/*.java" />
+      <exclude name="**/*.java"/>
     </fileset>
   </copy>
 
   <copy todir="../dest/dir" >
-    <fileset dir="src_dir" excludes="**/*.java" />
+    <fileset dir="src_dir" excludes="**/*.java"/>
   </copy>
 
      
 
      Copy a set of files to a directory appending
@@ -1649,7 +1802,7 @@ href="#identity-mapper">identity.
      
 
         <copy todir="../backup/dir" >
     <fileset dir="src_dir" />
-    <mapper type="glob" from="*" to="*.bak" />
+    <mapper type="glob" from="*" to="*.bak"/>
   </copy>
 
      
 
      
@@ -1728,8 +1881,8 @@ supports all attributes of <fileset>
   
     flatten
     ignore directory structure of source directory,
-      copy all files into a single directory - specified by the dest
-      attribute (default is false).
+      copy all files into a single directory, specified by the dest
+      attribute (default is false).
     No
   
   
@@ -1754,7 +1907,7 @@ recursively. All java files are copied, except for files with the name Tes
 
        <copydir src="${src}/resources"
            dest="${dist}"
            includes="**/*.java"
-           excludes="mypackage/test/**" />
      
+           excludes="mypackage/test/**"/>
      
 
      copies the directory ${src}/resources to ${dist}
 recursively. All java files are copied, except for the files under the mypackage/test
 directory.
      
@@ -1875,7 +2028,7 @@ preferred over the checkout command, because of speed.
      
   />

    checks out the package/module "jakarta-tools" from the CVS repository pointed to by the cvsRoot attribute, and stores the files in "${ws.dir}".

    -
      <cvs dest="${ws.dir}" command="update" />
    +
      <cvs dest="${ws.dir}" command="update"/>

    updates the package/module that has previously been checked out into "${ws.dir}".

      <cvs command="-q diff -u -N" output="patch.txt"/>
    @@ -1888,7 +2041,7 @@ repository pointed to by the cvsRoot attribute, and stores the files in "${

    Description

    Deletes either a single file, all files in a specified directory and its sub-directories, or a set of files specified by one or more FileSets. -When specifying a set of files, empty directories are not removed.

    +When specifying a set of files, empty directories are not removed.

    Parameters

    @@ -1955,12 +2108,12 @@ When specifying a set of files, empty directories are not removed.

    Examples

    -
      <delete file="/lib/ant.jar" />
    +
      <delete file="/lib/ant.jar"/>

    deletes the file /lib/ant.jar.

    -
      <delete dir="lib" />
    +
      <delete dir="lib"/>

    deletes all files in the /lib directory.

      <delete>
-    <fileset dir="." includes="**/*.bak" />
+    <fileset dir="." includes="**/*.bak"/>
   </delete>

    deletes all files with the extension ".bak" from the current directory @@ -1985,10 +2138,10 @@ and any sub-directories.

    Examples

    -
      <deltree dir="dist" />
    +
      <deltree dir="dist"/>

    deletes the directory dist, including its files and subdirectories.

    -
      <deltree dir="${dist}" />
    +
      <deltree dir="${dist}"/>

    deletes the directory ${dist}, including its files and subdirectories.

    @@ -2016,11 +2169,11 @@ subdirectories.

    append Append to an existing file? - No - default is false. + No – default is false.

    Examples

    -
      <echo message="Hello world" />
    +
      <echo message="Hello world"/>
      
 <echo>
 This is a longer message stretching over
@@ -2085,13 +2238,13 @@ systems.
    
     newenvironment
     Do not propagate old environment when new environment
       variables are specified.
-    No, default is false
+    No, default is false
   
 
 
    Examples
    
 
    
   
    <exec dir="${src}" executable="dir" os="windows"
-  output="dir.txt" />
    
+  output="dir.txt"/>
    
 
    
 
    Parameters specified as nested elements
    
 
    arg
    
@@ -2135,13 +2288,13 @@ system command via nested <env> elements.
    
 
    Examples
    
 
     <exec executable="emacs" >
-  <env key="DISPLAY" value=":1.0" />
+  <env key="DISPLAY" value=":1.0"/>
 </exec>
 
    
 
    starts emacs on display 1 of the X Window System.
    
 
     <exec ... >
-  <env key="PATH" path="${java.library.path}:${basedir}/bin" />
+  <env key="PATH" path="${java.library.path}:${basedir}/bin"/>
 </exec>
 
    
 
    adds ${basedir}/bin to the PATH of the
@@ -2209,7 +2362,7 @@ command. At least one nested <fileset> is required.
    
     newenvironment
     Do not propagate old environment when new environment
       variables are specified.
-    No, default is false
+    No, default is false
   
   
     parallel
@@ -2220,11 +2373,11 @@ command. At least one nested <fileset> is required.
    
   
   
     type
-    One of file, dir or
-      both. If set to file, only the names of plain
-      files will be sent to the command. If set to dir, only
+    One of file, dir or
+      both. If set to file, only the names of plain
+      files will be sent to the command. If set to dir, only
       the names of directories are considered.
-    No, default is file
+    No, default is file
   
 
 
    Parameters specified as nested elements
    
@@ -2251,13 +2404,13 @@ description in the section about exec
    
 
    Examples
    
 
     <execon executable="ls" >
-  <arg value="-l" />
+  <arg value="-l"/>
   <fileset dir="/tmp">
     <patternset>
-      <exclude name="**/*.txt" />
+      <exclude name="**/*.txt"/>
     </patternset>
   </fileset>
-  <fileset refid="other.files" />
+  <fileset refid="other.files"/>
 </execon>
 
    
 
    invokes ls -l, adding the absolute filenames of all
@@ -2266,10 +2419,10 @@ files of the FileSet with id other.files to
 the command line.
    
 
     <execon executable="somecommand" parallel="false" >
-  <arg value="arg1" />
+  <arg value="arg1"/>
   <srfile/>
-  <arg value="arg2" />
-  <fileset dir="/tmp" />
+  <arg value="arg2"/>
+  <fileset dir="/tmp"/>
 </execon>
 
    
 
    invokes somecommand arg1 SOURCEFILENAME arg2 for each
@@ -2349,14 +2502,14 @@ filterfile attribute.
    
 
 
    * see notes 1 and 2 above parameters table.
    
 
    Examples
    
-
      <filter token="year" value="2000" />
+
      <filter token="year" value="2000"/>
   <copy todir="${dest.dir}">
-    <fileset dir="${src.dir}" />
+    <fileset dir="${src.dir}"/>
   </copy>
     
 
    will copy recursively all the files from the src.dir directory into
 the dest.dir directory replacing all the occurencies of the string @year@
 with 2000.
    
-
      <filter filterfile="deploy_env.properties" />
    
+
      <filter filterfile="deploy_env.properties"/>
    
 will read all property entries from the deploy_env.properties file
 and set these as filters.
 
@@ -2588,7 +2741,7 @@ You never know what editor a user will use to browse README's.
    
 
    Examples
    
 
    
   
    <genkey alias="apache-group" storepass="secret" 
-  dname="CN=Ant Group, OU=Jakarta Division, O=Apache.org, C=US" />
    
+  dname="CN=Ant Group, OU=Jakarta Division, O=Apache.org, C=US"/>
    
 
    
 
 
    
@@ -2650,7 +2803,7 @@ NB: This timestamp facility only works on downloads using the HTTP protocol.
   
 
 
    Examples
    
-
      <get src="http://jakarta.apache.org/" dest="help/index.html" />
    
+
      <get src="http://jakarta.apache.org/" dest="help/index.html"/>
    
 
    Gets the index page of http://jakarta.apache.org/, and stores it in the file help/index.html.
    
 
 
      <get src="http://jakarta.apache.org/builds/tomcat/nightly/ant.zip" 
@@ -2833,7 +2986,7 @@ include an empty one for you.)
    
   
 
 
    Examples
    
-
      <jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" />
    
+
      <jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes"/>
    
 
    jars all files in the ${build}/classes directory into a file
 called app.jar in the ${dist}/lib directory.
    
 
      <jar jarfile="${dist}/lib/app.jar"
@@ -2964,26 +3117,26 @@ of the class (either ANT's VM or the forked VM). The attributes
 for this element are the same as for environment
 variables.
    
 
    classpath
    
-
    Java's classpath attribute is a Java's classpath attribute is a PATH like structure and can also be set via a nested
-classpath element.
    
+classpath element.
    
 
    Example
    
 
      
        <java classname="test.Main" >
-         <arg value="-h" /> 
+         <arg value="-h"/> 
          <classpath>
-           <pathelement location="\test.jar" />
-           <pathelement path="${java.class.path}" />
+           <pathelement location="\test.jar"/>
+           <pathelement path="${java.class.path}"/>
          </classpath>
        </java>
 
    
 
    Examples
    
-
      <java classname="test.Main" />
    
+
      <java classname="test.Main"/>
    
 
      <java classname="test.Main"
         fork="yes" >
-    <sysproperty key="DEBUG" value="true" /> 
-    <arg value="-h" /> 
-    <jvmarg value="-Xrunhprof:cpu=samples,file=log.txt,depth=3" /> 
+    <sysproperty key="DEBUG" value="true"/> 
+    <arg value="-h"/> 
+    <jvmarg value="-Xrunhprof:cpu=samples,file=log.txt,depth=3"/> 
   </java>
 
    
 
@@ -3146,11 +3299,11 @@ supports all attributes of <fileset>
 <include>, <exclude> and
 <patternset> elements.
    
 
    src, classpath, bootclasspath and extdirs
    
-
    Javac's srcdir, classpath,
-bootclasspath and extdirs attributes are Javac's srcdir, classpath,
+bootclasspath and extdirs attributes are PATH like structure and can also be set via nested
-src, classpath, bootclasspath and
-extdirs elements respectively.
    
+src, classpath, bootclasspath and
+extdirs elements respectively.
    
 
 
    Examples
    
 
      <javac srcdir="${src}"
@@ -3189,11 +3342,11 @@ the propery src2. This can also be represented using nested element
 
      <javac destdir="${build}"
          classpath="xyz.jar"
          debug="on">
-    <src path="${src}" />
-    <src path="${src2}" />
-    <include name="mypackage/p1/**" />
-    <include name="mypackage/p2/**" />
-    <exclude name="mypackage/p1/testpackage/**" />
+    <src path="${src}"/>
+    <src path="${src2}"/>
+    <include name="mypackage/p1/**"/>
+    <include name="mypackage/p2/**"/>
+    <exclude name="mypackage/p1/testpackage/**"/>
   </javac>
    
 
 
    Note: If you are using Ant on Windows and a new DOS-Window pops up
@@ -3626,10 +3779,10 @@ of the doclet element is shown below:
 
    
 
 
    sourcepath, classpath and bootclasspath
    
-
    Javadoc's sourcepath, classpath and
-bootclasspath attributes are PATH like
-structure and can also be set via nested sourcepath,
-classpath and bootclasspath elements
+
    Javadoc's sourcepath, classpath and
+bootclasspath attributes are PATH like
+structure and can also be set via nested sourcepath,
+classpath and bootclasspath elements
 respectively.
    
 
 
    Example
    
@@ -3717,9 +3870,9 @@ necessary.
    
   
 
 
    Examples
    
-
    <mkdir dir="${dist}" />
    
+
    <mkdir dir="${dist}"/>
    
 
    creates a directory ${dist}.
    
-
    <mkdir dir="${dist}/lib" />
    
+
    <mkdir dir="${dist}/lib"/>
    
 
    creates a directory ${dist}/lib.
    
 
    
 
    Move
    
@@ -3792,11 +3945,11 @@ href="#identity-mapper">identity.
    
 
    Examples
    
 
    Move a single file (rename a file)
    
 
    -  <move file="file.orig" tofile="file.moved" />
+  <move file="file.orig" tofile="file.moved"/>
 
    
 
    Move a single file to a directory
    
 
    -  <move file="file.orig" todir="dir/to/move/to" />
+  <move file="file.orig" todir="dir/to/move/to"/>
 
    
 
    Move a directory to a new directory
    
 
    @@ -3808,8 +3961,8 @@ href="#identity-mapper">identity.
    
 
       <move todir="some/new/dir" >
     <fileset dir="my/src/dir" >
-      <include name="**/*.jar" />
-      <exclude name="**/ant.jar" />
+      <include name="**/*.jar"/>
+      <exclude name="**/ant.jar"/>
     </fileset>
   </move>
 
    
@@ -3818,9 +3971,9 @@ in a directory.
    
 
       <move todir="my/src/dir" >
     <fileset dir="my/src/dir" >
-      <exclude name="**/*.bak" />
+      <exclude name="**/*.bak"/>
     </fileset>
-    <mapper type="glob" from="*" to="*.bak" />
+    <mapper type="glob" from="*" to="*.bak"/>
   </move>
 
    
 
    
@@ -3874,10 +4027,10 @@ in a directory.
    
   
 
 
    Examples
    
-
      <patch patchfile="module.1.0-1.1.patch" />
    
+
      <patch patchfile="module.1.0-1.1.patch"/>
    
 
    applies the diff included in module.1.0-1.1.patch to the
 files in base directory guessing the filename(s) from the diff output.
-
      <patch patchfile="module.1.0-1.1.patch" strip="1" />
    
+
      <patch patchfile="module.1.0-1.1.patch" strip="1"/>
    
 
    like above but one leading directory part will be removed. i.e. if
 the diff output looked like
 
    @@ -3969,19 +4122,19 @@ This also holds for properties loaded from a property file.
    
 
 
    Parameters specified as nested elements
    
 
    classpath
    
-
    Property's classpath attribute is a Property's classpath attribute is a PATH like structure and can also be set via a nested
-classpath element.
    
+classpath element.
    
 
    Examples
    
-
      <property name="foo.dist" value="dist" />
    
+
      <property name="foo.dist" value="dist"/>
    
 
    sets the property foo.dist to the value "dist".
    
-
      <property file="foo.properties" />
    
+
      <property file="foo.properties"/>
    
 
    reads a set of properties from a file called "foo.properties".
    
-
      <property resource="foo.properties" />
    
+
      <property resource="foo.properties"/>
    
 
    reads a set of properties from a resource called "foo.properties".
    
 
    Note that you can reference a global properties file for all of your Ant
 builds using the following:
-
      <property file="${user.home}/.ant-global.properties" />
    
+
      <property file="${user.home}/.ant-global.properties"/>
    
 
    since the "user.home" property is defined by the Java virtual machine
 to be your home directory.  This technique is more appropriate for Unix than 
 Windows since the notion of a home directory doesn't exist on Windows.  On the
@@ -4017,7 +4170,7 @@ implementations may use other values for the home directory on Windows.
    
   
 
 
    Examples
    
-
      <rename src="foo.jar" dest="${name}-${version}.jar" />
     
+
      <rename src="foo.jar" dest="${name}-${version}.jar"/>
     
 
    Renames the file foo.jar to ${name}-${version}.jar (assuming name
  and version being predefined properties). If a file named ${name}-${version}.jar
  already exists, it will be removed prior to renaming foo.jar.
    
@@ -4089,7 +4242,7 @@ must use a nested <replacetoken> element.
    
   
 
 
    Examples
    
-
      <replace file="${src}/index.html" token="@@@" value="wombat" />
    
+
      <replace file="${src}/index.html" token="@@@" value="wombat"/>
    
 
    replaces occurrences of the string "@@@" with the string
 "wombat", in the file ${src}/index.html.
    
 
    Parameters specified as nested elements
    
@@ -4103,14 +4256,14 @@ them.
    
 
    Examples
    
 
      
 <replace dir="${src}" value="wombat">
-  <include name="**/*.html" />
+  <include name="**/*.html"/>
   <replacetoken><![CDATA[multi line
 token]]></replacetoken>
 </replace>
 
    
 
    replaces occurrences of the string "multi
-line\ntoken" with the string "wombat", in all
-HTML files in the directory ${src}.Where \n is
+line\ntoken" with the string "wombat", in all
+HTML files in the directory ${src}.Where \n is
 the platform specific line separator.
    
 
      
 <replace file="${src}/index.html">
@@ -4245,14 +4398,14 @@ supports all attributes of <fileset>
 
 
    Parameters specified as nested elements
    
 
    classpath
    
-
    Rmic's classpath attribute is a Rmic's classpath attribute is a PATH like structure and can also be set via a nested
-classpath elements.
    
+classpath elements.
    
 
    Examples
    
-
      <rmic classname="com.xyz.FooBar" base="${build}/classes" />
    
+
      <rmic classname="com.xyz.FooBar" base="${build}/classes"/>
    
 
    runs the rmic compiler for the class com.xyz.FooBar. The
 compiled files will be stored in the directory ${build}/classes.
    
-
      <rmic base="${build}/classes" includes="**/Remote*.class" />
    
+
      <rmic base="${build}/classes" includes="**/Remote*.class"/>
    
 
    runs the rmic compiler for all classes with .class
 files below ${build}/classes whose classname starts with
 Remote. The compiled files will be stored in the directory
@@ -4330,7 +4483,7 @@ block
 
    Examples
    
 
    
   
    <signjar jar="${dist}/lib/ant.jar"
-alias="apache-group" storepass="secret" />
    
+alias="apache-group" storepass="secret"/>
    
 
    
 
    signs the ant.jar with alias "apache-group" accessing the
 keystore and private key via "secret" password.
    
@@ -4544,8 +4697,8 @@ task to come up with a .tar.gz package.
    
   
 
 
    Examples
    
-
      <tar tarfile="${dist}/manual.tar" basedir="htdocs/manual" />
-  <gzip zipfile="${dist}/manual.tar.gz" src="${dist}/manual.tar" />
    
+
      <tar tarfile="${dist}/manual.tar" basedir="htdocs/manual"/>
+  <gzip zipfile="${dist}/manual.tar.gz" src="${dist}/manual.tar"/>
    
 
    tars all files in the htdocs/manual directory into a file called manual.tar
 in the ${dist}  directory, then applies the gzip task to compress
 it.
    
@@ -4590,11 +4743,11 @@ href="#writingowntask">Writing your own task".
    
 
 
    Parameters specified as nested elements
    
 
    classpath
    
-
    Taskdef's classpath attribute is a Taskdef's classpath attribute is a PATH like structure and can also be set via a nested
-classpath element.
    
+classpath element.
    
 
    Examples
    
-
      <taskdef name="myjavadoc" classname="com.mydomain.JavadocTask" />
    
+
      <taskdef name="myjavadoc" classname="com.mydomain.JavadocTask"/>
    
 
    makes a task called myjavadoc available to Ant. The class com.mydomain.JavadocTask
 implements the task.
    
 
    
@@ -4632,10 +4785,10 @@ of now works, all other cases will emit a warning.
    
 
    If both millis and datetime are omitted
 the current time is assumed.
    
 
    Examples
    
-
      <touch file="myfile" />
    
+
      <touch file="myfile"/>
    
 
    creates myfile if it doesn't exist and changes the
 modification time to the current time.
    
-
      <touch file="myfile" datetime="06/28/2000 2:02 pm" />
    
+
      <touch file="myfile" datetime="06/28/2000 2:02 pm"/>
    
 
    creates myfile if it doesn't exist and changes the
 modification time to Jun, 28 2000 2:02 pm (14:02 for those used to 24
 hour times).
    
@@ -4707,11 +4860,11 @@ one mapper element are required.
    
   
   
     type
-    One of file, dir or
-      both. If set to file, only the names of plain
-      files will be sent to the command. If set to dir, only
+    One of file, dir or
+      both. If set to file, only the names of plain
+      files will be sent to the command. If set to dir, only
       the names of directories are considered.
-    No, default is file
+    No, default is file
   
 
 
    Parameters specified as nested elements
    
@@ -4743,12 +4896,12 @@ description in the section about exec
    
 
    Examples
    
 
     <transform executable="cc" dest="src/C" parallel="false">
-  <arg value="-c" />
-  <arg value="-o" />
+  <arg value="-c"/>
+  <arg value="-o"/>
   <targetfile/>
   <srcfile/>
-  <fileset dir="src/C" includes="*.c" />
-  <mapper type="glob" from="*.c" to="*.o" />
+  <fileset dir="src/C" includes="*.c"/>
+  <mapper type="glob" from="*.c" to="*.o"/>
 </transform>
 
    
 
    invokes cc -c -o TARGETFILE SOURCEFILE for each
@@ -4853,14 +5006,14 @@ execution depending on the relative age of the specified files.
    
 
 
    Examples
    
 
      <uptodate property="xmlBuild.notRequired" targetfile="${deploy}\xmlClasses.jar" >
-    <srcfiles dir= "${src}/xml" includes="**/*.dtd" />
+    <srcfiles dir= "${src}/xml" includes="**/*.dtd"/>
   </uptodate>
    
 
    sets the property xmlBuild.notRequired to the value "true"
 if the ${deploy}/xmlClasses.jar is more up to date than any of the DTD files in the ${src}/xml directory.
    
 
    This can be written as
 
      <uptodate property="xmlBuild.notRequired"  >
-    <srcfiles dir= "${src}/xml" includes="**/*.dtd" />
-    <mapper type="merge" to="${deploy}\xmlClasses.jar" />
+    <srcfiles dir= "${src}/xml" includes="**/*.dtd"/>
+    <mapper type="merge" to="${deploy}\xmlClasses.jar"/>
   </uptodate>
    
 
    as well.
    
 
    
@@ -5033,12 +5186,12 @@ src/graphics/images/gifs/large/logo.gif
 then the war file myapp.war created with
 
     <war warfile="myapp.war" webxml="src/metadata/myapp.xml">
-  <fileset dir="src/html/myapp" />
-  <fileset dir="src/jsp/myapp" />
+  <fileset dir="src/html/myapp"/>
+  <fileset dir="src/jsp/myapp"/>
   <lib dir="thirdparty/libs">
-    <exclude name="jdbc1.jar" />
+    <exclude name="jdbc1.jar"/>
   </lib>
-  <classes dir="build/main" />
+  <classes dir="build/main"/>
   <prefixedfileset dir="src/graphics/images/gifs" 
                    prefix="images"/>
 </war>
@@ -5078,12 +5231,12 @@ supports all attributes of <fileset>
 <include>, <exclude> and
 <patternset> elements.
    
 
    Or, you may place within it nested file sets, or references to file sets.
-In this case basedir is optional; the implicit file set is only used
+In this case basedir is optional; the implicit file set is only used
 if basedir is set. You may use any mixture of the implicit file set
 (with basedir set, and optional attributes like includes
 and optional subelements like <include>); explicit nested
 <fileset> elements so long as at least one fileset total is specified. The ZIP file will
-only reflect the relative paths of files within each fileset.
    
+only reflect the relative paths of files within each fileset.
    
 
    <zip> elements may contain both regular <fileset> elements
 and also <prefixedfileset> elements.  A <prefixedfileset> is an extended form of a fileset,
 which may include one of two special attributes: 
@@ -5208,6 +5361,7 @@ current directory as docs/ChangeLog.txt. For example, the archive m
   
  • PropertyFile
    • 
   
  • RenameExtensions
    • 
   
  • Script
    • 
+  
  • Sound
    • 
   
  • Telnet
    • 
   
  • VssGet
    • 
 
@@ -5429,7 +5583,7 @@ write patterns.
    
   <ftp server="ftp.apache.org"
        userid="anonymous"
        password="me@myorg.com">
-    <fileset dir="htdocs/manual" />
+    <fileset dir="htdocs/manual"/>
   </ftp>
 
    
 
    Logs in to ftp.apache.org as anonymous and 
@@ -5441,7 +5595,7 @@ to the default directory for that user.
    
        password="me@myorg.com"
        depends="yes"
   >
-    <fileset dir="htdocs/manual" />
+    <fileset dir="htdocs/manual"/>
   </ftp>
    
 
    Logs in to ftp.apache.org as anonymous and 
 uploads all new or changed files in the htdocs/manual directory 
@@ -5456,7 +5610,7 @@ for anonymous.
    
        binary="no"
   >
     <fileset dir="htdocs/manual">
-      <include name="**/*.html" />
+      <include name="**/*.html"/>
     </fileset>
   </ftp>
    
 
    Logs in to ftp.apache.org at port 2121 as 
@@ -5472,7 +5626,7 @@ changed HTML files in the htdocs/manual directory to the
 
       >
     <fileset dir="htdocs/manual">
-      <include name="**/*.html" />
+      <include name="**/*.html"/>
     </fileset>
   </ftp>
    Logs in to the Windows-based ftp.nt.org as 
 coder with password java1 and uploads all 
@@ -5491,7 +5645,7 @@ into.  The file structure from the FTP site is preserved on the local machine.
@@ -5509,7 +5663,7 @@ fact, the dir attribute of the fileset is ignored completely.
        userid="anonymous"
        password="me@myorg.com" >
     <fileset>
-      <include name="**/*.tmp" />
+      <include name="**/*.tmp"/>
     </fileset>
   </ftp>
 
    
@@ -5524,7 +5678,7 @@ If you don't have permission to delete a file, a BuildException is thrown.
    
        password="me@myorg.com" 
        listing="data/ftp.listing" >
     <fileset>
-      <include name="**" />
+      <include name="**"/>
     </fileset>
   </ftp>
 
    
@@ -5790,7 +5944,7 @@ supports all attributes of <fileset>
            classpath="/source/project2/proj.jar"
            comments="true"
            crossref="false" replace="true"
-           keep="true" />
+           keep="true"/>
   
    
 
    
 
    
@@ -5881,7 +6035,7 @@ supports all attributes of <fileset>
               excludes="**/samples/*"
               fromExtension=".java.keep"
               toExtension=".java"
-              replace="true" />
+              replace="true"/>
    @@ -5932,7 +6086,7 @@ accessible from the script, using either their name or </target> - <target name="main" depends="setup" /> + <target name="main" depends="setup"/> </project> @@ -5959,7 +6113,7 @@ and two different scripting languages:

     <project name="testscript" default="main">
   <target name="sub">
-    <echo id="theEcho" />
+    <echo id="theEcho"/>
   </target>
 
   <target name="sub1">
@@ -5976,7 +6130,7 @@ and two different scripting languages:
    
     ]]></script>
   </target>
 
-  <target name="main" depends="sub1,sub2" />
+  <target name="main" depends="sub1,sub2"/>
 </project>

    generates

    @@ -5991,6 +6145,87 @@ main: BUILD SUCCESSFUL + +
    +

    Sound

    +

    Description

    +

    Plays a sound-file at the end of the build, according to whether +the build failed or succeeded. You can specify either a specific +sound-file to play, or, if a directory is specified, the +<sound> task will randomly select a file to play. +Note: At this point, the random selection is based on all the files +in the directory, not just those ending in appropriate suffixes +for sound-files, so be sure you only have sound-files in the +directory you specify. + +

    Parameters

    + + + + + + + + + + + + + + + + +
    AttributeDescriptionRequired
    loopsthe number of extra times to play the sound-file; + default is 0. + No
    durationthe amount of time (in milliseconds) to play + the sound-file. + No
    +

    +To specify the sound-files or the sound-file directories, use the +nested <success> and <fail> +elements: +

    +
    +<success>     the path to a sound-file directory, or the name of a
+              specific sound-file, to be played if the build succeeded.
+<fail>        the path to a sound-file directory, or the name of a
+              specific sound-file, to be played if the build succeeded.
+
    +
    + +

    Examples

    +
    +
    +<target name="fun" if="fun" unless="fun.done">
+  <sound loops="2">
+    <success source="${user.home}/sounds/bell.wav"/>
+    <fail source="${user.home}/sounds/ohno.wav"/>
+  </sound>
+  <property name="fun.done" value="true"/>
+</target>
+
    +
    +plays the bell.wav sound-file if the build succeeded, or +the ohno.wav sound-file if the build failed, three times, +if the fun property is set to true. +If the target +is a dependency of an "initialization" target that other +targets depend on, the +fun.done property prevents the target from being executed +more than once. +
    +
    +<target name="fun" if="fun" unless="fun.done">
+  <sound>
+    <success source="//intranet/sounds/success"/>
+    <fail source="//intranet/sounds/failure"/>
+  </sound>
+  <property name="fun.done" value="true"/>
+</target>
+
    +
    +randomly selects a sound-file to play when the build succeeds or fails. +

    Telnet

    Description

    @@ -6156,7 +6391,7 @@ which are labeled Release1 and write them to the local directory

    Build Events

    Ant is capable of generating build events as it performs the tasks necessary to build a project. -Listeners can be attached to ant to receive these events. This capability could be used, for example, +Listeners can be attached to Ant to receive these events. This capability could be used, for example, to connect Ant to a GUI or to integrate Ant with an IDE.

    To use build events you need to create an ant Project object. You can then call the @@ -6173,61 +6408,84 @@ for the following events

  • Message logged -If you wish to attach a listener from the command line you may use the -listener option. For example +If you wish to attach a listener from the command line you may use the +-listener option. For example: 
    ant -listener org.apache.tools.ant.XmlLogger
    -will run ant with a listener which generates an XML representation of the build progress. This -listener is included with ant as is the default listener which generates the logging to standard -output. - +will run Ant with a listener that generates an XML representation of the build progress. This +listener is included with Ant, as is the default listener, which generates the logging to standard output.
    -

    Writing your own task

    +

    Writing Your Own Task

    It is very easy to write your own task:

    1. Create a Java class that extends org.apache.tools.ant.Task.
      2. -
    2. For each attribute, write a setter method. The setter method must be a +
    3. For each attribute, write a setter method. The setter method must be a public void method that takes a single argument. The - name of the method must begin with "set", followed by the - attribute name, with the first character in uppercase, and the rest in - lowercase. The type of the attribute can be String, any - primitive type (they are converted for you from their String-representation - in the build-file. If you specify a boolean your method will be passed the value - true if the value specified in the build-file is one of "true", - "yes" or "on"), Class, File - (in which case the value of the attribute is interpreted relative to the - project's basedir) or any other type that has a constructor with a single - String argument
      4. -
    4. If your task has enumerated attributes, you should consider using - a subclass of org.apache.tools.ant.types.EnumeratedAttribute as argument - to your setter method. See org.apache.tools.ant.taskdefs.FixCRLF for - an example.
      5. -
    5. If the task should support character data, write a public void - addText(String) method.
      6. -
    6. For each nested element, write a create or add method. A create method - must be a public method that takes no arguments and returns - an Object type. The name of the create method must begin with - "create", followed by the element name. An add method must be - a public void method that takes a single argument of an - Object type with a no argument constructor. The name of the add method - must begin with "add", followed by the element name. -
    7. Write a public void execute method, with no arguments, that - throws a BuildException. This method implements the task - itself.
      8. + name of the method must begin with set, followed by the + attribute name, with the first character of the name in uppercase, and the rest in + lowercase. The type of the attribute can be: +
        +
      • +String +
        • +
      • +any primitive type (they are converted for you from their String-representation +in the buildfile) +
        • +
      • +boolean – your method will be passed the value +true if the value specified in the buildfile is one of true, +yes, or on) +
        • +
      • +Class +
      • +File +(in which case the value of the attribute is interpreted relative to the +project's basedir) +
        • +
      • +any other type that has a constructor with a single +String argument +
        • +
      +
    8. If your task has enumerated attributes, you should consider using +a subclass of org.apache.tools.ant.types.EnumeratedAttribute +as an argument +to your setter method. See +org/apache/tools/ant/taskdefs/FixCRLF.java for +an example.
      9. +
    9. If the task should support character data, write a public void +addText(String) method.
      10. +
    10. For each nested element, write a create or add method. +A create method +must be a public method that takes no arguments and returns +an Object type. The name of the create method must begin with +create, followed by the element name. An add method must be +a public void method that takes a single argument of an +Object type with a no-argument constructor. +The name of the add method +must begin with add, followed by the element name. +
    11. Write a public void execute method, with no arguments, that +throws a BuildException. This method implements the task +itself.
    -

    The life cycle of a task

    + +

    The Life-cycle of a Task

      -
    1. The task gets instantiated using a no-arg constructor at parser +
    2. The task gets instantiated using a no-argument constructor, at parser time. This means even tasks that are never executed get instantiated.
      3. -
    3. The tasks gets references to its project and location inside the - build file via their inherited project and +
    4. The task gets references to its project and location inside the + buildfile via its inherited project and location variables.
      5. -
    5. If the user specified an id attribute to this task, the project - registers a reference to this newly created task - at parser +
    6. If the user specified an id attribute to this task, + the project + registers a reference to this newly created task, at parser time.
    7. The task gets a reference to the target it belongs to via its @@ -6238,30 +6496,35 @@ output.
    8. All child elements of the XML element corresponding to this task are created via this task's createXXX() methods or instantiated and added to this task via its addXXX() - methods - at parser time.
      9. + methods, at parser time.
    9. All attributes of this task get set via their corresponding - setXXX methods - at runtime.
      10. + setXXX methods, at runtime.
    10. The content character data sections inside the XML element corresponding to this task is added to the task via its - addText method - at runtime.
      11. + addText method, at runtime.
    11. All attributes of all child elements get set via their corresponding - setXXX methods - at runtime.
      12. + setXXX methods, at runtime.
    12. execute() is called at runtime. While the above initialization steps only occur once, the execute() method may be called more than once, if the task is invoked more than once. For example, - if target1 and target2 both depend on target3, then running - "ant target1 target2" will run all tasks in target3 twice.
      13. - + if target1 and target2 both depend + on target3, then running + 'ant target1 target2' will run all tasks in + target3 twice.
    +

    Example

    -

    Let's write our own task, that prints a message on the System.out stream. The -task has one attribute called "message".

    +

    Let's write our own task, which prints a message on the +System.out stream. +The +task has one attribute, called message.

    - 
    package com.mydomain;
+
    +package com.mydomain;
 
 import org.apache.tools.ant.BuildException;
 import org.apache.tools.ant.Task;
@@ -6278,41 +6541,47 @@ public class MyVeryOwnTask extends Task {
   public void setMessage(String msg) {
     this.msg = msg;
   }
-}
    
+}
+
    -

    It's really this simple;-)

    +

    It's really this simple ;-)

    Adding your task to the system is rather simple too:

    1. Make sure the class that implements your task is in the classpath when starting Ant.
      2. -
    2. Add a taskdef element to your project. This actually adds - your task to the system.
      3. +
    3. Add a <taskdef> element to your project. + This actually adds your task to the system.
    4. Use your task in the rest of the buildfile.
    +

    Example

    - 
    <?xml version="1.0"?>
+
    +<?xml version="1.0"?>
 
 <project name="OwnTaskExample" default="main" basedir=".">
   <taskdef name="mytask" classname="com.mydomain.MyVeryOwnTask"/>
 
   <target name="main">
-    <mytask message="Hello World! MyVeryOwnTask works!" />
+    <mytask message="Hello World! MyVeryOwnTask works!"/>
   </target>
 </project>

    Another way to add a task (more permanently), is to add the task name and -implementing class name to the default.properties file in the org.apache.tools.ant.taskdefs -package. Then you can use it as if it were a built in task.

    +implementing class name to the default.properties file in the +org.apache.tools.ant.taskdefs +package. Then you can use it as if it were a built-in task.

    +
    -

    FAQ, DTD, external resources

    -

    There is an online FAQ for Ant at FAQ, DTD, External Resources +

    There is an on-line FAQ for Ant at jakarta.apache.org. This FAQ is interactive, which means you can ask and answer questions -online.

    -

    One of the questions poping up quite often is "Is there a DTD for -buildfiles?". Please refer to the FAQ for an answer.

    +on line.

    +

    One of the questions popping up quite often is "Is there a DTD for +buildfiles?" Please refer to the FAQ for an answer.

    +

    Feedback

    To provide feedback on this software, please subscribe to the Ant User @@ -6322,15 +6591,14 @@ development, join the Ant Development Mail List (ant-dev-subscribe@jakarta.apache.org)

    Archives of both lists can be found at http://archive.covalent.net/. Many -thanks to Covalent Technologies. Another archive can be found at http://marc.theaimsgroup.com. If -you know of any additional archive sites, please report to the +you know of any additional archive sites, please report them to the lists.

    -

    Copyright © 2000 Apache Software Foundation. All rights +

    Copyright © 2000,2001 Apache Software Foundation. All rights Reserved.

    -