wangwei
/
antliscence
forked from youys/ant

<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Ant</title>
</head>

<body>

<h1>Ant User Manual</h1>
<p>by</p>
<!-- Names are in alphabetical order, on last name -->
<ul>
  <li>Jacques Bergeron (<a href="mailto:jacques.bergeron@dogico.com">jacques.bergeron@dogico.com</a>)</li>
  <li>Stefan Bodewig (<a href="mailto:stefan.bodewig@megabit.net">stefan.bodewig@megabit.net</a>)</li>
  <li>Patrick Chanezon (<a href="mailto:chanezon@netscape.com">chanezon@netscape.com</a>)</li>
  <li>James Duncan Davison (<a href="mailto:duncan@x180.com">duncan@x180.com</a>)</li>
  <li>Tom Dimock (<a href="mailto:tad1@cornell.edu">tad1@cornell.edu</a>)</li>
  <li>Bill Kelly (<a href="mailto:bill.kelly@softwired-inc.com">bill.kelly@softwired-inc.com</a>)</li>
  <li>Arnout J. Kuiper (<a href="mailto:ajkuiper@wxs.nl">ajkuiper@wxs.nl</a>)</li>
  <li>Conor MacNeill (<a href="mailto:conor@cortexebusiness.com.au">conor@cortexebusiness.com.au</a>)</li>
  <li>Stefano Mazzocchi (<a href="mailto:stefano@apache.org">stefano@apache.org</a>)</li>
  <li>Sam Ruby (<a href="mailto:rubys@us.ibm.com">rubys@us.ibm.com</a>)</li>
</ul>

<p>Version 1.0.8.1 - 2000/06/28</p>

<hr>
<h2>Table of Contents</h2>
<ul>
  <li><a href="#introduction">Introduction</a></li>
  <li><a href="#getting">Getting Ant</a></li>
  <li><a href="#sysrequirements">System Requirements</a></li>
  <li><a href="#buildingant">Building Ant</a></li>
  <li><a href="#installing">Installing Ant</a></li>
  <li><a href="#running">Running Ant</a></li>
  <li><a href="#buildfile">Writing a simple buildfile</a>
  <li><a href="#directorybasedtasks">Directory based tasks</a></li>
  <li><a href="#tasks">Built in Tasks</a>
  <li><a href="#optionaltasks">Optional Tasks</a>
  <li><a href="#buildevents">Build Events</a>
  <li><a href="#writingowntask">Writing your own task</a></li>
  <li><a href="#license">License</a></li>
  <li><a href="#feedback">Feedback</a></li>
</ul>

<hr>
<h2><a name="introduction">Introduction</a></h2>
<p>Ant is a Java based build tool. In theory it is kind of like make without
make's wrinkles.</p>
<h3>Why?</h3>
<p>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
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.</p>
<p>Makefiles are inherently evil as well. Anybody who has worked on them for any
time has run into the dreaded tab problem. &quot;Is my command not executing
because I have a space in front of my tab!!!&quot; 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.</p>
<p>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
Task interface.</p>
<p>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
on.</p>

<hr>
<h2><a name="getting">Getting Ant</a></h2>
<h3>Binary edition</h3>
<p>The latest stable version of Ant can be downloaded from <a
href="http://jakarta.apache.org/builds/tomcat/release/v3.0/ant.zip">http://jakarta.apache.org/builds/tomcat/release/v3.0/ant.zip</a>.
If you like living on the edge, you can download the latest version from <a
href="http://jakarta.apache.org/builds/tomcat/nightly/ant.zip">http://jakarta.apache.org/builds/tomcat/nightly/ant.zip</a>.</p>
<h3>Source edition</h3>
<p>If you prefer the source edition, you can download Ant from <a
href="http://jakarta.apache.org/builds/tomcat/release/v3.0/src/jakarta-tools.src.zip">http://jakarta.apache.org/builds/tomcat/release/v3.0/src/jakarta-tools.src.zip</a>
(latest stable) or from <a
href="http://jakarta.apache.org/from-cvs/jakarta-tools/">http://jakarta.apache.org/from-cvs/jakarta-ant/</a>
(current). See the section <a href="#buildingant">Building Ant</a> on how to
build Ant from the source code.</p>

<hr>
<h2><a name="sysrequirements">System Requirements</a></h2>
<p>
  To build and use ant you must have a JAXP compilant XML parser installed and available on your classpath.
  <p>
  If you do not have a JAXP compliant XML parse installed, you may use the reference implementation 
  available from Sun. It is available from <a href="http://java.sun.com/xml">http://java.sun.com/xml</a>.
  Once installed make sure the "jaxp.jar" and "parser.jar" files are in your classpath.
  <p>
  You will also need the JDK installed on your system, version 1.1 or later. 

<hr>  
<h2><a name="buildingant">Building Ant</a></h2>
<p>Go to the directory <code>jakarta-ant</code>.</p>
<p>Make sure the JDK is in you path.</p>
<p>Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX)
to build a bootstrap version of Ant.</p>
<p>When finished, use</p>
<blockquote>
  <p><code>build.bat -Dant.dist.dir=&lt;directory to install Ant&gt; dist</code></p>
</blockquote>
<p>for Windows, and</p>
<blockquote>
  <p><code>build.sh -Dant.dist.dir=&lt;directory to install Ant&gt; dist</code></p>
</blockquote>
<p>for UNIX, to create a binary distribution of Ant. This distribution can be
found in the directory you specified.</p>
<hr>
<h2><a name="installing">Installing Ant</a></h2>
<p>The binary distribution of Ant consists of three directories: <code>bin</code>,
<code>docs</code> and <code>lib</code>. Only the <code>bin</code> and <code>lib</code>
directory are crucial for running Ant. To run Ant, the following must be done:</p>
<ul>
  <li>Add the <code>bin</code> directory to your path.</li>
  <li>Set the ANT_HOME environment variable. This should be set to the directory
    which contains the <code>bin</code> and <code>lib</code> directory.</li>
  <li>Set the JAVA_HOME environment variable. This should be set to the
    directory where the JDK is installed.</li>
</ul>
<h3>Windows</h3>
<p>Assume Ant is installed in <code>c:\ant\</code>. The following sets up the
environment:</p>
<pre>set ANT_HOME=c:\ant
set JAVA_HOME=c:\jdk1.2.2
set PATH=%PATH%;%ANT_HOME%\bin</pre>
<h3>Unix (bash)</h3>
<p>Assume Ant is installed in <code>/usr/local/ant</code>. The following sets up
the environment:</p>
<pre>export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/local/jdk-1.2.2
export PATH=${PATH}:${ANT_HOME}/bin</pre>
<h3>Advanced</h3>
<p>There are lots of variants that can be used to run Ant. What you need is at
least the following:</p>
<p>The classpath for Ant must contain <code>ant.jar</code> and any jars/classes 
needed for your chosen JAXP compliant XML parser.</p>
<p>When you need JDK functionality (like a <a href="#javac">javac</a> task, or a
<a href="#rmic">rmic</a> task), then for JDK 1.1, the <code>classes.zip</code>
file of the JDK must be added to the classpath; for JDK 1.2, <code>tools.jar</code>
must be added. The scripts supplied with ant, in the bin directory, will add 
<code>tools.jar</code> automatically if the JAVA_HOME environment variable is set.</p>
<p>When you are executing platform specific applications (like the <a
href="#exec">exec</a> task, or the <a href="#cvs">cvs</a> task), the property <code>ant.home</code>
must be set to the directory containing a bin directory, which contains the <code>antRun</code> shell script necessary to run execs on Unix.</p>
<hr>
<h2><a name="running">Running Ant</a></h2>
<p>Running Ant is simple, when you installed it as described in the previous
section. Just type <code>ant</code>.</p>
<p>When nothing is specified, Ant looks for a <code>build.xml</code> file in the
current directory. When found, it uses that file as a buildfile. To make Ant use
another buildfile, use the commandline option <i>-buildfile &lt;file&gt;</i>,
where <i>&lt;file&gt;</i> is the buildfile you want to use.</p>
<p>You can also set properties which override properties specified in the
buildfile (see the <a href="#property">property task</a>). 
This can be done with the <i>-D&lt;property&gt;=&lt;value&gt;</i>
option, where <i>&lt;property&gt;</i> is the name of the property and <i>&lt;value&gt;</i>
the value.</p>
<p>To more options are <i>-quiet</i> which instructs Ant to print less
information on the console when running. The option <i>-verbose</i> on the other
hand makes Ant print more information on the console.</p>
<p>It is also possible to specify the target that should be executed. Default
the target that is mentioned in the <i>default</i> attribute of the project is
used. This can be overridden by adding the target name to the end of the
commandline.</p>
<p>Commandline option summary:</p>
<pre>ant [options] [target]
Options:
-help                  print this message
-version               print the version information and exit
-quiet                 be extra quiet
-verbose               be extra verbose
-logfile &lt;file&gt;        use given file for log
-listener &lt;classname&gt;  add an instance of class as a project listener
-buildfile &lt;file&gt;      use given buildfile
-D&lt;property&gt;=&lt;value&gt;   use value for given property</pre>
<h3>Examples</h3>
<blockquote>
  <pre>ant</pre>
</blockquote>
<p>runs Ant using the <code>build.xml</code> file in the current directory, on
the default target.</p>
<blockquote>
  <pre>ant -buildfile test.xml</pre>
</blockquote>
<p>runs Ant using the <code>test.xml</code> file in the current directory, on
the default target.</p>
<blockquote>
  <pre>ant -buildfile test.xml dist</pre>
</blockquote>
<p>runs Ant using the <code>test.xml</code> file in the current directory, on a
target called <code>dist</code>.</p>
<blockquote>
  <pre>ant -buildfile test.xml -Dbuild=build/classes dist</pre>
</blockquote>
<p>runs Ant using the <code>test.xml</code> file in the current directory, on a
target called <code>dist</code>. It also sets the <i>build</i> property to the
value <i>build/classes</i>.</p>
<h3>Running Ant by hand</h3>
<p>When you have installed Ant in the do-it-yourself way, Ant can be started
with:</p>
<blockquote>
  <pre>java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre>
</blockquote>

