stefano 00/01/26 19:48:26
Modified: docs index.html
Log:
MUCH! improved documentation (also up-to-date with latest changes)
Revision Changes Path
1.2 +1548 -44 jakarta-ant/docs/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/index.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.html 2000/01/13 10:42:41 1.1
+++ index.html 2000/01/27 03:48:26 1.2
@@ -1,51 +1,1555 @@
<html>
+
<head>
-<title>BuildTool Readme</title>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<meta http-equiv="Content-Language" content="en-us">
+<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<title>Ant</title>
</head>
+
+<body>
-<body bgcolor="#FFFFFF">
-<h1>BuildTool</h1>
-<p>BuildTool is a Java based build tool. In theory it is kind of like make
without
- makes wrinkles.</p>
-<h2>Why?</h2>
-<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 developming 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. "Is my command not
executing
- because I have a space in front of my tab!!!" said the original
author
- of BuildTool 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>BuildTool 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 implments 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, BuildTool has an exec
rule
- that allows different commands to be executed based on the OS that it is
executing
- on. </p>
-<h2>How?</h2>
-<p>To get started using BuildTool check out the following topics:</p>
-<ul>
- <li>Installing BuildTool</li>
- <li>Writing a simple BuildFile</li>
- <li>Built in Tasks</li>
- <li>Writing a new Task</li>
- <li>API Documentation</li>
-</ul>
-<h2>License</h2>
-<h2>Feedback</h2>
-<p>To provide feedback on this software, please send mail to <a
href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</a>.</p>
+<h1>Ant User Manual</h1>
+<p>by </p>
+<ul>
+ <li> Arnout J. Kuiper <a href="mailto:([EMAIL PROTECTED]">([EMAIL
PROTECTED]</a>)</li>
+ <li>Stefano Mazzocchi <a href="mailto:([EMAIL PROTECTED]">([EMAIL
PROTECTED]</a>)</li>
+</ul>
+<p>Version 1.0.2 - 2000/01/26</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="#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="#tasks">Built in Tasks</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
+makes 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. "Is my command not executing
+because I have a space in front of my tab!!!" said the original author
of
+Ant way too many times. Tools like Jam took care of this to a great degree,
but
+still use yet another format to use and remember.</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="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 -Ddist.dir=<directory to install Ant>
dist</code></p>
+</blockquote>
+<p>for Windows, and</p>
+<blockquote>
+<p><code>build.sh -Ddist.dir=<directory to install Ant> 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
<code>xml.jar</code>.</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.</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
<code>antRun.bat</code>
+(Windows) or <code>antRun</code> (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 <file></i>,
+where <i><file></i> is the buildfile you want to use.</p>
+<p>You can also set properties which override properties specified in the
+buildfile. This can be done with the <i>-D<property>=<value></i>
+option, where <i><property></i> is the name of the property and
<i><value></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
+-quiet be extra quiet
+-verbose be extra verbose
+-logfile <file> use given file for log
+-buildfile <file> use given buildfile
+-D<property>=<value> 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>set
CLASSPATH=c:\ant\lib\ant.jar;c:\ant\lib\xml.jar;c:\jdk1.2.2\lib\tools.jar
+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.</p>
+<hr>
+<h2><a name="buildfile">Writing a simple buildfile</a></h2>
+<p>The buildfile is an 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
"basedir"
+ 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>
+<pre><target name="A"/>
+<target name="B" depends="A"/>
+<target name="C" depends="B"/>
+<target name="D" depends="C,B,A"/></pre>
+<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>In situations without such dependencies, you can rely on the order of the
+targets in the <i>depends</i> attributes.</p>
+<p>A target gets executed only once. Even when more targets depend on it (see
+the previous example).</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>
+</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><name attribute1="value1" attribute2="value2"
... /></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
+"${" and "}" in the attribute value.</p>
+<p>If there is a property called "builddir" with the value
+"build", then this could be used in an attribute like this:
"${builddir}/classes".
+This is resolved as "build/classes".</p>
+<h3>Examples</h3>
+<blockquote>
+<pre><project name="foo" default="dist"
basedir=".">
+ <target name="init">
+ <tstamp/>
+ <property name="build" value="build" />
+ <property name="dist" value="dist" />
+ </target>
+
+ <target name="prepare" depends="init">
+ <mkdir dir="${build}" />
+ </target>
+
+ <target name="compile" depends="prepare">
+ <javac srcdir="${src}" destdir="${build}" />
+ </target>
+
+ <target name="dist" depends="compile">
+ <mkdir dir="${dist}/lib" />
+ <jar jarfile="${dist}/lib/foo${DSTAMP}.jar"
+ basedir="${build}" items="com"/>
+ </target>
+
+ <target name="clean" depends="init">
+ <deltree dir="${build}" />
+ <deltree dir="${dist}" />
+ </target>
+</project>
+</pre>
+</blockquote>
+<hr>
+<h2><a name="tasks">Built in tasks</a></h2>
+<ul>
+ <li><a href="#ant">Ant</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="#get">Get</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="#property">Property</a></li>
+ <li><a href="#replace">Replace</a></li>
+ <li><a href="#rmic">Rmic</a></li>
+ <li><a href="#taskdef">Taskdef</a></li>
+ <li><a href="#tstamp">Tstamp</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
"build.xml"
+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>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><ant antfile="subproject/subbuild.xml"
dir="subproject"
+target="compile" /></code></p>
+<p><code><ant dir="subproject" /></code></p>
+</blockquote>
+<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><chmod src="${dist}/start.sh" perm="ugo+rx"
+/></code></p>
+</blockquote>
+<p>makes the "start.sh" 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 exclude a set of files from the files that are being
+copied. This can be done with the <i>ignore</i> attribute. This 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!</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.</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><copydir src="${src}/resources"
dest="${dist}"
+/></code></p>
+</blockquote>
+<p>copies the directory <code>${src}/resources</code> to
<code>${dist}</code>.</p>
+<blockquote>
+<p><code><copydir src="${src}/resources"
dest="${dist}"
+ignore="old, Test.java" /></code></p>
+</blockquote>
+<p>copies the directory <code>${src}/resources</code> to
<code>${dist}</code>.
+All files/directories with the names <code>old</code> and
<code>Test.java</code>
+are excluded from the copy. When <code>old</code> or <code>Test.java</code>
is
+the name of a directory, then that whole directory is excluded from the
copy.</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>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><copyfile src="test.java"
dest="subdir/test.java"
+/></code></p>
+<p><code><copyfile src="${src}/index.html"
dest="${dist}/help/index.html"
+/></code></p>
+</blockquote>
+<hr>
+<h2><a name="cvs">Cvs</a></h2>
+<h3>Description</h3>
+<p>Checks out a package/module 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, 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">cvsRoot</td>
+ <td valign="top">the CVSROOT variable.</td>
+ <td align="center" valign="top">Yes</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">Yes</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>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><cvs cvsRoot=":pserver:[EMAIL
PROTECTED]:/home/cvspublic"
+package="jakarta-tools" dest="${ws.dir}" /></code></p>
+</blockquote>
+<p>This checks out the package/module "jakarta-tools" from the CVS
+repository pointed to by the cvsRoot attribute, and stores the files in
"${ws.dir}".</p>
+<hr>
+<h2><a name="delete">Delete</a></h2>
+<h3>Description</h3>
+<p>Deletes a single 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">the file to delete.</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><delete file="/lib/ant.jar" /></code></p>
+<p><code><delete file="${ant}" /></code></p>
+</blockquote>
+<hr>
+<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>
+<blockquote>
+<p><code><deltree dir="dist" /></code></p>
+<p><code><deltree dir="${dist}" /></code></p>
+</blockquote>
<hr>
-<p>Java is a trademark of Sun Microsystems.</p>
+<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>
+<blockquote>
+<p><code><echo message="Hello world" /></code></p>
+</blockquote>
+<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><exec dir="${src}" command="dir"
os="windows"
+output="dir.txt" /></code></p>
+</blockquote>
+<hr>
+<h2><a name="expand">Expand</a></h2>
+<h3>Description</h3>
+<p>Unzips a 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><expand src="${tomcat_src}/tools-src.zip"
dest="${tools.home}"
+/></code></p>
+</blockquote>
+<hr>
+<h2><a name="get">Get</a></h2>
+<h3>Description</h3>
+<p>Gets a file from an URL. When the verbose option is "on", 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
("on"/"off").</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><get src="http://jakarta.apache.org/"
dest="help/index.html"
+/></code></p>
+</blockquote>
+<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><gzip src="test.tar" zipfile="test.tar.gz"
/></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>When "*" is used for items, 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">items</td>
+ <td valign="top">a comma separated list of the files/directories to
jar.</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+ <tr>
+ <td valign="top">ignore</td>
+ <td valign="top">a comma separated list of the filenames/directorynames
to
+ exclude from the jar.</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>
+<blockquote>
+<p><code><jar jarfile="${dist}/lib/app.jar"
basedir="${build}/classes"
+items="*" /></code></p>
+</blockquote>
+<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>
+<blockquote>
+<p><code><jar jarfile="${dist}/lib/app.jar"
basedir="${build}/classes"
+items="*" ignore="Test.class" /></code></p>
+</blockquote>
+<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">class</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">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">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>
+<blockquote>
+<p><code><java class="test.Main" /></code></p>
+<p><code><java class="test.Main" args="-h"
/></code></p>
+<p><code><java class="test.Main" args="-h"
+fork="yes"
jvmargs="-Xrunhprof:cpu=samples,file=log.txt,depth=3"
+/></code></p>
+</blockquote>
+<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 use different compilers. This can be selected with the
+"build.compiler" 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">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 ("on").</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 ("on").</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 ("on").</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><javac srcdir="${src}" destdir="${build}"
-classpath="xyz.jar"
+-debug="on" /></code></p>
+</blockquote>
+<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 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 "changed" files, unlike the <a
href="#javac">javac</a>
+task, but it's not used so 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(), we cannot run javadoc inside the
+same VM without breaking functionality. For this reason, this task always
forks
+the VM. But this is not a performance penalty since javadoc is normally a
heavy
+application and must be called just once.</p>
+<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">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">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 <url> using package list at
<url2></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"> 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">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"> 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>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<pre><javadoc packagenames="com.dummy.test.*"
+ sourcepath="src"
+ destdir="docs/api"
+ author="true"
+ version="true"
+ use="true"
+ windowtitle="Test API"
+ doctitle="<h1>Test</h1>"
+ bottom="<i>Copyright &#169; 2000 Dummy Corp. All
Rights Reserved.</i>"
+/></pre>
+</blockquote>
+<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
+"${keyname}" is replaced by the corresponding value.</p>
+<p>The <i>keys</i> attribute is of the form
+"name1=value1*name2=value2*name3=value3". 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>
+<blockquote>
+<p><code><keysubst src="abc.txt" dest="def.txt"
+keys="VERSION=1.0.3*DATE=2000-01-10" /></code></p>
+</blockquote>
+<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>
+<blockquote>
+<p><code><mkdir dir="${dist}" /></code></p>
+<p><code><mkdir dir="${dist}/lib" /></code></p>
+</blockquote>
+<hr>
+<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">No</td>
+ </tr>
+ <tr>
+ <td valign="top">value</td>
+ <td valign="top">the value of the property.</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">resource</td>
+ <td valign="top">the resource name of the property file.</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">file</td>
+ <td valign="top">the filename of the property file .</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><property name="foo.dist"
value="dist"/></code></p>
+<p><code><property file="foo.properties" /></code></p>
+<p><code><property resource="foo.properties" /></code></p>
+</blockquote>
+<hr>
+<h2><a name="replace">Replace</a></h2>
+<h3>Description</h3>
+<p>Replaces the occurrence of a given string with another string in a file.
When
+the <i>value</i> attribute is omitted, it defaults to "".</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</td>
+ <td valign="top" align="center">Yes</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</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><replace file="${src}/index.html" token="@@@"
+value="wombat" /></code></p>
+</blockquote>
+<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">class</td>
+ <td valign="top">the class for which to run <code>rmic</code>.</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><rmic class="com.xyz.FooBar"
+base="${build}/classes" /></code></p>
+</blockquote>
+<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
"<a
+href="#writingowntask">Writing your own 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">name</td>
+ <td valign="top">the name of the task</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+ <tr>
+ <td valign="top">class</td>
+ <td valign="top">the full class name implementing the task</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><taskdef name="myjavadoc"
value="com.mydomain.JavadocTask"
+/></code></p>
+</blockquote>
+<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 "yyyymmdd" format, the TSTAMP is in the "hhmm"
format
+and TODAY is "month day year".</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
the <a
+href="#inittarget">init target</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>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><tstamp/></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>When "*" is used for items, 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 names of 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">items</td>
+ <td valign="top">a comma separated list of the files/directories to
zip.</td>
+ <td align="center" valign="top">Yes</td>
+ </tr>
+ <tr>
+ <td valign="top">ignore</td>
+ <td valign="top">a comma separated list of the filenames/directorynames
to
+ exclude from the zip.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+<blockquote>
+<p><code><zip zipfile="${dist}/manual.zip"
basedir="htdocs/manual"
+items="*" /></code></p>
+</blockquote>
+<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>
+<blockquote>
+<p><code><zip zipfile="${dist}/manual.zip"
basedir="htdocs/manual"
+items="*" ignore="mydocs, todo.html"/></code></p>
+</blockquote>
+<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="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 "set", 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 "message".</p>
+<blockquote>
+<pre>public class MyVeryOwnTask extends Task {
+ private String msg;
+
+ // The method executing the task
+ public void execute() throws BuildException {
+ System.out.println(message);
+ }
+
+ // The setter for the "message" 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 the <i>init</i> 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><project name="TaskTest" default="test"
basedir=".">
+ <target name="init">
+ <taskdef name="mytask"
class="com.mydomain.MyVeryOwnTask"/>
+ </target>
+
+ <target name="test">
+ <mytask myattr="wombat" />
+ </target>
+</project>
+</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:([EMAIL PROTECTED]">([EMAIL PROTECTED]</a>)</p>
+<hr>
+<p align="center">Copyright © 2000 Apache Software Foundation. All
+rights Reserved.</p>
+
</body>
+
</html>