<p>These instructions actually do exactly the same as the <code>ant</code>
command. The options and target are the same as when running Ant with the <code>ant</code>
command. This example assumes you have set up your classpath to include
<ul>
<li>ant.jar
<li>jars/classes for your XML parser
<li>the JDK's tools.jar
</ul>
<hr>
<h2><a name="buildfile">Writing a simple buildfile</a></h2>
<p>The buildfile is written in XML. Each buildfile contains one project.</p>
<h3>Projects</h3>
<p>A project has three attributes:</p>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">name</td>
    <td valign="top">the name of the project.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">default</td>
    <td valign="top">the default target to use when no target is supplied.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">basedir</td>
    <td valign="top">the base directory from which all path calculations are
      done. This attribute might be overridden by setting the &quot;basedir&quot;
      property on forehand. When this is done, it might be ommitted in the
      project tag.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
</table>
<p>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.</p>
<h3>Targets</h3>
<p>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.</p>
<p>Ant tries to execute the targets in the <i>depends</i> 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:</p>
<blockquote>
<pre>&lt;target name=&quot;A&quot;/&gt;
&lt;target name=&quot;B&quot; depends=&quot;A&quot;/&gt;
&lt;target name=&quot;C&quot; depends=&quot;B&quot;/&gt;
&lt;target name=&quot;D&quot; depends=&quot;C,B,A&quot;/&gt;</pre>
</blockquote>
<p>Suppose we want to execute target D. From its <i>depends</i> 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.</p>
<p>A target gets executed only once. Even when more targets depend on it (see
the previous example).</p>
<p>A target has also the ability to perform its execution if 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 <i>sense</i> this property you should add the <i>if</i> attribute
with the name of the property that the target should react to, for example</p>
<blockquote>
  <pre>&lt;target name=&quot;build-module-A&quot; if=&quot;module-A-present&quot;/&gt;</pre>
</blockquote>
<p>If no <i>if</i> attribute is present, the target will always be executed.</p>
<p>It is a good practice to place your <a href="#property">property</a> and <a
href="#tstamp">tstamp</a> tasks in a so called initialization target, on which
all other targets depend. Make sure that 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".</p>
<p>A target has the following attributes:</p>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">name</td>
    <td valign="top">the name of the project.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">depends</td>
    <td valign="top">a comma separated list of names of targets on which this
      target depends.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">if</td>
    <td valign="top">the name of the property that must be set in order for this
      target to execute.</td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Tasks</h3>
<p>A task is a piece of code that can be executed.</p>
<p>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.</p>
<p>Tasks have a common structure:</p>
<blockquote>
  <pre>&lt;name attribute1=&quot;value1&quot; attribute2=&quot;value2&quot; ... /&gt;</pre>
</blockquote>
<p>where name is the name of the task, attribute-x the attribute name, and
value-x the value of this attribute.</p>
<p>There is a set of <a href="#tasks">built in tasks</a>, but it is also very
easy to <a href="#writingowntask">write your own</a>.</p>
<h3>Properties</h3>
<p>A project can have a set of properties. These might be set in the buildfile
by the <a href="#property">property task</a>, or might be set outside Ant. A
property has a name and a value. Properties might be used in in the value of
task attributes. This is done by placing the property name between
&quot;${&quot; and &quot;}&quot; in the attribute value.</p>
<p>If there is a property called &quot;builddir&quot; with the value
&quot;build&quot;, then this could be used in an attribute like this: &quot;${builddir}/classes&quot;.
This is resolved as &quot;build/classes&quot;.</p>
<h3>Token Filters</h3>
<p>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 <a href="#filter">filter task</a>.&nbsp;</p>
<p>Since this can be a very harmful behavior, the tokens in the files <b>must</b>
be of the form<i> @token@</i> where <i>token</i> 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.</p>
<p>Note: in case a token with the format @token@ if 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.</p>
<h3>Examples</h3>
<blockquote>
  <pre>&lt;project name=&quot;foo&quot; default=&quot;dist&quot; basedir=&quot;.&quot;&gt;
  &lt;target name=&quot;init&quot;&gt;
    &lt;tstamp/&gt;
    &lt;property name=&quot;build&quot; value=&quot;build&quot; /&gt;
    &lt;property name=&quot;dist&quot;  value=&quot;dist&quot; /&gt;
    &lt;filter token=&quot;version&quot; value=&quot;1.0.3&quot; /&gt;
    &lt;filter token=&quot;year&quot; value=&quot;2000&quot; /&gt;
  &lt;/target&gt;

  &lt;target name=&quot;prepare&quot; depends=&quot;init&quot;&gt;
    &lt;mkdir dir=&quot;${build}&quot; /&gt;
  &lt;/target&gt;

  &lt;target name=&quot;compile&quot; depends=&quot;prepare&quot;&gt;
    &lt;javac srcdir=&quot;${src}&quot; destdir=&quot;${build}&quot; filtering=&quot;on&quot;/&gt;
  &lt;/target&gt;

  &lt;target name=&quot;dist&quot; depends=&quot;compile&quot;&gt;
    &lt;mkdir dir=&quot;${dist}/lib&quot; /&gt;
    &lt;jar jarfile=&quot;${dist}/lib/foo${DSTAMP}.jar&quot;
     basedir=&quot;${build}&quot; items=&quot;com&quot;/&gt;
  &lt;/target&gt;

  &lt;target name=&quot;clean&quot; depends=&quot;init&quot;&gt;
    &lt;deltree dir=&quot;${build}&quot; /&gt;
    &lt;deltree dir=&quot;${dist}&quot; /&gt;
  &lt;/target&gt;
&lt;/project&gt;
</pre>
</blockquote>

<hr>
<h2><a name="directorybasedtasks">Directory based tasks</a></h2>
<p>Some tasks use directory trees for the task they perform. For instance, the <a
href="#javac">Javac task</a> 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.</p>
<p>Ant gives you two ways to create a subset, both of which can be used at the same
time:</p>
<ul>
  <li>Only include files/directories that match at least one pattern of a set of
    patterns</li>
  <li>Exclude files/directories that match at least one pattern a set of
    patterns</li>
</ul>
<p>When both inclusion and exclusion are used, only files/directories that match
the include patterns, and don't match the exclude patterns are used.</p>
<p>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 
patterns.</p>
<h3>Patterns</h3>
<p>As described earlier, patterns are used for the inclusion and exclusion.
These patterns look very much like the patterns used in DOS and UNIX:</p>
<p>'*' matches zero or more characters, '?' matches one character.</p>
<p>Examples:</p>
<p>'*.java' matches '.java', 'x.java' and 'FooBar.java', but not 'FooBar.xml'
(does not end with '.java').</p>
<p>'?.java' matches 'x.java', 'A.java', but not '.java' or 'xyz.java' (both
don't have one character before '.java').</p>
<p>Combinations of '*'s and '?'s are allowed.</p>
<p>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.</p>
<p>Too 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'.</p>
<p>There is one &quot;shorthand&quot;, if a pattern ends with '/' or '\', then '**'
is appended. E.g. &quot;mypackage/test/&quot; is interpreted as were it &quot;mypackage/test/**&quot;.</p>
<p>Examples:</p>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top">**/CVS/*</td>
    <td valign="top">Matches all files in CVS directories, that can be located
      anywhere in the directory tree.
      <p>Matches:</p>
      <p>CVS/Repository<br>
      org/apache/CVS/Entries<br>
      org/apache/jakarta/tools/ant/CVS/Entries</p>
      <p>But not:</p>
      <p>org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)</td>
  </tr>
  <tr>
    <td valign="top">org/apache/jakarta/**</td>
    <td valign="top">Matches all files in the org/apache/jakarta directory tree.
      <p>Matches:</p>
      <p>org/apache/jakarta/tools/ant/docs/index.html<br>
      org/apache/jakarta/test.xml</p>
      <p>But not:</p>
      <p>org/apache/xyz.java ('jakarta'/' part is missing)</td>
  </tr>
  <tr>
    <td valign="top">org/apache/**/CVS/*</td>
    <td valign="top">Matches all files in CVS directories, that are located
      anywhere in the directory tree under org/apache.
      <p>Matches:</p>
      <p>org/apache/CVS/Entries<br>
      org/apache/jakarta/tools/ant/CVS/Entries</p>
      <p>But not:</p>
      <p>org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)</td>
  </tr>
  <tr>
    <td valign="top">**/test/**</td>
    <td valign="top">Matches all files which have a directory 'test' in their
      path, including 'test' as a filename.</td>
  </tr>
</table>
<p>When these patterns are used in inclusion and exclusion, you have a powerful
way to select just the files you want.</p>
<h3>Examples</h3>
<pre>  &lt;copydir src=&quot;${src}&quot;
           dest=&quot;${dist}&quot;
           includes=&quot;**/images/*&quot;
           excludes=&quot;**/*.gif&quot; /&gt;</pre>
<p>This copies all files in directories called &quot;images&quot;, that are
located in the directory tree &quot;${src}&quot; to the destination &quot;${dist}&quot;,
but excludes all &quot;*.gif&quot; files from the copy.</p>
<p> This example can also be expressed using nested elements as
<pre>  &lt;copydir src=&quot;${src}&quot;
           dest=&quot;${dist}&quot;&gt;
    &lt;include name=&quot;**/images/*&quot;/&gt;
    &lt;exclude name=&quot;**/*.gif&quot; /&gt;
  &lt;/copydir&gt;
</pre>

<h3>Default Excludes</h3>
<p>There are a set of definitions which are excluded by default from all directory based tasks.
They are:
<pre>        &quot;**/*~&quot;,
        &quot;**/#*#&quot;,
        &quot;**/%*%&quot;,
        &quot;**/CVS&quot;,
        &quot;**/CVS/*&quot;,
        &quot;**/.cvsignore&quot;
</pre>
If you do not want these default excludes applied, you may disable them with the 
<code>defaultexcludes=&quot;no&quot;</code> attribute.</p>
<hr>
<h2><a name="tasks">Built in tasks</a></h2>
<ul>
  <li><a href="#ant">Ant</a></li>
  <li><a href="#available">Available</a></li>
  <li><a href="#chmod">Chmod</a></li>
  <li><a href="#copydir">Copydir</a></li>
  <li><a href="#copyfile">Copyfile</a></li>
  <li><a href="#cvs">Cvs</a></li>
  <li><a href="#delete">Delete</a></li>
  <li><a href="#deltree">Deltree</a></li>
  <li><a href="#echo">Echo</a></li>
  <li><a href="#exec">Exec</a></li>
  <li><a href="#expand">Expand</a></li>
  <li><a href="#filter">Filter</a></li>
  <li><a href="#fixcrlf">FixCRLF</a></li>
  <li><a href="#get">Get</a></li>
  <li><a href="#gunzip">GUnzip</a></li>
  <li><a href="#gzip">GZip</a></li>
  <li><a href="#jar">Jar</a></li>
  <li><a href="#java">Java</a></li>
  <li><a href="#javac">Javac</a></li>
  <li><a href="#javadoc">Javadoc/Javadoc2</a></li>
  <li><a href="#keysubst">KeySubst</a></li>
  <li><a href="#mkdir">Mkdir</a></li>
  <li><a href="#patch">Patch</a></li>
  <li><a href="#property">Property</a></li>
  <li><a href="#rename">Rename</a></li>
  <li><a href="#replace">Replace</a></li>
  <li><a href="#rmic">Rmic</a></li>
  <li><a href="#tar">Tar</a></li>
  <li><a href="#taskdef">Taskdef</a></li>
  <li><a href="#touch">Touch</a></li>
  <li><a href="#tstamp">Tstamp</a></li>
  <li><a href="#style">Style</a></li>
  <li><a href="#untar">Untar</a></li>
  <li><a href="#zip">Zip</a></li>
</ul>
<hr>
<h2><a name="ant">Ant</a></h2>
<h3><b>Description:</b></h3>
<p>Runs Ant on a supplied buildfile. This can be used to build subprojects.</p>
<p>When the <i>antfile</i> attribute is omitted, the file &quot;build.xml&quot;
in the supplied directory (<i>dir</i> attribute) is used.</p>
<p>If no target attribute is supplied, the default target of the new project is
used.</p>
<p>The properties of the current project will be available in the new project.
These properties will override the properties that are set in the new project.
(See also the <a href="#property">properties task</a>).</p>
<h3>Parameters:</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">antfile</td>
    <td valign="top">the buildfile to use.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">the directory to use as a basedir for the new Ant project.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">target</td>
    <td valign="top">the target of the new Ant project that should be executed.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">output</td>
    <td valign="top">Filename to write the ant output to.
    </td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>&lt;ant antfile=&quot;subproject/subbuild.xml&quot; dir=&quot;subproject&quot;
  target=&quot;compile&quot; /&gt;</code></p>
  <p><code>&lt;ant dir=&quot;subproject&quot; /&gt;</code></p>
</blockquote>
<hr>
<h2><a name="available">Available</a></h2>
<h3>Description</h3>
<p>Sets a property if a resource is available at runtime. This resource can be a
file resource, a class in classpath or a JVM system resource.</p>
<p>The value part of the properties being set is <i>true</i> if the resource is
present, otherwise, the property is not set.</p>
<p>Normally, this task is used to set properties that are useful to avoid target
execution depending on system parameters.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">property</td>
    <td valign="top">the name of the property to set.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">classname</td>
    <td valign="top">the class to look for in classpath.</td>
    <td valign="middle" align="center" rowspan="3">Yes</td>
  </tr>
  <tr>
    <td valign="top">resource</td>
    <td valign="top">the resource to look for in the JVM</td>
  </tr>
  <tr>
    <td valign="top">file</td>
    <td valign="top">the file to look for.</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;available classname=&quot;org.whatever.Myclass&quot; property=&quot;Myclass.present&quot; /&gt;</pre>
<p>sets the property <code><i>Myclass.present</i></code> to the value &quot;true&quot;
if the <i>org.whatever.Myclass</i> is found in Ant's classpath.</p>
<hr>
<h2><a name="chmod">Chmod</a></h2>
<h3>Description</h3>
<p>Changes the permissions of a file. Right now it has efect only under Unix.
The permissions are also UNIX style, like the argument for the chmod command.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">the file of which the permissions must be changed.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">perm</td>
    <td valign="top">the new permissions.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>&lt;chmod src=&quot;${dist}/start.sh&quot; perm=&quot;ugo+rx&quot;
  /&gt;</code></p>
</blockquote>
<p>makes the &quot;start.sh&quot; file readable and executable for anyone on a
UNIX system.</p>
<hr>
<h2><a name="copydir">Copydir</a></h2>
<h3>Description</h3>
<p>Copies a directory tree from the source to the destination.</p>
<p>It is possible to refine the set of files that are being copied. This can be
done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the <i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The patterns are
relative to the <i>src</i> directory.</p>
<p>The <i>ignore</i> attribute contains the names of the files/directories that
must be excluded from the copy. The names specified in the <i>ignore</i>
attribute are just names, they do not contain any path information! Note that
this attribute has been replaced by the <i>excludes</i> attribute.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">the directory to copy.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">the directory to copy to.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">ignore</td>
    <td valign="top">comma separated list of filenames/directorynames to ignore.
      No files (except default excludes) are excluded when omitted. (<b>deprecated</b>,
      use <i>excludes</i> instead).</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">filtering</td>
    <td valign="top">indicates whether token filtering should take place during
      the copy</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">forceoverwrite</td>
    <td valign="top">overwrite existing files even if the destination
      files are newer (default is false).</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;copydir src=&quot;${src}/resources&quot;
           dest=&quot;${dist}&quot;
  /&gt;</pre>
<p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>.</p>
<pre>  &lt;copydir src=&quot;${src}/resources&quot;
           dest=&quot;${dist}&quot;
           includes=&quot;**/*.java&quot;
           excludes=&quot;**/Test.java&quot;
  /&gt;</pre>
<p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>
recursively. All java files are copied, except for files with the name <code>Test.java</code>.</p>
<pre>  &lt;copydir src=&quot;${src}/resources&quot;
           dest=&quot;${dist}&quot;
           includes=&quot;**/*.java&quot;
           excludes=&quot;mypackage/test/**&quot; /&gt;</pre>
<p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>
recursively. All java files are copied, except for the files under the <code>mypackage/test</code>
directory.</p>
<hr>
<h2><a name="copyfile">Copyfile</a></h2>
<h3>Description</h3>
<p>Copies a file from the source to the destination. The file is only copied if
the source file is newer than the destination file, or when the destination file
does not exist.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">the filename of the file to copy.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">the filename of the file where to copy to.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">filtering</td>
    <td valign="top">indicates whether token filtering should take place during
      the copy</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>&lt;copyfile src=&quot;test.java&quot; dest=&quot;subdir/test.java&quot;
  /&gt;</code></p>
  <p><code>&lt;copyfile src=&quot;${src}/index.html&quot; dest=&quot;${dist}/help/index.html&quot;
  /&gt;</code></p>
</blockquote>
<hr>
<h2><a name="cvs">Cvs</a></h2>
<h3>Description</h3>
<p>Handles packages/modules retrieved from a 
<a href="http://www.cyclic.com/">CVS</a> repository.</p>
<p>When doing automated builds, the <a href="#get">get task</a> should be
preferred over the <i>checkout</i> command, because of speed.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">command</td>
    <td valign="top">the CVS command to execute.</td>
    <td align="center" valign="top">No, default &quot;checkout&quot;</td>
  </tr>
  <tr>
    <td valign="top">cvsRoot</td>
    <td valign="top">the CVSROOT variable.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">the directory where the checked out files should be placed.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">package</td>
    <td valign="top">the package/module to check out.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">tag</td>
    <td valign="top">the tag of the package/module to check out.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">date</td>
    <td valign="top">Use the most recent revision no later than the given date</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">quiet</td>
    <td valign="top">supress informational messages.</td>
    <td align="center" valign="top">No, default &quot;false&quot;</td>
  </tr>
  <tr>
    <td valign="top">noexec</td>
    <td valign="top">report only, don't change any files.</td>
    <td align="center" valign="top">No, default &quot;false&quot;</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;cvs cvsRoot=&quot;:pserver:anoncvs@jakarta.apache.org:/home/cvspublic&quot;
       package=&quot;jakarta-tools&quot;
       dest=&quot;${ws.dir}&quot;
  /&gt;</pre>
<p>checks out the package/module &quot;jakarta-tools&quot; from the CVS
repository pointed to by the cvsRoot attribute, and stores the files in &quot;${ws.dir}&quot;.</p>
<pre>  &lt;cvs dest=&quot;${ws.dir}&quot; command=&quot;update&quot; /&gt;</pre>
<p>updates the package/module that has previously been checked out into
&quot;${ws.dir}&quot;.</p>
<hr>
<h2><a name="delete">Delete</a></h2>
<h3>Description</h3>
<p>Deletes either a single file or
all files in a specified directory and its sub-directories.</p>
<p>It is possible to refine the set of files that are being deleted. This can be
done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included in the deletion process by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded from the deletion process. This is also done with patterns. And
finally with the <i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The patterns are
relative to the <i>dir</i> directory.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">file</td>
    <td valign="top">The file to delete.</td>
    <td align="center" valign="middle" rowspan="2">at least one of the two</td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">The directory to delete files from.</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">Comma separated list of patterns of files that must be
      deleted. All files are in the current directory 
      and any sub-directories are deleted when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">Comma separated list of patterns of files that must be
      excluded from the deletion list. No files (except default excludes) are excluded when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">Indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">verbose</td>
    <td valign="top">Show name of each deleted file (&quot;true&quot;/&quot;false&quot;). Default is "false" when omitted.</td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;delete file=&quot;/lib/ant.jar&quot; /&gt;</pre>
<p>deletes the file <code>/lib/ant.jar</code>.</p>
<pre>  &lt;delete dir=&quot;lib&quot; /&gt;</pre>
<p>deletes all files in the <code>/lib</code> directory.</p>
<pre>  &lt;delete dir=&quot;.&quot;
          include=&quot;**/*.bak&quot;
  /&gt;
</pre>
<p>deletes all files with the extension &quot;<code>.bak</code>&quot from the current directory 
and any sub-directories.</p>
<h2><a name="deltree">Deltree</a></h2>
<h3>Description</h3>
<p>Deletes a directory with all its files and subdirectories.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">the directory to delete.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;deltree dir=&quot;dist&quot; /&gt;</pre>
<p>deletes the directory <code>dist</code>, including its files and
subdirectories.</p>
<pre>  &lt;deltree dir=&quot;${dist}&quot; /&gt;</pre>
<p>deletes the directory <code>${dist}</code>, including its files and
subdirectories.</p>
<hr>
<h2><a name="echo">Echo</a></h2>
<h3>Description</h3>
<p>Echoes a message to System.out.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">message</td>
    <td valign="top">the message to echo.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;echo message=&quot;Hello world&quot; /&gt;</pre>
<hr>
<h2><a name="exec">Exec</a></h2>
<h3>Description</h3>
<p>Executes a system command. When the <i>os</i> attribute is specified, then
the command is only executed when Ant is run on one of the specified operating
systems.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">command</td>
    <td valign="top">the command to execute.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">the directory in which the command should be executed.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">os</td>
    <td valign="top">list of Operating Systems on which the command may be
      executed.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">output</td>
    <td valign="top">the file to which the output of the command should be
      redirected.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>&lt;exec dir=&quot;${src}&quot; command=&quot;dir&quot; os=&quot;windows&quot;
  output=&quot;dir.txt&quot; /&gt;</code></p>
</blockquote>
<hr>
<h2><a name="expand">Expand</a></h2>
<h3>Description</h3>
<p>Unzips a zipfile.</p>
<p>For JDK 1.1 "last modified time" field is set to current time instead of being 
carried from zipfile.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">zipfile to expand.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">directory where to store the expanded files.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>&lt;expand src=&quot;${tomcat_src}/tools-src.zip&quot; dest=&quot;${tools.home}&quot;
  /&gt;</code></p>
</blockquote>
<hr>
<h2><a name="filter">Filter</a></h2>
<h3>Description</h3>
<p>Sets a token filter for this project. Token filters are used by all tasks
that perform file copying operations through the Project commodity methods.</p>
<p>Note: the token string must not contain the separators chars (@).</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">token</td>
    <td valign="top">the token string without @</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">value</td>
    <td valign="top">the string that should be put to replace the token when the
      file is copied</td>
    <td align="center" valign="top">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;filter token=&quot;year&quot; value=&quot;2000&quot; /&gt;
  &lt;copydir src=&quot;${src.dir}&quot; dest=&quot;${dest.dir}&quot;/&gt;</pre>
<p>will copy recursively all the files from the <i>src.dir</i> directory into
the <i>dest.dir</i> directory replacing all the occurencies of the string <i>@year@</i>
with <i>2000.</i></p>
<hr>
<h2><a name="fixcrlf">FixCRLF</a></h2>
<h3>Description</h3>
<p>Adjusts a text file to local.</p>
<p>It is possible to refine the set of files that are being adjusted. This can be
done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the <i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The patterns are
relative to the <i>src</i> directory.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">srcDir</td>
    <td valign="top">Where to find the files to be fixed up.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">destDir</td>
    <td valign="top">Where to place the corrected files.  Defaults to
      srcDir (replacing the original file)</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">cr</td>
    <td valign="top">Specifies how carriage return (CR) characters are to
      be handled.  Valid values for this property are:
      <ul>
      <li>add: ensure that there is a CR before every LF
      <li>asis: leave CR characters alone
      <li>remove: remove all CR characters
      </ul>
      Default is based on the platform on which you are running this task.
      For Unix platforms, the default is remove.  For DOS based systems
      (including Windows), the default is add.
      <p>
      Note: Unless this property is specified as "asis", extra CR characters
      which do not preceed a LF will be removed.
      </td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">tab</td>
    <td valign="top">Specifies how tab characters are to be handled.  Valid
      values for this property are:
      <ul>
      <li>add: convert sequences of spaces which span a tab stop to tabs
      <li>asis: leave tab and space characters alone
      <li>remove: convert tabs to spaces
      </ul>
      Default for this parameter is "asis".
      <p>
      Note: Unless this property is specified as "asis", extra spaces and
      tabs after the last non-whitespace character on the line will be removed.
      </td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">eof</td>
    <td valign="top">Specifies how DOS end of file (control-Z) characters are
      to be handled.  Valid values for this property are:
      <ul>
      <li>add: ensure that there is an EOF character at the end of the file
      <li>asis: leave EOF characters alone
      <li>remove: remove any EOF character found at the end
      </ul>
      Default is based on the platform on which you are running this task.
      For Unix platforms, the default is remove.  For DOS based systems
      (including Windows), the default is asis.
      </td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;
       cr=&quot;remove&quot; eof=&quot;remove&quot;
       includes=&quot;**/*.sh&quot;
  /&gt;</pre>
<p>Removes carriage return and eof characters from the shell scripts.  Tabs and
spaces are left as is.
<pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;
       cr=&quot;add&quot;
       includes=&quot;**/*.bat&quot;
  /&gt;</pre>
<p>Ensures that there are carriage return characters prior to evey line feed.
Tabs and spaces are left as is.
EOF characters are left alone if run on
DOS systems, and are removed if run on Unix systems.</p>
<pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;
       tabs=&quot;add&quot;
       includes=&quot;**/Makefile&quot;
  /&gt;</pre>
<p>Adds or removes CR characters to match local OS conventions, and
converts spaces to tabs when appropriate.  EOF characters are left alone if
run on DOS systems, and are removed if run on Unix systems.
Many versions of make require tabs prior to commands.</p>
<pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;
       tabs=&quot;remove&quot;
       includes=&quot;**/README*&quot;
  /&gt;</pre>
<p>Adds or removes CR characters to match local OS conventions, and
converts all tabs to spaces.  EOF characters are left alone if run on
DOS systems, and are removed if run on Unix systems.
You never know what editor a user will use to browse README's.</p>
<hr>
<h2><a name="get">Get</a></h2>
<h3>Description</h3>
<p>Gets a file from an URL. When the verbose option is &quot;on&quot;, this task
displays a '.' for every 100 Kb retrieved.</p>
<p>This task should be preferred above the <a href="#cvs">CVS task</a> when
doing automated builds. CVS is significant slower than loading a compressed
archive with http/ftp.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">the URL from which to retrieve a file.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">the file where to store the retrieved file.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">verbose</td>
    <td valign="top">show verbose information (&quot;on&quot;/&quot;off&quot;).</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">ignoreerrors</td>
    <td valign="top">Log errors but don't treat as fatal.</td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;get src=&quot;http://jakarta.apache.org/&quot; dest=&quot;help/index.html&quot; /&gt;</pre>
<p>gets the index page of http://jakarta.apache.org/, and stores it in the file <code>help/index.html</code>.</p>
<hr>
<h2><a name="gunzip">GUnzip</a></h2>
<h3>Description</h3>
<p>Expands a GZip file.</p>

<p>If <i>dest</i> is a directory the name of the destination file is
the same as <i>src</i> (with the &quot;.gz&quot; extension removed if
present). If <i>dest</i> is ommited, the parent dir of <i>src</i> is
taken. The file is only expanded if the source file is newer than the
destination file, or when the destination file does not exist.</p>

<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">the file to expand.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">the destination file or directory.</td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>&lt;gunzip src=&quot;test.tar.gz&quot;/&gt;</code></p>
</blockquote>
<p>expands <i>test.tar.gz</i> to <i>test.tar</i></p>
<blockquote>
  <p><code>&lt;gunzip src=&quot;test.tar.gz&quot; dest=&quot;test2.tar&quot;/&gt;</code></p>
</blockquote>
<p>expands <i>test.tar.gz</i> to <i>test2.tar</i></p>
<blockquote>
  <p><code>&lt;gunzip src=&quot;test.tar.gz&quot; dest=&quot;subdir&quot;/&gt;</code></p>
</blockquote>
<p>expands <i>test.tar.gz</i> to <i>subdir/test.tar</i> (assuming
subdir is a directory).</p>

<hr>
<h2><a name="gzip">GZip</a></h2>
<h3>Description</h3>
<p>GZips a file.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">the file to gzip.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">zipfile</td>
    <td valign="top">the destination file.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>&lt;gzip src=&quot;test.tar&quot; zipfile=&quot;test.tar.gz&quot;
  /&gt;</code></p>
</blockquote>
<hr>
<h2><a name="jar">Jar</a></h2>
<h3>Description</h3>
<p>Jars a set of files.</p>
<p>The <i>basedir</i> attribute is the reference directory from where to jar.</p>
<p>It is possible to refine the set of files that are being jarred. This can be
done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the <i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The patterns are
relative to the <i>basedir</i> directory.</p>
<p>The <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i> attributes
replace the <i>items</i> and <i>ignore</i> attributes. The following explains
how the deprecated <i>items</i> and <i>ignore</i> attribute behave.</p>
<p>When &quot;*&quot; is used for <i>items</i>, all files in the basedir, and
its subdirectories, will be jarred. Otherwise all the files and directories
mentioned in the items list will jarred. When a directory is specified, then all
files within it are also jarred.</p>
<p>With the <i>ignore</i> attribute, you can specify files or directories to
ignore. These files will not be jarred. The items in the <i>ignore</i> attribute
override the items in the <i>items</i> attribute. The names specified in the <i>ignore</i>
attribute are just names, they do not contain any path information!</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">jarfile</td>
    <td valign="top">the jar-file to create.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">basedir</td>
    <td valign="top">the directory from which to jar the files.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">compress</td>
    <td valign="top">Not only store data but also compress them, defaults to true</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">items</td>
    <td valign="top">a comma separated list of the files/directories to jar. All
      files are included when omitted. (<b>deprecated</b>, use <i>includes</i>
      instead).</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">ignore</td>
    <td valign="top">comma separated list of filenames/directorynames to exclude
      from the jar. No files (except default excludes) are excluded when
      omitted. (<b>deprecated</b>, use <i>excludes</i> instead).</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">manifest</td>
    <td valign="top">the manifest file to use.</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot; /&gt;</pre>
<p>jars all files in the <code>${build}/classes</code> directory in a file
called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>
<pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;
       basedir=&quot;${build}/classes&quot;
       excludes=&quot;**/Test.class&quot;
  /&gt;</pre>
<p>jars all files in the <code>${build}/classes</code> directory in a file
called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Files
with the name <code>Test.class</code> are excluded.</p>
<pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;
       basedir=&quot;${build}/classes&quot;
       includes=&quot;mypackage/test/**&quot;
       excludes=&quot;**/Test.class&quot;
  /&gt;</pre>
<p>jars all files in the <code>${build}/classes</code> directory in a file
called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Only
files under the directory <code>mypackage/test</code> are used, and files with
the name <code>Test.class</code> are excluded.</p>
<h3>Deprecated examples</h3>
<pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot; items=&quot;*&quot; /&gt;</pre>
<p>jars all files in the <code>${build}/classes</code> directory in a file
called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>
<pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot; items=&quot;*&quot; ignore=&quot;Test.class&quot; /&gt;</pre>
<p>jars all files in the <code>${build}/classes</code> directory in a file
called <code>app.jar</code> in the <code>${dist}/lib</code> directory.
Files/directories with the name <code>Test.class</code> are excluded.</p>
<hr>
<h2><a name="java">Java</a></h2>
<h3>Description</h3>
<p>Executes a Java class within the running (Ant) VM or forks another VM if
specified.</p>
<p>Be careful that the executed class doesn't call System.exit(), because it
will terminate the VM and thus Ant. In case this happens, it's highly suggested
that you set the fork attribute so that System.exit() stops the other VM and not
the one that is currently running Ant.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">classname</td>
    <td valign="top">the Java class to execute.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">args</td>
    <td valign="top">the arguments for the class that is executed.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">classpath</td>
    <td valign="top">the classpath to use.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">fork</td>
    <td valign="top">if enabled triggers the class execution in another VM
      (disabled by default)</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">jvm</td>
    <td valign="top">the command used to invoke the Java Virtual Machine,
      default is 'java'.  The command is resolved by java.lang.Runtime.exec().
      Ignored if fork is disabled.
    </td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">jvmargs</td>
    <td valign="top">the arguments to pass to the forked VM (ignored if fork is
      disabled)</td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;java classname=&quot;test.Main&quot; /&gt;</pre>
<pre>  &lt;java classname=&quot;test.Main&quot; args=&quot;-h&quot; /&gt;</pre>
<pre>  &lt;java classname=&quot;test.Main&quot;
        args=&quot;-h&quot;
        fork=&quot;yes&quot;
        jvmargs=&quot;-Xrunhprof:cpu=samples,file=log.txt,depth=3&quot;
  /&gt;</pre>
<hr>
<h2><a name="javac">Javac</a></h2>
<h3>Description</h3>
<p>Compiles a source tree within the running (Ant) VM.</p>
<p>The source and destination directory will be recursively scanned for Java
source files to compile. Only Java files that have no corresponding class file
or where the class file is older than the java file will be compiled.</p>
<p>Files in the source tree, that are no java files, are copied to the
destination directory, allowing support files to be located properly in the
classpath.</p>
<p>The directory structure of the source tree should follow the package
hierarchy.</p>
<p>It is possible to refine the set of files that are being compiled/copied.
This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the <i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The patterns are
relative to the <i>srcdir</i> directory.</p>
<p>It is possible to use different compilers. This can be selected with the
&quot;build.compiler&quot; property. There are three choices:</p>
<ul>
  <li>classic (the standard compiler of JDK 1.1/1.2)</li>
  <li>modern (the new compiler of JDK 1.3)</li>
  <li>jikes (the <a
    href="http://oss.software.ibm.com/developerworks/opensource/jikes/project">Jikes</a>
    compiler)</li>
</ul>
<p>For JDK 1.1/1.2 is classic the default. For JDK 1.3 is modern the default.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">srcdir</td>
    <td valign="top">location of the java files.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">destdir</td>
    <td valign="top">location where to store the class files.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">classpath</td>
    <td valign="top">the classpath to use.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">bootclasspath</td>
    <td valign="top">location of bootstrap class files.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">extdirs</td>
    <td valign="top">location of installed extensions.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">debug</td>
    <td valign="top">indicates whether there should be compiled with debug
      information (&quot;on&quot;).</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">optimize</td>
    <td valign="top">indicates whether there should be compiled with
      optimization (&quot;on&quot;).</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">deprecation</td>
    <td valign="top">indicates whether there should be compiled with deprecation
      information (&quot;on&quot;).</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">filtering</td>
    <td valign="top">indicates whether token filtering should take place</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">target</td>
    <td valign="top">Generate class files for specific VM version, e.g. "1.1" or "1.2".</td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;javac srcdir=&quot;${src}&quot;
         destdir=&quot;${build}&quot;
         classpath=&quot;xyz.jar&quot;
         debug=&quot;on&quot;
  /&gt;</pre>
<p>compiles all .java files under the directory <code>${src}</code>, and stores
the .class files in the directory <code>${build}</code>. It also copies the non-java
files from the tree under <code>${src}</code> to the tree under <code>${build}</code>.
The classpath used contains <code>xyz.jar</code>, and debug information is on.</p>
<pre>  &lt;javac srcdir=&quot;${src}&quot;
         destdir=&quot;${build}&quot;
         includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;
         excludes=&quot;mypackage/p1/testpackage/**&quot;
         classpath=&quot;xyz.jar&quot;
         debug=&quot;on&quot;
  /&gt;</pre>
<p>compiles .java files under the directory <code>${src}</code>, and stores the
.class files in the directory <code>${build}</code>. It also copies the non-java
files from the tree under <code>${src}</code> to the tree under <code>${build}</code>.
The classpath used contains <code>xyz.jar</code>, and debug information is on.
Only files under <code>mypackage/p1</code> and <code>mypackage/p2</code> are
used. Files in the <code>mypackage/p1/testpackage</code> directory are excluded
form compilation and copy.</p>

<hr>
<h2><a name="javadoc">Javadoc/Javadoc2</a></h2>
<h3>Description</h3>
<p>Generates code documentation using the javadoc tool.</p>
<p>The source directory will be recursively scanned for Java source files to process
but only those matching the inclusion rules will be passed to the javadoc tool. This
allows wildcards to be used to choose between package names, reducing verbosity
and management costs over time. This task, however, has no notion of
&quot;changed&quot; files, unlike the <a href="#javac">javac</a> task. This means
all packages will be processed each time this task is run. In general, however,
this task is used much less frequently.</p>
<p>This task works seamlessly between different javadoc versions (1.1 and 1.2),
with the obvious restriction that the 1.2 attributes will be ignored if run in a
1.1 VM.</p>
<p>NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the
same VM as ant without breaking functionality. For this reason, this task 
always forks the VM. This overhead is not significant since javadoc is normally a heavy
application and will be called infrequently.</p>
<p>NOTE: the packagelist attribute allows you to specify the list of packages to 
document outside of the Ant file. It's a much better practice to include everything 
inside the build.xml file. This option was added in order to make it easier to 
migrate from regular makefiles, where you would use this option of javadoc. 
The packages listed in packagelist are not checked, so the task performs even 
if some packages are missing or broken. Use this option if you wish to convert from 
an existing makefile. Once things are running you should then switch to the regular 
notation. 

<p>DEPRECATION: the javadoc2 task simply points to the javadoc task and it's
there for back compatibility reasons. Since this task will be removed in future
versions, you are strongly encouraged to use <a href="#javadoc">javadoc</a>
instead.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Availability</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">sourcepath</td>
    <td valign="top">Specify where to find source files</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">destdir</td>
    <td valign="top">Destination directory for output files</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">maxmemory</td>
    <td valign="top">Max amount of memory to allocate to the javadoc VM</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">sourcefiles</td>
    <td valign="top">Space separated list of source files</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="middle" rowspan="2">at least one of the two</td>
  </tr>
  <tr>
    <td valign="top">packagenames</td>
    <td valign="top">Space separated list of package files (with terminating
      wildcard)</td>
    <td align="center" valign="top">all</td>
  </tr>
  <tr>
    <td valign="top">packageList</td>
    <td valign="top">The name of a file containing the packages to process</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">classpath</td>
    <td valign="top">Specify where to find user class files</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Bootclasspath</td>
    <td valign="top">Override location of class files loaded by the bootstrap
      class loader</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Extdirs</td>
    <td valign="top">Override location of installed extensions</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Overview</td>
    <td valign="top">Read overview documentation from HTML file</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Public</td>
    <td valign="top">Show only public classes and members</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Protected</td>
    <td valign="top">Show protected/public classes and members (default)</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Package</td>
    <td valign="top">Show package/protected/public classes and members</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Private</td>
    <td valign="top">Show all classes and members</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Old</td>
    <td valign="top">Generate output using JDK 1.1 emulating doclet</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Verbose</td>
    <td valign="top">Output messages about what Javadoc is doing</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Locale</td>
    <td valign="top">Locale to be used, e.g. en_US or en_US_WIN</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Encoding</td>
    <td valign="top">Source file encoding name</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Version</td>
    <td valign="top">Include @version paragraphs</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Use</td>
    <td valign="top">Create class and package usage pages</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Author</td>
    <td valign="top">Include @author paragraphs</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Splitindex</td>
    <td valign="top">Split index into one file per letter</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Windowtitle</td>
    <td valign="top">Browser window title for the documenation (text)</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Doctitle</td>
    <td valign="top">Include title for the package index(first) page (html-code)</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Header</td>
    <td valign="top">Include header text for each page (html-code)</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">Footer</td>
    <td valign="top">Include footer text for each page (html-code)</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">bottom</td>
    <td valign="top">Include bottom text for each page (html-code)</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">link</td>
    <td valign="top">Create links to javadoc output at the given URL</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">linkoffline</td>
    <td valign="top">Link to docs at &lt;url&gt; using package list at
      &lt;url2&gt;</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">group</td>
    <td valign="top">Group specified packages together in overview page</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">nodeprecated</td>
    <td valign="top">Do not include @deprecated information</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">nodeprecatedlist</td>
    <td valign="top">Do not generate deprecated list</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">notree</td>
    <td valign="top">Do not generate class hierarchy</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">noindex</td>
    <td valign="top">Do not generate index</td>
    <td align="center" valign="top">all</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">nohelp</td>
    <td valign="top">Do not generate help link</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">nonavbar</td>
    <td valign="top">Do not generate navigation bar</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">serialwarn</td>
    <td valign="top">FUTURE: Generate warning about @serial tag</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">helpfile</td>
    <td valign="top">FUTURE: Specifies the HTML help file to use</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">stylesheetfile</td>
    <td valign="top">Specifies the CSS stylesheet to use</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">charset</td>
    <td valign="top">FUTURE: Charset for cross-platform viewing of generated
      documentation</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">docencoding</td>
    <td valign="top">Output file encoding name</td>
    <td align="center" valign="top">1.1</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">doclet</td>
    <td valign="top">Specifies the class file that starts the doclet used in generating the documentation.</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">docletpath</td>
    <td valign="top">Specifies the path to the doclet class file that is specified with the -doclet option.</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">additionalparam</td>
    <td valign="top">Lets you add additional parameters to the javadoc command line. Useful for doclets</td>
    <td align="center" valign="top">1.2</td>
    <td align="center" valign="top">No</td>
  </tr>
</table>

<h3>Parameters specified as subelements</h3>
Two parameters of the Javadoc task may be specified as nested elements of the
Javadoc task element: link and group.
When present, there can be any number of each of these elements.
They perform the same role as the link, linkoffline and
group attributes. You can use either syntax (or both at once), but with the  nested 
elements you can easily specify multiple occurrences of the arguments.
<h4>link</h4>
Create link to javadoc output at the given URL
<h4>Parameters</h4>

<table width="60%" border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">href</td>
    <td valign="top">The URL for the external documentation you wish to link to</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">offline</td>
    <td valign="top">True if this link is not available online at the time of 
                     generating the documentation</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">packagelistLoc</td>
    <td valign="top">The location to the directory containing the package-list file for
                     the external documentation</td>
    <td align="center" valign="top">Only if the offline attribute is true</td>
  </tr>
</table>
  
<h4>groups</h4>
Separates packages on the overview page into whatever groups you specify,
one group per table.

<table width="60%" border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">title</td>
    <td valign="top">Title of the group</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">packages</td>
    <td valign="top">List of packages to include in that group</td>
    <td align="center" valign="top">Yes</td>
  </tr>
</table>

<h3>Example</h3>
<pre>  &lt;javadoc packagenames=&quot;com.dummy.test.*&quot;
           sourcepath=&quot;src&quot;
           destdir=&quot;docs/api&quot;
           author=&quot;true&quot;
           version=&quot;true&quot;
           use=&quot;true&quot;
           windowtitle=&quot;Test API&quot;
           doctitle=&quot;&lt;h1&gt;Test&lt;/h1&gt;&quot;
           bottom=&quot;&lt;i&gt;Copyright &amp;#169; 2000 Dummy Corp. All Rights Reserved.&lt;/i&gt;&quot;&gt;
    &lt;group title=&quot;Group 1 Packages&quot; packages=&quot;com.dummy.test.a*&quot;/&gt;
    &lt;group title=&quot;Group 2 Packages&quot; packages=&quot;com.dummy.test.b*&quot;/&gt;
    &lt;link offline=&quot;true&quot; href=&quot;http://java.sun.com/products/jdk/1.2/docs/api/&quot; packagelistLoc=&quot;C:\tmp&quot;/&gt;
    &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;
  &lt/javadoc&gt;</pre>
  
<hr>
<h2><a name="keysubst">KeySubst</a></h2>
<h3>Description</h3>
<p>Performs keyword substitution in the source file, and writes the result to
the destination file.</p>
<p>Keys in the source file are of the form ${keyname}. The <i>keys</i> attribute
contains key/value pairs. When a key is found in the <i>keys</i> attribute, then
&quot;${keyname}&quot; is replaced by the corresponding value.</p>
<p>The <i>keys</i> attribute is of the form
&quot;name1=value1*name2=value2*name3=value3&quot;. The '*' is called the
separator, which might we changed with the <i>sep</i> attribute.</p>
<p>Note: the source file and destination file may not be the same.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">the source file.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">the destination file.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">sep</td>
    <td valign="top">the separator for the name/value pairs.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">keys</td>
    <td valign="top">name/value pairs for replacement.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;keysubst src=&quot;abc.txt&quot; dest=&quot;def.txt&quot; keys=&quot;VERSION=1.0.3*DATE=2000-01-10&quot; /&gt;</pre>
<hr>
<h2><a name="mkdir">Mkdir</a></h2>
<h3>Description</h3>
<p>Creates a directory. Also non-existent parent directories are created, when
necessary.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">the directory to create.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>&lt;mkdir dir=&quot;${dist}&quot; /&gt;</pre>
<p>creates a directory <code>${dist}</code>.</p>
<pre>&lt;mkdir dir=&quot;${dist}/lib&quot; /&gt;</pre>
<p>creates a directory <code>${dist}/lib</code>.</p>
<hr>
<h2><a name="patch">Patch</a></h2>
<h3>Description</h3>
<p>Applies a diff file to originals.
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">the directory in which the command should be executed.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">os</td>
    <td valign="top">list of Operating Systems on which the command may be
      executed.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">output</td> 
    <td valign="top">the file to which the output of the patch command 
      should be redirected.</td> 
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">patchfile</td> 
    <td valign="top">the file that includes the diff output</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">originalfile</td> 
    <td valign="top">the file to patch</td>
    <td align="center" valign="top">No, tries to guess it from the diff 
      file</td>
  </tr>
  <tr>
    <td valign="top">backups</td> 
    <td valign="top">Keep backups of the unpatched files</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">quiet</td> 
    <td valign="top">Work silently unless an error occurs</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">reverse</td> 
    <td valign="top">Assume patch was created with old and new files 
      swapped.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">ignorewhitespace</td> 
    <td valign="top">Ignore whitespace differences.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">strip</td> 
    <td valign="top">Strip the smallest prefix containing <i>num</i> leading 
      slashes from filenames.</td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;patch patchfile=&quot;module.1.0-1.1.patch&quot; /&gt;</pre>
<p>applies the diff included in <i>module.1.0-1.1.patch</i> to the
files in base directory guessing the filename(s) from the diff output.
<pre>  &lt;patch patchfile=&quot;module.1.0-1.1.patch&quot; strip="1" /&gt;</pre>
<p>like above but one leading directory part will be removed. i.e. if
the diff output looked like
<pre>
--- a/mod1.0/A	Mon Jun  5 17:28:41 2000
+++ a/mod1.1/A	Mon Jun  5 17:28:49 2000
</pre> 
the leading <i>a/</i> will be stripped.
<h2><a name="property">Property</a></h2>
<h3>Description</h3>
<p>Sets a property (by name and value), or set of properties (from file or
resource) in the project.</p>
<p>When a property was set by the user, or was a property in a parent project
(that started this project with the <a href="#ant">ant task</a>), then this
property cannot be set, and will be ignored. This means that properties set
outside the current project always override the properties of the current
project.</p>
<p>There are three ways to set properties:</p>
<ul>
  <li>By supplying both the <i>name</i> and <i>value</i> attribute.</li>
  <li>By setting the <i>file</i> attribute with the filename of the property
    file to load. This property file has the format as defined by the file used
    in the class java.util.Properties.</li>
  <li>By setting the <i>resource</i> attribute with the resource name of the
    property file to load. This property file has the format as defined by the
    file used in the class java.util.Properties.</li>
</ul>
<p>Although combinations of the three ways are possible, only one should be used
at a time. Problems might occur with the order in which properties are set, for
instance.</p>
<p>The value part of the properties being set, might contain references to other
properties. These references are resolved at the time these properties are set.
This also holds for properties loaded from a property file.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">name</td>
    <td valign="top">the name of the property to set.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">value</td>
    <td valign="top">the value of the property.</td>
    <td valign="middle" align="center" rowspan="3">Yes</td>
  </tr>
  <tr>
    <td valign="top">resource</td>
    <td valign="top">the resource name of the property file.</td>
  </tr>
  <tr>
    <td valign="top">file</td>
    <td valign="top">the filename of the property file .</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;property name=&quot;foo.dist&quot; value=&quot;dist&quot; /&gt;</pre>
<p>sets the property <code>foo.dist</code> to the value &quot;dist&quot;.</p>
<pre>  &lt;property file=&quot;foo.properties&quot; /&gt;</pre>
<p>reads a set of properties from a file called &quot;foo.properties&quot;.</p>
<pre>  &lt;property resource=&quot;foo.properties&quot; /&gt;</pre>
<p>reads a set of properties from a resource called &quot;foo.properties&quot;.</p>
<p>Note that you can reference a global properties file for all of your Ant
builds using the following:
<pre>  &lt;property file=&quot;${user.home}/.ant-global.properties&quot; /&gt;</pre>
<p>since the &quot;user.home&quot; 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
JVM that I tested, the home directory on Windows is &quot;C:\&quot;.  Different JVM
implementations may use other values for the home directory on Windows.
<hr>
<h2><a name="rename">Rename</a></h2>
<h3>Description</h3>
<p>Renames a given file.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">file to rename.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">new name of the file.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">replace</td>
    <td valign="top">Enable replacing of existing file (default: on).</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;rename src=&quot;foo.jar&quot; dest=&quot;${name}-${version}.jar&quot; /&gt;</pre> 
<p>Renames the file <code>foo.jar</code> to <code>${name}-${version}.jar</code> (assuming <code>name</code>
 and <code>version</code> being predefined properties). If a file named <code>${name}-${version}.jar</code>
 already exists, it will be removed prior to renameing <code>foo.jar</code>.</p>
<hr>
<h2><a name="replace">Replace</a></h2>
<h3>Description</h3>
<p>Replace is a directory based task for replacing the occurrence of a given string with another string 
in selected file.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">file</td>
    <td valign="top">file for which the token should be replaced. If not present the dir attribute 
                     must be specified</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">The base directory to use when replacing a token in multiple files. If not present the file attribute
                     must be specified</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">token</td>
    <td valign="top">the token which must be replaced.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">value</td>
    <td valign="top">the new value for the token. When omitted, an empty string
      (&quot;&quot;) is used.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;replace file=&quot;${src}/index.html&quot; token=&quot;@@@&quot; value=&quot;wombat&quot; /&gt;</pre>
<p>replaces occurrences of the string &quot;@@@&quot; with the string
&quot;wombat&quot;, in the file <code>${src}/index.html</code>.</p>
<hr>
<h2><a name="rmic">Rmic</a></h2>
<h3>Description</h3>
<p>Runs the rmic compiler for a certain class.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">base</td>
    <td valign="top">the location to store the compiled files.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">classname</td>
    <td valign="top">the class for which to run <code>rmic</code>.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">filtering</td>
    <td valign="top">indicates whether token filtering should take place</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">sourcebase</td>
    <td valign="top">Pass the "-keepgenerated" flag to rmic and
 move the generated source file to the base directory.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">stubversion</td>
    <td valign="top">Specify the JDK version for the generated stub code.
 Specify "1.1" to pass the "-v1.1" option to rmic.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">classpath</td>
    <td valign="top">The classpath to use during compilation</td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;rmic classname=&quot;com.xyz.FooBar&quot; base=&quot;${build}/classes&quot; /&gt;</pre>
<p>runs the rmic compiler for the class <code>com.xyz.FooBar</code>. The
compiled files will be stored in the directory <code>${build}/classes</code>.</p>
<hr>
<h2><a name="tar">Tar</a></h2>
<h3>Description</h3>
<p>Creates a tar archive.</p>
<p>The <i>basedir</i> attribute is the reference directory from where to tar.</p>
<p>It is possible to refine the set of files that are being tarred. This can be
done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the <i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The patterns are
relative to the <i>basedir</i> directory.</p>
<p>The <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i> attributes
replace the <i>items</i> and <i>ignore</i> attributes. The following explains
how the deprecated <i>items</i> and <i>ignore</i> attribute behave.</p>
<p>When &quot;*&quot; is used for <i>items</i>, all files in the basedir, and
its subdirectories, will be tarred. Otherwise all the files and directories
mentioned in the items list will tarred. When a directory is specified, then all
files within it are also tarred.</p>
<p>With the <i>ignore</i> attribute, you can specify files or directories to
ignore. These files will not be tarred. The items in the <i>ignore</i> attribute
override the items in the <i>items</i> attribute. The names specified in the <i>ignore</i>
attribute are just names, they do not contain any path information!</p>
<p>Note that this task does not perform compression. You might want to use the <a href="#gzip">GZip</a>
task to come up with a .tar.gz package.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td valign="top" align="center"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">tarfile</td>
    <td valign="top">the tar-file to create.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">basedir</td>
    <td valign="top">the directory from which to zip the files.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot; basedir=&quot;htdocs/manual&quot; /&gt;
  &lt;gzip zipfile=&quot;${dist}/manual.tar.gz&quot; src=&quot;${dist}/manual.tar&quot; /&gt;</pre>
<p>tars all files in the <code>htdocs/manual</code> directory in a file called <code>manual.tar</code>
in the <code>${dist}</code>  directory, then applies the gzip task to compress
it.</p>
<pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot;
       basedir=&quot;htdocs/manual&quot;
       excludes=&quot;mydocs/**, **/todo.html&quot;
  /&gt;</pre>
<p>tars all files in the <code>htdocs/manual</code> directory in a file called <code>manual.tar</code>
in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,
or files with the name <code>todo.html</code> are excluded.</p>
<hr>
<h2><a name="taskdef">Taskdef</a></h2>
<h3>Description</h3>
<p>Adds a task definition to the current project, such that this new task can be
used in the current project. Two attributes are needed, the name that identifies
this task uniquely, and the full name of the class (including the packages) that
implements this task.</p>
<p>Taskdef should be used to add your own tasks to the system. See also &quot;<a
href="#writingowntask">Writing your own task</a>&quot;.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">name</td>
    <td valign="top">the name of the task</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">classname</td>
    <td valign="top">the full class name implementing the task</td>
    <td valign="top" align="center">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;taskdef name=&quot;myjavadoc&quot; classname=&quot;com.mydomain.JavadocTask&quot; /&gt;</pre>
<p>makes a task called <code>myjavadoc</code> available to Ant. The class <code>com.mydomain.JavadocTask</code>
implements the task.</p>
<hr>
<h2><a name="touch">Touch</a></h2>
<h3>Description</h3>
<p>Changes the modification time of a file and possibly creates it at
the same time.</p>
<p>For JDK 1.1 only the creation of new files with a modification time
of now works, all other cases will emit a warning.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">file</td>
    <td valign="top">the name of the file</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">millis</td>
    <td valign="top">specifies the new modification time of the file
       in milliseconds since midnight Jan 1 1970</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">datetime</td>
    <td valign="top">specifies the new modification time of the file
       in the format MM/DD/YYYY HH:MM AM_or_PM.</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<p>If both <code>millis</code> and <code>datetime</code> are ommited
the current time is assumed.</p>
<h3>Examples</h3>
<pre>  &lt;touch file=&quot;myfile&quot; /&gt;</pre>
<p>creates <code>myfile</code> if it doesn't exist and changes the
modification time to the current time.</p>
<pre>  &lt;touch file=&quot;myfile&quot; datetime=&quot;06/28/2000 2:02 pm&quot; /&gt;</pre>
<p>creates <code>myfile</code> 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).</p>
<hr>
<h2><a name="tstamp">Tstamp</a></h2>
<h3>Description</h3>
<p>Sets the DSTAMP, TSTAMP and TODAY properties in the current project. The
DSTAMP is in the &quot;yyyymmdd&quot; format, the TSTAMP is in the &quot;hhmm&quot;
format and TODAY is &quot;month day year&quot;.</p>
<p>These properties can be used in the buildfile, for instance, to create
timestamped filenames or used to replace placeholder tags inside documents to
indicate, for example, the release date. The best place for this task is in your
initialization target.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;tstamp/&gt;</pre>
<hr>
<h2><a name="style">Style</a></h2>
<h3>Description</h3>
<p>Process a set of documents via XSLT.</p>
<p>This is useful for building views of XML based documentation,
or in generating code.</p>
<p>It is possible to refine the set of files that are being copied. This can be
done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the <i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The patterns are
relative to the <i>basedir</i> directory.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">basedir</td>
    <td valign="top">where to find the source xml file.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">destdir</td>
    <td valign="top">directory where to store the results.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">extention</td>
    <td valign="top">desired file extension to be used for the targets.
        If not specified, the default is "html".</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">style</td>
    <td valign="top">name of the stylesheet to use.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">processor</td>
    <td valign="top">name of the XSLT processor to use.  Permissable
values are "xslp" for the XSL:P processor, "xalan" for the Apache XML Xalan
processor, or the name of an arbitrary XSLTLiaison class.
Defaults to xslp or xalan (in that order), if one is found in your
class path</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><pre>
&lt;style basedir=&quot;doc&quot; destdir=&quot;build/doc&quot;
       extension=&quot;html&quot; style=&quot;style/apache.xml&quot;/&gt;
</pre></p>
</blockquote>
<hr>
<h2><a name="untar">Untar</a></h2>
<h3>Description</h3>
<p>Untars a tarfile.</p>
<p>For JDK 1.1 "last modified time" field is set to current time instead of being 
carried from tarfile.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">tarfile to expand.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">directory where to store the expanded files.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>
&lt;gunzip src=&quot;tools.tar.gz&quot;/&gt;<br>
&lt;untar src=&quot;tools.tar&quot; dest=&quot;${tools.home}&quot;/&gt;
</code></p>
</blockquote>
<hr>
<h2><a name="zip">Zip</a></h2>
<h3>Description</h3>
<p>Creates a zipfile.</p>
<p>The <i>basedir</i> attribute is the reference directory from where to zip.</p>
<p>It is possible to refine the set of files that are being zipped. This can be
done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the <i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The patterns are
relative to the <i>basedir</i> directory.</p>
<p>The <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i> attributes
replace the <i>items</i> and <i>ignore</i> attributes. The following explains
how the deprecated <i>items</i> and <i>ignore</i> attribute behave.</p>
<p>When &quot;*&quot; is used for <i>items</i>, all files in the basedir, and
its subdirectories, will be zipped. Otherwise all the files and directories
mentioned in the items list will zipped. When a directory is specified, then all
files within it are also zipped.</p>
<p>With the <i>ignore</i> attribute, you can specify files or directories to
ignore. These files will not be zipped. The items in the <i>ignore</i> attribute
override the items in the <i>items</i> attribute. The names specified in the <i>ignore</i>
attribute are just names, they do not contain any path information!</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td valign="top" align="center"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">zipfile</td>
    <td valign="top">the zip-file to create.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">basedir</td>
    <td valign="top">the directory from which to zip the files.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">compress</td>
    <td valign="top">Not only store data but also compress them, defaults to true</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">items</td>
    <td valign="top">a comma separated list of the files/directories to zip. All
      files are included when omitted. (<b>deprecated</b>, use <i>includes</i>
      instead).</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">ignore</td>
    <td valign="top">comma separated list of filenames/directorynames to exclude
      from the zip. No files (except default excludes) are excluded when
      omitted. (<b>deprecated</b>, use <i>excludes</i> instead).</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;
       basedir=&quot;htdocs/manual&quot;
  /&gt;</pre>
<p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
in the <code>${dist}</code> directory.</p>
<pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;
       basedir=&quot;htdocs/manual&quot;
       excludes=&quot;mydocs/**, **/todo.html&quot;
  /&gt;</pre>
<p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,
or files with the name <code>todo.html</code> are excluded.</p>
<pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;
       basedir=&quot;htdocs/manual&quot;
       includes=&quot;api/**/*.html&quot;
       excludes=&quot;**/todo.html&quot;
  /&gt;</pre>
<p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
in the <code>${dist}</code> directory. Only html files under the directory <code>api</code>
are zipped, and files with the name <code>todo.html</code> are excluded.</p>
<h3>Deprecated examples</h3>
<pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;
       basedir=&quot;htdocs/manual&quot;
       items=&quot;*&quot;
  /&gt;</pre>
<p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
in the <code>${dist}</code> directory.</p>
<pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;
       basedir=&quot;htdocs/manual&quot;
       items=&quot;*&quot;
       ignore=&quot;mydocs, todo.html&quot;
  /&gt;</pre>
<p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
in the <code>${dist}</code> directory. Files/directories with the names <code>mydocs</code>
and <code>todo.html</code> are excluded.</p>

<hr>
<h2><a name="buildevents">Build Events</a></h2>
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,
to connect Ant to a GUI or to integrate Ant with an IDE. 

<p>To use build events you need to create an ant <code>Project</code> object. You can then call the 
<code>addBuildListener</code> method to add your listener to the project. Your listener must implement
the <code>org.apache.tools.antBuildListener</code> interface. The listener will receive BuildEvents 
for the following events
<ul>
<li>Build started
<li>Build finished
<li>Target started
<li>Target finished
<li>Task started
<li>Task finished
<li>Message logged
</ul>

If you wish to attach a listener from the command line you may use the -listener option. For example
<blockquote>
  <pre>ant -listener org.apache.tools.ant.XmlLogger</pre>
</blockquote>
will run ant with a listener which generates an XML representaion of the build progress. This 
listener is included with ant as is the default listener which generates the logging to standard
output.


<hr>
<h2><a name="writingowntask">Writing your own task</a></h2>
<p>It is very easy to write your own task:</p>
<ol>
  <li>Create a Java class that extends <code>org.apache.tools.ant.Task</code>.</li>
  <li>For each attribute, write a setter method. The setter method must be a <code>public
    void</code> method that takes one <code>String</code> as an argument. The
    name of the method must begin with &quot;set&quot;, followed by the
    attribute name, with the first character in uppercase, and the rest in
    lowercase.</li>
  <li>Write a <code>public void execute</code> method, with no arguments, that
    throws a <code>BuildException</code>. This method implements the task
    itself.</li>
</ol>
<p>It is important to know that Ant first calls the setters for the attributes
it encounters for a specific task in the buildfile, before it executes is.</p>
<p>Let's write our own task, that prints a message on the System.out stream. The
task has one attribute called &quot;message&quot;.</p>
<blockquote>
  <pre>package com.mydomain;

import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;

public class MyVeryOwnTask extends Task {
  private String msg;

  // The method executing the task
  public void execute() throws BuildException {
    System.out.println(msg);
  }

  // The setter for the &quot;message&quot; attribute
  public void setMessage(String msg) {
    this.msg = msg;
  }
}</pre>
</blockquote>
<p>It's really this simple;-)</p>
<p>Adding your task to the system is rather simple too:</p>
<ol>
  <li>Make sure the class that implements your task is in the classpath when
    starting Ant.</li>
  <li>In your initialization target, add a <i>taskdef</i> task. This actually adds
    your task to the system.</li>
  <li>Use your task in the rest of the buildfile.</li>
</ol>
<h3>Example</h3>
<blockquote>
  <pre>&lt;?xml version=&quot;1.0&quot;?&gt;

&lt;project name=&quot;OwnTaskExample&quot; default=&quot;main&quot; basedir=&quot;.&quot;&gt;
  &lt;target name=&quot;init&quot;&gt;
    &lt;taskdef name=&quot;mytask&quot; classname=&quot;com.mydomain.MyVeryOwnTask&quot;/&gt;
  &lt;/target&gt;

  &lt;target name=&quot;main&quot; depends=&quot;init&quot;&gt;
    &lt;mytask message=&quot;Hello World! MyVeryOwnTask works!&quot; /&gt;
  &lt;/target&gt;
&lt;/project&gt;
</pre>
</blockquote>
<p>Another way to add a task (more permanently), is to add the task name and
implementing class name to the <code>default.properties</code> file in the <code>org.apache.tools.ant.taskdefs</code>
package. Then you can use it as if it were a built in task.</p>
<hr>
<h2><a name="feedback">Feedback</a></h2>
<p>To provide feedback on this software, please subscribe to the Ant Development
Mail List <a href="mailto:(ant-dev-subscribe@jakarta.apache.org">(ant-dev-subscribe@jakarta.apache.org</a>)</p>
<hr>
<p align="center">Copyright � 2000 Apache Software Foundation. All rights
Reserved.</p>

<h2><a name="optionaltasks">Optional tasks</a></h2>
<ul>
  <li><a href="#netrexxc">NetRexxC</a></li>
  <li><a href="#renameexts">RenameExtensions</a></li>
  <li><a href="#script">Script</a></li>
</ul>
<hr>
<h2><a name="netrexxc">NetRexxC</a></h2>
<h3><b>Description:</b></h3>
<p>Compiles a <a href="http://www2.hursley.ibm.com/netrexx">NetRexx</a>
source tree within the running (Ant) VM.</p>
<p>The source and destination directory will be recursively scanned for
NetRexx source files to compile.  Only NetRexx files that have no corresponding
class file or where the class file is older than the java file will be compiled.</p>
<p>Files in the source tree are copied to the destination directory,
allowing support files to be located properly in the classpath. The source 
files are copied because the NetRexx compiler cannot produce class files in a
specific directory via parameters</p>
<p>The directory structure of the source tree should follow the package
hierarchy.</p>
<p>It is possible to refine the set of files that are being compiled/copied.
This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and
<i>defaultexcludes</i> attributes. With the <i>includes</i> or <i>includesfile</i> attribute you 
specify the files you want to have included by using patterns. The 
<i>exclude</i> or <i>excludesfile</i> attribute is used to specify the files you want to have 
excluded.  This is also done with patterns.  And finally with the 
<i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The
patterns are relative to the <i>srcDir</i> directory.</p>

<h3>Parameters:</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">binary</td>
    <td valign="top">Whether literals are treated as the java binary
      type rather than the NetRexx types</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">classpath</td>
    <td valign="top">The classpath to use during compilation</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">comments</td>
    <td valign="top">Whether comments are passed through to the
      generated java source</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">compact</td>
    <td valign="top">Whether error messages come out in compact or
      verbose format</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">compile</td>
    <td valign="top">Whether the NetRexx compiler should compile the
      generated java code</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">console</td>
    <td valign="top">Whether or not messages should be displayed on the
      'console'</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">crossref</td>
    <td valign="top">Whether variable cross references are generated</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">decimal</td>
    <td valign="top">Whether decimal arithmetic should be used for the
      NetRexx code</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when
      omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">destDir</td>
    <td valign="top">the destination directory into which the NetRexx
      source files should be copied and then compiled</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">diag</td>
    <td valign="top">Whether diagnostic information about the compile is
      generated</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when
      omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">explicit</td>
    <td valign="top">Whether variables must be declared explicitly
      before use</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">format</td>
    <td valign="top">Whether the generated java code is formatted nicely
      or left to match NetRexx line numbers for call stack debugging</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">java</td>
    <td valign="top">Whether the generated java code is produced</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">keep</td>
    <td valign="top">Sets whether the generated java source file should be kept
      after compilation. The generated files will have an extension of
      .java.keep, <b>not</b> .java</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">logo</td>
    <td valign="top">Whether the compiler text logo is displayed when
      compiling</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">replace</td>
    <td valign="top">Whether the generated .java file should be replaced
      when compiling</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">savelog</td>
    <td valign="top">Whether the compiler messages will be written to
      NetRexxC.log as well as to the console</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">sourcedir</td>
    <td valign="top">Tells the NetRexx compiler to store the class files in the
      same directory as the source files. The alternative is the working
      directory</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">srcDir</td>
    <td valign="top">Set the source dir to find the source Netrexx
      files</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">strictargs</td>
    <td valign="top">Tells the NetRexx compiler that method calls always
      need parentheses, even if no arguments are needed, e.g. 
      <code>aStringVar.getBytes</code> vs. 
      <code>aStringVar.getBytes()</code></td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">strictassign</td>
    <td valign="top">Tells the NetRexx compile that assignments must
      match exactly on type</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">strictcase</td>
    <td valign="top">Specifies whether the NetRexx compiler should be
      case sensitive or not</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">strictimport</td>
    <td valign="top">Whether classes need to be imported explicitly using an 
      <code>import</code> statement.  By default the NetRexx compiler will 
      import certain packages automatically</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">strictprops</td>
    <td valign="top">Whether local properties need to be qualified
      explicitly using <code>this</code></td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">strictsignal</td>
    <td valign="top">Whether the compiler should force catching of
      exceptions by explicitly named types</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">symbols</td>
    <td valign="top">Whether debug symbols should be generated into the
      class file</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">time</td>
    <td valign="top">Asks the NetRexx compiler to print compilation
      times to the console</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">trace</td>
    <td valign="top">Turns on or off tracing and directs the resultant
      trace output</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">utf8</td>
    <td valign="top">Tells the NetRexx compiler that the source is in UTF8</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">verbose</td>
    <td valign="top">Whether lots of warnings and error messages should
      be generated</td>
    <td valign="top" align="center">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>&lt;netrexxc srcDir=&quot;/source/project&quot;
           includes=&quot;vnr/util/*&quot;
           destDir=&quot;/source/project/build&quot;
           classpath=&quot;/source/project2/proj.jar&quot;
           comments=&quot;true&quot;
           crossref=&quot;false&quot; replace=&quot;true&quot;
           keep=&quot;true&quot; /&gt;</code>
  </p>
</blockquote>
<hr>
<h2><a name="renameexts">RenameExtensions</a></h2>
<h3><b>Description:</b></h3>
<p>Renames files in the <code>srcDir</code> directory ending with the
<code>fromExtension</code> string so that they end with the 
<code>toExtension</code> string. Files are only replaced if 
<code>replace</code> is true
</p>
<p>See the section on 
<a href="#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns. The
patterns are relative to the <i>srcDir</i> directory.</p>
<h3>Parameters:</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when
      omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma separated list of patterns of files that must be
      excluded. No files (except default excludes) are excluded when
      omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">excludesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an exclude pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">fromExtention</td>
    <td valign="top">The string that files must end in to be renamed</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma separated list of patterns of files that must be
      included. All files are included when omitted.</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">includesfile</td>
    <td valign="top">the name of a file. Each line of this file is
      taken to be an include pattern</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">replace</td>
    <td valign="top">Whether the file being renamed to should be
      replaced if it already exists</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">srcDir</td>
    <td valign="top">The starting directory for files to search in</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">toExtension</td>
    <td valign="top">The string that renamed files will end with on
      completion</td>
    <td valign="top" align="center">Yes</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p><code>&lt;renameext srcDir=&quot;/source/project1&quot;
              includes=&quot;**&quot;
              excludes=&quot;**/samples/*&quot;
              fromExtension=&quot;.java.keep&quot;
              toExtension=&quot;.java&quot;
              replace=&quot;true&quot; /&gt;
</code>
  </p>
</blockquote>

<hr>
<h2><a name="script">Script</a></h2>
<h3><b>Description:</b></h3>
<p>Execute a script in a 
  <a href="http://www.alphaworks.ibm.com/tech/bsf">BSF</a> supported language.
<p>All items (tasks, targets, etc) of the running project are accessible
from the script.
<h3>Parameters:</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">language</td>
    <td valign="top">The programming language the script is written in.
      Must be a supported BSF language</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">src</td>
    <td valign="top">The location of the script as a file, if not inline</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<blockquote>
  <p>None yet available</p>
</blockquote>

</body>

</html>