| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Ant</title> |
| </head> |
| |
| <body> |
| |
| <p><strong>This document is the User Manual for Ant 1.2. It is based |
| on the documentation that shipped with the release of Ant 1.2 but |
| contains clarifications and bug fixes committed after the release |
| date.</strong></p> |
| |
| <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@epost.de">stefan.bodewig@epost.de</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> |
| <li>Nico Seessle (<a href="mailto:nico@seessle.de">nico@seessle.de</a>)</li> |
| <li>Roger Vaughn (<a href="mailto:rvaughn@seaconinc.com">rvaughn@seaconinc.com</a>)</li> |
| <li>Dave Walend (<a href="mailto:dwalend@cs.tufts.edu">dwalend@cs.tufts.edu</a>)</li> |
| </ul> |
| |
| <p>Version 1.2 - 2000/12/13</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="#faq">FAQ, DTD, external resources</a> |
| <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. "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/ant/release/v1.2/bin/"> |
| http://jakarta.apache.org/builds/ant/release/v1.2/bin/</a>. |
| If you like living on the edge, you can download the latest version from <a |
| href="http://jakarta.apache.org/builds/ant/nightly/">http://jakarta.apache.org/builds/ant/nightly/</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/ant/release/v1.2/src/"> |
| http://jakarta.apache.org/builds/ant/release/v1.2/src/</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 compliant 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>Set the JAVA_HOME environment variable. This should be set to the |
| directory where the JDK is installed. See <a href="#installing">Installing Ant</a> |
| for examples on how to do this for your operating system.</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=<directory to install Ant> dist</code></p> |
| </blockquote> |
| <p>for Windows, and</p> |
| <blockquote> |
| <p><code>build.sh -Dant.dist.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 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 or JDK 1.3, <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, otherwise it searches in the parent directory and so on |
| until the root of the filesystem has been reached. To make Ant use |
| another buildfile, use the commandline option <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 (see the <a href="#property">property task</a>). |
| 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. This can also be used (and is the only way since Java can not access them) |
| to have access to your environment variables, just pass -DMYVAR=%MYVAR% (Windows) or |
| -DMYVAR=$MYVAR (Unix) to Ant, you can then access these variables inside your build-file |
| as ${MYVAR}.</p> |
| <p>Two 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 one or more targets that should be executed. When omitted the target that is mentioned in the <i>default</i> attribute of the project is |
| used.</p> |
| <p>The <i>-projecthelp</i> option gives a list of this projects targets. First those with a description and then those without one.</p> |
| <p>Commandline option summary:</p> |
| <pre>ant [options] [target [target2 [target3] ...]] |
| Options: |
| -help print this message |
| -projecthelp print project help information |
| -version print the version information and exit |
| -quiet be extra quiet |
| -verbose be extra verbose |
| -debug print debugging information |
| -emacs produce logging information without adornments |
| -logfile <file> use given file for log |
| -logger <classname> the class which is to perform logging |
| -listener <classname> add an instance of class as a project listener |
| -buildfile <file> use given buildfile |
| -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>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> |
| <p>Each element of the buildfile can have an <code>id</code> attribute and |
| can later be referred to by the value supplied to this. The value has |
| to be unique.</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">No</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 must be omitted in the |
| project tag. If neither the attribute not the property have |
| been set, the parent directory of the build file will be used.</td> |
| <td align="center" valign="top">No</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><target name="A"/> |
| <target name="B" depends="A"/> |
| <target name="C" depends="B"/> |
| <target name="D" depends="C,B,A"/></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 (or |
| unless) a property has been set. This allows, for example, better |
| control on the building process depending on the state of the system |
| (java version, OS, command line properties, etc...). To make target |
| <i>sense</i> this property you should add the <i>if</i> (or |
| <i>unless</i>) attribute with the name of the property that the target |
| should react to, for example</p> |
| <blockquote> |
| <pre><target name="build-module-A" if="module-A-present"/></pre> |
| <pre><target name="build-own-fake-module-A" unless="module-A-present"/></pre> |
| </blockquote> |
| <p>If no <i>if</i> and no <i>unless</i> attribute is present, the target will |
| always be executed.</p> |
| <p>It is a good practice to place your <a |
| href="#tstamp">tstamp</a> tasks in a so called initialization target, on which |
| all other targets depend. Make sure that target is always the first one in |
| the depends list of the other targets. In this manual, most initialization targets |
| have the name "init".</p> |
| <p>The optional <i>description</i> attribute can be used to provide a one line description of this target that is printed by the <i>-projecthelp</i> commandline option.</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 target.</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> |
| <tr> |
| <td valign="top">unless</td> |
| <td valign="top">the name of the property that must not be set in order |
| for this target to execute.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">description</td> |
| <td valign="top">a short description of this targets function.</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> |
| <p>All tasks share a <code>taskname</code> attribute. The value of |
| this attribute will be used in the logging messages generated by |
| Ant.</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>Built in Properties</h3> |
| <p>Ant provides access to all system properties as if they had been |
| defined using a property task, for example ${os.name} expands to the |
| name of the operating system.</p> |
| <p>In addition Ant knows some built in properties:</p> |
| <ul> |
| <li>basedir - the absolute path of the project's basedir (as set |
| with the basedir attribute of <project>).</li> |
| <li>ant.file - the absolute path of the build file.</li> |
| <li>ant.java.version - the JVM version Ant detected. Currently it |
| can hold the values "1.1", "1.2" and |
| "1.3".</li> |
| </ul> |
| <h3>Example</h3> |
| <blockquote> |
| <pre> |
| <project name="MyProject" default="dist" basedir="."> |
| |
| <!-- set global properties for this build --> |
| <property name="src" value="." /> |
| <property name="build" value="build" /> |
| <property name="dist" value="dist" /> |
| |
| <target name="prepare"> |
| <!-- Create the time stamp --> |
| <tstamp/> |
| <!-- Create the build directory structure used by compile --> |
| <mkdir dir="${build}" /> |
| </target> |
| |
| <target name="compile" depends="prepare"> |
| <!-- Compile the java code from ${src} into ${build} --> |
| <javac srcdir="${src}" destdir="${build}" /> |
| </target> |
| |
| <target name="dist" depends="compile"> |
| <!-- Create the ${dist}/lib directory --> |
| <mkdir dir="${dist}/lib" /> |
| |
| <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file --> |
| <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}" /> |
| </target> |
| |
| <target name="clean"> |
| <!-- Delete the ${build} and ${dist} directory trees --> |
| <delete dir="${build}" /> |
| <delete dir="${dist}" /> |
| </target> |
| </project> |
| </pre> |
| </blockquote> |
| |
| <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>. </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@ is found in a file but no |
| filter is associated with that token, no changes take place. So, no escaping |
| method is present, but as long as you choose appropriate names for your tokens, |
| this should not cause problems.</p> |
| |
| <h3><a name="path">PATH like structures</a></h3> |
| <p>You can specify PATH and CLASSPATH variables using both |
| ":" and ";" as separator characters, Ant will |
| convert it to the correct character of the current operating |
| system.</p> |
| <p>Wherever PATH like values need to be specified a nested element can |
| be used. This takes the general form of</p> |
| <pre> |
| <classpath> |
| <pathelement path="${classpath}" /> |
| <pathelement location="lib/helper.jar" /> |
| </classpath> |
| </pre> |
| <p>The <code>location</code> attribute specifies a single file or |
| directory relative to the project's base directory (or an absolute |
| filename), while the <code>path</code> attribute accepts ":" |
| or ";" separated lists of locations. The <code>path</code> |
| attribute is intended to be used with predefined paths - in any other |
| case multiple elements with <code>location</code> attributes should be |
| preferred.</p> |
| <p>As a shortcut the surrounding PATH element supports path and |
| location attributes of its own, so</p> |
| <pre> |
| <classpath> |
| <pathelement path="${classpath}" /> |
| </classpath> |
| </pre> |
| <p>can be abreviated to</p> |
| <pre> |
| <classpath path="${classpath}" /> |
| </pre> |
| <p>In addition, <a href="#fileset">FileSet</a>s can be specified via |
| nested <code><fileset></code> elements. The order in which the files |
| building up FileSet are added to the PATH like structure is not |
| defined.</p> |
| <pre> |
| <classpath> |
| <pathelement path="${classpath}" /> |
| <fileset dir="lib"> |
| <include name="**/*.jar" /> |
| </fileset;> |
| <pathelement location="classes" /> |
| </classpath> |
| </pre> |
| <p>Builds a PATH which holds the value of <code>${classpath}</code> |
| followed by all JAR files in the <code>lib</code> directory, followed |
| by the <code>classes</code> directory.</p> |
| <p>If you want to use the same PATH like structure for several tasks, |
| you can define them with a <code><path></code> element at the |
| same level as <em>target</em>s and reference them via their |
| <em>id</em> attribute - see <a href="#references">References</a> for an |
| example.</p> |
| <p>A PATH like structure can include a reference to another PATH like |
| structure via a nested <code><path></code> elements.</p> |
| <pre> |
| <path id="base.path"> |
| <pathelement path="${classpath}" /> |
| <fileset dir="lib"> |
| <include name="**/*.jar" /> |
| </fileset;> |
| <pathelement location="classes" /> |
| </path> |
| |
| <path id="tests.path"> |
| <path refid="base.path" /> |
| <pathelement location="testclasses" /> |
| </path> |
| </pre> |
| |
| <h3><a name="arg">Command line arguments</a></h3> |
| |
| <p>Several tasks take arguments that shall be passed to another |
| process on the command line. To make it easier to specify arguments |
| that contain space characters, nested elements can be used.</p> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td width="12%" valign="top"><b>Attribute</b></td> |
| <td width="78%" valign="top"><b>Description</b></td> |
| <td width="10%" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">value</td> |
| <td valign="top">a single command line argument, can contain space |
| characters.</td> |
| <td align="center" rowspan="4">Exactly one of these.</td> |
| </tr> |
| <tr> |
| <td valign="top">line</td> |
| <td valign="top">a space delimited list of command line arguments.</td> |
| </tr> |
| <tr> |
| <td valign="top">file</td> |
| <td valign="top">The name of a file as a single command line |
| argument. Will be replaced with the absolute filename of the file |
| by Ant.</td> |
| </tr> |
| <tr> |
| <td valign="top">path</td> |
| <td valign="top">A string that shall be treated as a PATH like |
| string as a single command line argument. You can use ; or : as |
| path separators and Ant will convert it to the platform's local |
| conventions.</td> |
| </tr> |
| </table> |
| <h4>Examples</h4> |
| <blockquote><pre> |
| <arg value="-l -a" /> |
| </pre></blockquote> |
| <p>is a single command line argument containing a space character.</p> |
| <blockquote><pre> |
| <arg line="-l -a" /> |
| </pre></blockquote> |
| <p>stands for two separate command line arguments.</p> |
| <blockquote><pre> |
| <arg path="/dir;/dir2:\dir3" /> |
| </pre></blockquote> |
| <p>is a single command line argument with value |
| <code>\dir;\dir2;\dir3</code> on DOS based systems and |
| <code>/dir:/dir2:/dir3</code> on Unix like systems.</p> |
| <h3><a name="references">References</a></h3> |
| <p>The <code>id</code> attribute of the buildfile's elements can be |
| used to refer to them. This can useful if you are going to replicate |
| the same snippet of XML over and over again - using a |
| <code><classpath></code> structure more than once for |
| example.</p> |
| <p>The following example</p> |
| <blockquote><pre> |
| <project ... > |
| <target ... > |
| <rmic ...> |
| <classpath> |
| <pathelement location="lib/" /> |
| <pathelement path="${java.class.path}/" /> |
| <pathelement path="${additional.path}" /> |
| </classpath> |
| </rmic> |
| </target> |
| |
| <target ... > |
| <javac ...> |
| <classpath> |
| <pathelement location="lib/" /> |
| <pathelement path="${java.class.path}/" /> |
| <pathelement path="${additional.path}" /> |
| </classpath> |
| </javac> |
| </target> |
| </project> |
| </pre></blockquote> |
| <p>could be rewritten as</p> |
| <blockquote><pre> |
| <project ... > |
| <path id="project.class.path"> |
| <pathelement location="lib/" /> |
| <pathelement path="${java.class.path}/" /> |
| <pathelement path="${additional.path}" /> |
| </path> |
| |
| <target ... > |
| <rmic ...> |
| <classpath refid="project.class.path" /> |
| </rmic> |
| </target> |
| |
| <target ... > |
| <javac ...> |
| <classpath refid="project.class.path" /> |
| </javac> |
| </target> |
| </project> |
| </pre></blockquote> |
| <p>All tasks that use nested elements for <a |
| href="#patternset">PatternSet</a>s, <a href="#fileset">FileSet</a>s or |
| <a href="#path">PATH like structures</a> accept references to these |
| structures as well.</p> |
| <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 "shorthand", if a pattern ends with '/' or '\', then '**' |
| is appended. E.g. "mypackage/test/" is interpreted as were it "mypackage/test/**".</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> |
| <copy todir="${dist}" > |
| <fileset dir="${src}" |
| includes="**/images/*" |
| excludes="**/*.gif" |
| /> |
| </copy></pre> |
| <p>This copies all files in directories called "images", that are |
| located in the directory tree "${src}" to the destination "${dist}", |
| but excludes all "*.gif" files from the copy.</p> |
| <p> This example can also be expressed using nested elements as |
| <pre> |
| <copy todir="${dist}" > |
| <fileset dir="${src}" /> |
| <include name="**/images/*"/> |
| <exclude name="**/*.gif" /> |
| </fileset> |
| </copy> |
| </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> "**/*~", |
| "**/#*#", |
| "**/%*%", |
| "**/CVS", |
| "**/CVS/*", |
| "**/.cvsignore" |
| </pre> |
| If you do not want these default excludes applied, you may disable them with the |
| <code>defaultexcludes="no"</code> attribute.</p> |
| <h3><a name="patternset">PatternSets</a></h3> |
| <p>Patterns can be grouped to sets and later be referenced by their id |
| attribute. They are defined via a <code>patternset</code> element - |
| which can appear nested into a <a href="#fileset">FileSet</a> or a |
| directory based task that constitutes an implicit FileSet. In addition |
| <code>patternset</code>s can be defined at the same level as |
| <code>target</code> - i.e. as children of <code>project</code></p> |
| <p>Patterns can be specified by nested <code><include></code> or |
| <code><exclude></code> elements or 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> |
| </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> |
| </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> |
| </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> |
| </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> |
| </tr> |
| </table> |
| <h4>Examples</h4> |
| <blockquote><pre> |
| <patternset id="non.test.sources" > |
| <include name="**/*.java" /> |
| <exclude name="**/*Test*" /> |
| </patternset> |
| </pre></blockquote> |
| <p>Builds a set of patterns, that matches all <code>.java</code> files |
| that do not contain the text <code>Test</code> in their name. This set |
| can be <a href="#references">referred</a> to via |
| <code><patternset refid="non.test.sources" |
| /></code> by tasks that support this feature or by FileSets.</p> |
| <p>Note that while the includes and excludes attributes accept |
| multiple elements separated by commas or spaces, the nested |
| <include> and <exclude> elements expect their name |
| attribute to hold a single pattern.</p> |
| <h3><a name="fileset">FileSets</a></h3> |
| <p>FileSets are groups of files. These files can be found in a |
| directory tree starting in a base directory and are matched by |
| patterns taken from a number of <a |
| href="#patternset">PatternSets</a>. FileSets can appear inside task |
| that support this feature or at the same level as <code>target</code> |
| - i.e. as children of <code>project</code>.</p> |
| <p>PatternSets can be specified as nested |
| <code><patternset></code> |
| elements. In addition FileSet holds an implicit PatternSet and |
| supports the nested <code><include></code> and |
| <code><exclude></code> elements of PatternSet directly as well |
| as PatternSet's 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">dir</td> |
| <td valign="top">The root of the directory tree of this FileSet.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">defaultexcludes</td> |
| <td valign="top">indicates whether default excludes should be used or not |
| ("yes"/"no"). Default excludes are used when omitted.</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> |
| </table> |
| <h4>Examples</h4> |
| <blockquote><pre> |
| <fileset dir="${server.src}" > |
| <patternset id="non.test.sources" > |
| <include name="**/*.java" /> |
| <exclude name="**/*Test*" /> |
| </patternset> |
| </fileset> |
| </pre></blockquote> |
| <p>Groups all files in directory <code>${server.src}</code> that are Java |
| source files and don't have the text <code>Test</code> in their |
| name.</p> |
| <blockquote><pre> |
| <fileset dir="${client.src}" > |
| <patternset refid="non.test.sources" /> |
| </fileset> |
| </pre></blockquote> |
| <p>Groups all files in directory <code>${client.src}</code> using the |
| same patterns as the example before.</p> |
| <hr> |
| <h2><a name="tasks">Built in tasks</a></h2> |
| <ul> |
| <li><a href="#ant">Ant</a></li> |
| <li><a href="#antcall">AntCall</a></li> |
| <li><a href="#antstructure">AntStructure</a></li> |
| <li><a href="#available">Available</a></li> |
| <li><a href="#chmod">Chmod</a></li> |
| <li><a href="#copy">Copy</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="#execon">ExecOn</a></li> |
| <li><a href="#fail">Fail</a></li> |
| <li><a href="#filter">Filter</a></li> |
| <li><a href="#fixcrlf">FixCRLF</a></li> |
| <li><a href="#genkey">GenKey</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="#mail">Mail</a></li> |
| <li><a href="#mkdir">Mkdir</a></li> |
| <li><a href="#move">Move</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="#signjar">SignJar</a></li> |
| <li><a href="sql.html">Sql</a></li> |
| <li><a href="#style">Style</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="#unzip">Unjar</a></li> |
| <li><a href="#untar">Untar</a></li> |
| <li><a href="#unzip">Unwar</a></li> |
| <li><a href="#unzip">Unzip</a></li> |
| <li><a href="#uptodate">Uptodate</a></li> |
| <li><a href="#war">War</a></li> |
| <li><a href="#zip">Zip</a></li> |
| </ul> |
| <hr> |
| <h2><a name="ant">Ant</a></h2> |
| <h3>Description</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>). You can set properties |
| in the new project from the old project by using nested property tags. This |
| allows you to parameterize your subprojects.</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. Defaults to "build.xml".</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. |
| Defaults to the current directory.</td> |
| <td valign="top" align="center">No</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> |
| <pre> |
| <ant antfile="subproject/subbuild.xml" dir="subproject" target="compile" /> |
| |
| <ant dir="subproject" /> |
| |
| <ant antfile="subproject/property_based_subbuild.xml"> |
| <property name="param1" value="version 1.x" /> |
| <property file="config/subproject/default.properties" /> |
| </ant> |
| </pre> |
| <hr> |
| <h2><a name="antcall">AntCall</a></h2> |
| <h3>Description</h3> |
| <p>Call another target within the same build-file optionally specifying some |
| properties (param's in this context)</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">target</td> |
| <td valign="top">The target to execute.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>param</h4> |
| <p>Specifies the properties to set before running the specified target. See <a |
| href="#property">property</a> for usage guidelines.</p> |
| <h3>Examples</h3> |
| <pre> |
| <target name="default"> |
| <antcall target="doSomethingElse"> |
| <param name="param1" value="value"/> |
| </antcall> |
| </target> |
| |
| <target name="doSomethingElse"> |
| <echo message="param1=${param1}"/> |
| </target> |
| </pre> |
| <p>Will run the target 'doSomethingElse' and echo 'param1=value'.</p> |
| <hr> |
| <h2><a name="antstructure">AntStructure</a></h2> |
| <h3>Description</h3> |
| <p>Generates a DTD for Ant build files which contains information |
| about all tasks currently known to Ant.</p> |
| <p>Note that the DTD generated by this task is incomplete, you can |
| always add XML entities using <a |
| href="#taskdef"><code><taskdef></code></a>. See <a |
| href="http://www.sdv.fr/pages/casa/html/ant-dtd.en.html">here</a> for |
| a way to get around this problem.</p> |
| <p>This task doesn't know about required attributes, all will be |
| listed as <code>#IMPLIED</code>.</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">output</td> |
| <td valign="top">file to write the DTD to.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <blockquote><pre> |
| <antstructure output="project.dtd" /> |
| </pre></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>If the resource is present, the property value is set to true by |
| default, otherwise the property is not set. You can set the value to |
| something specific by using the value attribute.</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">value</td> |
| <td valign="top">the value to set the property to. Defaults to "true".</td> |
| <td valign="top" align="center">No</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> |
| <tr> |
| <td valign="top">classpath</td> <td valign="top">the classpath to |
| use when looking up <code>classname</code>.</td> <td |
| align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>classpath</h4> |
| <p><code>Available</code>'s <em>classpath</em> attribute is a <a |
| href="#path">PATH like structure</a> and can also be set via a nested |
| <em>classpath</em> element.</p> |
| <h3>Examples</h3> |
| <pre> <available classname="org.whatever.Myclass" property="Myclass.present" /></pre> |
| <p>sets the property <code><i>Myclass.present</i></code> to the value "true" |
| 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 or all files inside specified directories. Right now it has effect only under Unix. |
| The permissions are also UNIX style, like the argument for the chmod command.</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.</p> |
| <p>This task holds an implicit <a href="#fileset">FileSet</a> and |
| supports all of FileSet's attributes and nested elements |
| directly. More FileSets can be specified using nested |
| <code><fileset></code> elements.</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 or single directory of which the permissions |
| must be changed.</td> |
| <td valign="top" valign="middle" rowspan="2">exactly one of the two or nested <code><fileset></code> elements.</td> |
| </tr> |
| <tr> |
| <td valign="top">dir</td> |
| <td valign="top">the directory which holds the files whose permissions |
| must be changed.</td> |
| </tr> |
| <tr> |
| <td valign="top">perm</td> |
| <td valign="top">the new permissions.</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">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 |
| ("yes"/"no"). Default excludes are used when omitted.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">parallel</td> |
| <td valign="top">process all specified files using a single |
| <code>chmod</code> command. Defaults to true.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">type</td> |
| <td valign="top">One of <em>file</em>, <em>dir</em> or |
| <em>both</em>. If set to <em>file</em>, only the permissions of |
| plain files are going to be changed. If set to <em>dir</em>, only |
| the directories are considered.</td> |
| <td align="center" valign="top">No, default is <em>file</em></td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <blockquote> |
| <p><code><chmod file="${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> |
| <blockquote> |
| <pre> |
| <chmod dir="${dist}/bin" perm="ugo+rx" includes="**/*.sh" /> |
| </pre> |
| </blockquote> |
| <p>makes all ".sh" files below <code>${dist}/bin</code> |
| readable and executable for anyone on a UNIX system.</p> |
| <blockquote> |
| <pre> |
| <chmod perm="g+w" /> |
| <fileset dir="shared/sources1" > |
| <exclude name="**/trial/**" /> |
| </fileset> |
| <fileset refid="other.shared.sources" /> |
| </chmod> |
| </pre> |
| </blockquote> |
| <p>makes all files below <code>shared/sources1</code> (except those |
| below any directory named trial) writable for members of the same |
| group on a UNIX system. In addition all files belonging to a FileSet |
| with <code>id</code> <code>other.shared.sources</code> get the same |
| permissions.</p> |
| <hr> |
| <h2><a name="copy">Copy</a></h2> |
| <h3>Description</h3> |
| <p>Copies a file or Fileset to a new file or directory. Files are |
| only copied if the source file is newer than the destination file, |
| or when the destination file does not exist. However, you can explicitly |
| overwrite files with the <var>overwrite</var> attribute.</p> |
| <p><a href="#fileset">FileSet</a>s are used to select files to copy. |
| To use a fileset, the <var>todir</var> attribute must be set.</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 copy.</td> |
| <td valign="top" align="center">One of either <var>file</var> or |
| at least one nested fileset element.</td> |
| </tr> |
| <tr> |
| <td valign="top">tofile</td> |
| <td valign="top">The file to copy to.</td> |
| <td valign="top" align="center" rowspan="2">With the <var>file</var> attribute, |
| either <var>tofile</var> or <var>todir</var> can be used. With nested filesets, |
| only <var>todir</var> is allowed.</td> |
| </tr> |
| <tr> |
| <td valign="top">todir</td> |
| <td valign="top">The directory to copy to.</td> |
| </tr> |
| <tr> |
| <td valign="top">overwrite</td> |
| <td valign="top">Overwrite existing files even if the destination |
| files are newer. Defaults to "no".</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. Defaults to "no".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">flatten</td> |
| <td valign="top">Ignore directory structure of source directory, |
| copy all files into a single directory, specified by the <var>todir</var> |
| attribute. Defaults to "no".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">includeEmptyDirs</td> |
| <td valign="top">Copy empty directories included with the nested FileSet(s). |
| Defaults to "yes".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <p><b>Copy a single file</b></p> |
| <pre> |
| <copy file="myfile.txt" tofile="mycopy.txt" /> |
| </pre> |
| <p><b>Copy a file to a directory</b></p> |
| <pre> |
| <copy file="myfile.txt" todir="../some/dir/tree" /> |
| </pre> |
| <p><b>Copy a directory to another directory</b></p> |
| <pre> |
| <copy todir="../new/dir"> |
| <fileset dir="src_dir"/> |
| </copy> |
| </pre> |
| <p><b>Copy a set of files to a directory</b></p> |
| <pre> |
| <copy todir="../dest/dir" > |
| <fileset dir="src_dir" > |
| <exclude name="**/*.java" /> |
| </fileset> |
| </copy> |
| |
| <copy todir="../dest/dir" > |
| <fileset dir="src_dir" excludes="**/*.java" /> |
| </copy> |
| </pre> |
| <hr> |
| <h2><a name="copydir">Copydir</a></h2> |
| <h3><i>Deprecated</i></h3> |
| <p><i>This task has been deprecated. Use the Copy task instead.</i></p> |
| <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.</p> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>src</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</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">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 |
| ("yes"/"no"). 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">flatten</td> |
| <td valign="top">ignore directory structure of source directory, |
| copy all files into a single directory - specified by the dest |
| attribute (default is false).</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> <copydir src="${src}/resources" |
| dest="${dist}" |
| /></pre> |
| <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>.</p> |
| <pre> <copydir src="${src}/resources" |
| dest="${dist}" |
| includes="**/*.java" |
| excludes="**/Test.java" |
| /></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> <copydir src="${src}/resources" |
| dest="${dist}" |
| includes="**/*.java" |
| excludes="mypackage/test/**" /></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><i>Deprecated</i></h3> |
| <p><i>This task has been deprecated. Use the Copy task instead.</i></p> |
| <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> |
| <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> |
| <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>Handles packages/modules retrieved from a |
| <a href="http://www.cvshome.org/">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 "checkout"</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">No, default is project's basedir.</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">suppress informational messages.</td> |
| <td align="center" valign="top">No, default "false"</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 "false"</td> |
| </tr> |
| <tr> |
| <td valign="top">output</td> |
| <td valign="top">the file to direct standard output from the command.</td> |
| <td align="center" valign="top">No, default output to ANT Log as MSG_INFO.</td> |
| </tr> |
| <tr> |
| <td valign="top">error</td> |
| <td valign="top">the file to direct standard error from the command.</td> |
| <td align="center" valign="top">No, default error to ANT Log as MSG_WARN.</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <cvs cvsRoot=":pserver:anoncvs@jakarta.apache.org:/home/cvspublic" |
| package="jakarta-tools" |
| dest="${ws.dir}" |
| /></pre> |
| <p>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> |
| <pre> <cvs dest="${ws.dir}" command="update" /></pre> |
| <p>updates the package/module that has previously been checked out into |
| "${ws.dir}".</p> |
| <pre> <cvs command="-q diff -u -N" output="patch.txt"/></pre> |
| <p>silently (-q) creates a file called patch.txt which contains a unified (-u) diff which includes new files added via "cvs add" (-N) and can be used as input to patch.</p> |
| <pre> <cvs command="update -A -d"/></pre> |
| <p>Updates from the head of repository ignoring sticky bits (-A) and creating any new directories as necessary (-d).</p> |
| <p>Note: the text of the command is passed to cvs "as-is" so any cvs options should appear before the command, and any command options should appear after the command as in the diff example above. See <a href="http://www.cvshome.org/docs/manual/index.html">the cvs manual</a> for details, specifically the <a href="http://www.cvshome.org/docs/manual/cvs_16.html">Guide to CVS commands</a></p> |
| <hr> |
| <h2><a name="delete">Delete</a></h2> |
| <h3>Description</h3> |
| <p>Deletes either a single file, all files in a specified directory and its |
| sub-directories, or a set of files specified by one or more <a href="#fileset">FileSet</a>s. |
| When specifying a set of files, empty directories are <em>not</em> removed.</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">verbose</td> |
| <td valign="top">Show name of each deleted file ("true"/"false"). |
| Default is "false" when omitted.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">includes</td> |
| <td valign="top"><i>Deprecated.</i> 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"><i>Deprecated.</i> 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"><i>Deprecated.</i> 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"><i>Deprecated.</i> 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"><i>Deprecated.</i> Indicates whether default excludes should be used or not |
| ("yes"/"no"). Default excludes are used when omitted.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <delete file="/lib/ant.jar" /></pre> |
| <p>deletes the file <code>/lib/ant.jar</code>.</p> |
| <pre> <delete dir="lib" /></pre> |
| <p>deletes all files in the <code>/lib</code> directory.</p> |
| <pre> <delete> |
| <fileset dir="." includes="**/*.bak" /> |
| </delete> |
| </pre> |
| <p>deletes all files with the extension "<code>.bak</code>" from the current directory |
| and any sub-directories.</p> |
| <hr> |
| <h2><a name="deltree">Deltree</a></h2> |
| <h3><i>Deprecated</i></h3> |
| <p><i>This task has been deprecated. Use the Delete task instead.</i></p> |
| <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> <deltree dir="dist" /></pre> |
| <p>deletes the directory <code>dist</code>, including its files and |
| subdirectories.</p> |
| <pre> <deltree dir="${dist}" /></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 or 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">message</td> |
| <td valign="top">the message to echo.</td> |
| <td valign="top" align="center">Yes, unless data is included in a |
| character section within this element.</td> |
| </tr> |
| <tr> |
| <td valign="top">file</td> |
| <td valign="top">the file to write the message to.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">append</td> |
| <td valign="top">Append to an existing file?</td> |
| <td valign="top" align="center">No - default is false.</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <echo message="Hello world" /></pre> |
| <pre> |
| <echo> |
| This is a longer message stretching over |
| two lines. |
| </echo> |
| </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 with all command line |
| arguments. <b>deprecated, use executable and nested |
| <code><arg></code> elements instead</b>.</td> |
| <td align="center" rowspan="2">Exactly one of the two.</td> |
| </tr> |
| <tr> |
| <td valign="top">executable</td> |
| <td valign="top">the command to execute without any command line |
| arguments.</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">No</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">No</td> |
| </tr> |
| <tr> |
| <td valign="top">timeout</td> |
| <td valign="top">Stop the command if it doesn't finish within the |
| specified time (given in milliseconds).</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">failonerror</td> |
| <td valign="top">Stop the buildprocess if the command exits with a |
| returncode other than 0.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <blockquote> |
| <p><code><exec dir="${src}" executable="dir" os="windows" |
| output="dir.txt" /></code></p> |
| </blockquote> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>arg</h4> |
| <p>Command line arguments should be specified as nested |
| <code><arg></code> elements. See <a |
| href="index.html#arg">Command line arguments</a>.</p> |
| <h4><a name="env">env</a></h4> |
| <p>It is possible to specify environment variables to pass to the |
| system command via nested <code><env></code> elements.</p> |
| <p>Please note that the environment of the current Ant process is |
| <b>not</b> passed to the system command if you specify variables using |
| <code><env></code>.</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">key</td> |
| <td valign="top">The name of the environment variable.</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">value</td> |
| <td valign="top">The literal value for the environment variable.</td> |
| <td align="center" rowspan="3">Exactly one of these.</td> |
| </tr> |
| <tr> |
| <td valign="top">path</td> |
| <td valign="top">The value for a PATH like environment |
| variable. You can use ; or : as path separators and Ant will |
| convert it to the platform's local conventions.</td> |
| </tr> |
| <tr> |
| <td valign="top">file</td> |
| <td valign="top">The value for the environment variable. Will be |
| replaced by the absolute filename of the file by Ant.</td> |
| </tr> |
| </table> |
| <h5>Examples</h5> |
| <blockquote><pre> |
| <exec executable="emacs" > |
| <env key="DISPLAY" value=":1.0" /> |
| </exec> |
| </pre></blockquote> |
| <p>starts <code>emacs</code> on display 1 of the X Window System.</p> |
| <blockquote><pre> |
| <exec ... > |
| <env key="PATH" path="${java.library.path}:${basedir}/bin" /> |
| </exec> |
| </pre></blockquote> |
| <p>adds <code>${basedir}/bin</code> to the <code>PATH</code> of the |
| system command.</p> |
| <p><b>Note:</b> Although it may work for you to specify arguments using |
| a simple arg-element and seperate them by spaces it may fail if you switch to |
| a newer version of the JDK. JDK < 1.2 will pass these as separate arguments |
| to the program you are calling, JDK >= 1.2 will pass them as a single |
| argument and cause most calls to fail.</p> |
| <p><b>Note2:</b> If you are using Ant on Windows and a new DOS-Window pops up |
| for every command which is excuted this may be a problem of the JDK you are using. |
| This problem may occur with all JDK's < 1.2.</p> |
| <hr> |
| <h2><a name="execon">ExecOn</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> |
| <p>The files and/or directories of a number of <a |
| href="#fileset">FileSet</a>s are passed as arguments to the system |
| command. At least one nested <code><fileset></code> is required.</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">executable</td> |
| <td valign="top">the command to execute without any command line |
| arguments.</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">No</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">No</td> |
| </tr> |
| <tr> |
| <td valign="top">timeout</td> |
| <td valign="top">Stop the command if it doesn't finish within the |
| specified time (given in milliseconds).</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">failonerror</td> |
| <td valign="top">Stop the buildprocess if the command exits with a |
| returncode other than 0.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">parallel</td> |
| <td valign="top">Run the command only once, appending all files as |
| arguments. Defaults to true. If false, command will be executed |
| once for every file.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">type</td> |
| <td valign="top">One of <em>file</em>, <em>dir</em> or |
| <em>both</em>. If set to <em>file</em>, only the names of plain |
| files will be sent to the command. If set to <em>dir</em>, only |
| the names of directories are considered.</td> |
| <td align="center" valign="top">No, default is <em>file</em></td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>fileset</h4> |
| <p>You can use any number of nested <code><fileset></code> |
| elements to define the files for this task and refer to |
| <code><fileset></code>s defined elsewhere.</p> |
| <h4>arg</h4> |
| <p>Command line arguments should be specified as nested |
| <code><arg></code> elements. See <a |
| href="index.html#arg">Command line arguments</a>.</p> |
| <h4>env</h4> |
| <p>It is possible to specify environment variables to pass to the |
| system command via nested <code><env></code> elements. See the |
| description in the section about <a href="#env">exec</a></p> |
| <p>Please note that the environment of the current Ant process is |
| <b>not</b> passed to the system command if you specify variables using |
| <code><env></code>.</p> |
| <h3>Examples</h3> |
| <blockquote><pre> |
| <execon executable="ls" > |
| <arg value="-l" /> |
| <fileset dir="/tmp"> |
| <patternset> |
| <exclude name="**/*.txt" /> |
| </patternset> |
| </fileset> |
| <fileset refid="other.files" /> |
| </execon> |
| </pre></blockquote> |
| <p>invokes <code>ls -l</code>, adding the absolute filenames of all |
| files below <code>/tmp</code> not ending in <code>.txt</code> and all |
| files of the FileSet with <code>id</code> <code>other.files</code> to |
| the command line.</p> |
| <hr> |
| <h2><a name="fail">Fail</a></h2> |
| <h3>Description</h3> |
| <p>Exits the current build (just throwing a BuildException), optionally printing additional 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">message</td> |
| <td valign="top">A message giving further information on why the build exited</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <fail/></pre> |
| <p>will exit the current build with no further information given. |
| <pre> |
| BUILD FAILED |
| |
| build.xml:4: No message |
| </pre> |
| </p> |
| <pre> <fail message="Something wrong here."/></pre> |
| <p>will exit the current build and print something like the following to whereever |
| your output goes: |
| <pre> |
| BUILD FAILED |
| |
| build.xml:4: Something wrong here. |
| </pre> |
| </p> |
| <hr> |
| <h2><a name="filter">Filter</a></h2> |
| <h3>Description</h3> |
| <p>Sets a token filter for this project or read multiple token filter from |
| an input file and sets these as filters. |
| Token filters are used by all tasks that perform file copying operations |
| through the Project commodity methods.</p> |
| <p>Note 1: the token string must not contain the separators chars (@).<br> |
| Note 2: Either token and value attributes must be provided, or only the |
| filterfile 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">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> |
| <tr> |
| <td valign="top">filtersfile</td> |
| <td valign="top">The file from which the filters must be read. This file must be a formatted as a property file. </td> |
| <td align="center" valign="top">Yes*</td> |
| </tr> |
| </table> |
| <p>* see notes 1 and 2 above parameters table.</p> |
| <h3>Examples</h3> |
| <pre> <filter token="year" value="2000" /> |
| <copy todir="${dest.dir}"> |
| <fileset dir="${src.dir}" /> |
| </copy></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> |
| <pre> <filter filterfile="deploy_env.properties" /></pre> |
| will read all property entries from the <i>deploy_env.properties</i> file |
| and set these as filters. |
| |
| <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.</p> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>srcdir</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</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 |
| ("yes"/"no"). 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 precede 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">tablength</td> |
| <td valign="top">The number of characters a TAB stop corresponds to. |
| Must be a positive power of 2, default for this parameter is 8.</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> <fixcrlf srcdir="${src}" |
| cr="remove" eof="remove" |
| includes="**/*.sh" |
| /></pre> |
| <p>Removes carriage return and eof characters from the shell scripts. Tabs and |
| spaces are left as is. |
| <pre> <fixcrlf srcdir="${src}" |
| cr="add" |
| includes="**/*.bat" |
| /></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> <fixcrlf srcdir="${src}" |
| tabs="add" |
| includes="**/Makefile" |
| /></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> <fixcrlf srcdir="${src}" |
| tabs="remove" |
| includes="**/README*" |
| /></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="genkey">GenKey</a></h2> |
| <h3>Description</h3> |
| <p>Generates a key in keystore.</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">alias</td> |
| <td valign="top">the alias to add under</td> |
| <td valign="top" align="center">Yes.</td> |
| </tr> |
| <tr> |
| <td valign="top">storepass</td> |
| <td valign="top">password for keystore integrity.</td> |
| <td valign="top" align="center">Yes.</td> |
| </tr> |
| <tr> |
| <td valign="top">keystore</td> |
| <td valign="top">keystore location</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">storetype</td> |
| <td valign="top">keystore type</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">keypass</td> |
| <td valign="top">password for private key (if different)</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">sigalg</td> |
| <td valign="top">the algorithm to use in signing</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">keyalg</td> |
| <td valign="top">the method to use when generating name-value pair</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">verbose</td> |
| <td valign="top">(true | false) verbose output when signing</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">dname</td> |
| <td valign="top">The distinguished name for entity</td> |
| <td valign="top" align="center">Yes if dname element unspecified</td> |
| </tr> |
| <tr> |
| <td valign="top">validity</td> |
| <td valign="top">(integer) indicates how many days certificate is valid</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">keysize</td> |
| <td valign="top">(integer) indicates the size of key generated</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Alternatively you can specify the distinguished name by creating a sub-element named dname and populating it with param elements that have a name and a value. When using the subelement it is automatically encoded properly and , are replace |
| <p>The following two examples are identical: </p> |
| |
| <h3>Examples</h3> |
| <blockquote> |
| <p><code><genkey alias="apache-group" storepass="secret" |
| dname="CN=Ant Group, OU=Jakarta Division, O=Apache.org, C=US" /></code></p> |
| </blockquote> |
| |
| <blockquote> |
| <pre><code><genkey alias="apache-group" storepass="secret" > |
| <dname> |
| <param name="CN" value="Ant Group"/> |
| <param name="OU" value="Jakarta Division"/> |
| <param name="O" value="Apache.Org"/> |
| <param name="C" value="US"/> |
| </dname> |
| </genkey></code></pre> |
| </blockquote> |
| <hr> |
| <h2><a name="get">Get</a></h2> |
| <h3>Description</h3> |
| <p>Gets a file from a 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 significantly slower than loading a compressed |
| archive with http/ftp.</p> |
| |
| The <i>usetimestamps</i> option enables you to control downloads so that the remote file is |
| only fetched if newer than the local copy. If there is no local copy, the download always takes |
| place. When a file is downloaded, the timestamp of the downloaded file is set to the remote timestamp, |
| if the JVM is Java1.2 or later. |
| NB: This timestamp facility only works on downloads using the HTTP protocol. |
| <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 progress information ("on"/"off").</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> |
| <tr> |
| <td valign="top">usetimestamps</td> |
| <td valign="top">conditionally download a file based on the timestamp of the local copy. |
| HTTP only</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <get src="http://jakarta.apache.org/" dest="help/index.html" /></pre> |
| <p>Gets the index page of http://jakarta.apache.org/, and stores it in the file <code>help/index.html</code>.</p> |
| |
| <pre> <get src="http://jakarta.apache.org/builds/tomcat/nightly/ant.zip" |
| dest="optional.jar" |
| verbose="true" |
| usetimestamps="true"/></pre> |
| <p> |
| Gets the nightly ant build from the tomcat distribution, if the local copy |
| is missing or out of date. Uses the verbose option |
| for progress information. |
| </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 ".gz" extension removed if |
| present). If <i>dest</i> is omitted, 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><gunzip src="test.tar.gz"/></code></p> |
| </blockquote> |
| <p>expands <i>test.tar.gz</i> to <i>test.tar</i></p> |
| <blockquote> |
| <p><code><gunzip src="test.tar.gz" dest="test2.tar"/></code></p> |
| </blockquote> |
| <p>expands <i>test.tar.gz</i> to <i>test2.tar</i></p> |
| <blockquote> |
| <p><code><gunzip src="test.tar.gz" dest="subdir"/></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><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>Note that file permissions will not be stored in the resulting jarfile.</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.</p> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>basedir</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</p> |
| <p>You can also use nested file sets for more flexibility, and specify |
| multiple ones to merge together different trees of files into one JAR. |
| See the <a href="#zip">Zip</a> task for more details and examples.</p> |
| <p>If the manifest is omitted, a simple one will be supplied by Ant. |
| You should not include <samp>META-INF/MANIFEST.MF</samp> in your set of files. |
| <p>The <code>whenempty</code> parameter controls what happens when no files match. |
| If <code>create</code> (the default), the JAR is created anyway with only a manifest. |
| If <code>skip</code>, the JAR is not created and a warning is issued. |
| If <code>fail</code>, the JAR is not created and the build is halted with an error. |
| <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">No</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">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 |
| ("yes"/"no"). 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> |
| <tr> |
| <td valign="top">whenempty</td> |
| <td valign="top">Behavior to use if no files match.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" /></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> <jar jarfile="${dist}/lib/app.jar" |
| basedir="${build}/classes" |
| excludes="**/Test.class" |
| /></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> <jar jarfile="${dist}/lib/app.jar" |
| basedir="${build}/classes" |
| includes="mypackage/test/**" |
| excludes="**/Test.class" |
| /></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> |
| <pre> <jar jarfile="${dist}/lib/app.jar"> |
| <fileset dir="${build}/classes" |
| excludes="**/Test.class" |
| /> |
| <fileset dir="${src}/resources"/> |
| </jar></pre> |
| <p>jars all files in the <code>${build}/classes</code> directory and also |
| in the <code>${src}/resources</code> directory together 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. |
| If there are files such as <code>${build}/classes/mypackage/MyClass.class</code> |
| and <code>${src}/resources/mypackage/image.gif</code>, they will appear |
| in the same directory in the JAR (and thus be considered in the same package |
| by Java).</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. <b>deprecated, use nested <code><arg></code> |
| elements instead.</b></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">classpathref</td> |
| <td valign="top">the classpath to use, given as <a |
| href="#references">reference</a> to a PATH defined elsewhere.</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). <b>deprecated, use nested |
| <code><jvmarg></code> elements instead.</b></td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">maxmemory</td> |
| <td valign="top">Max amount of memory to allocate to the forked VM |
| (ignored if fork is disabled)</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">failonerror</td> |
| <td valign="top">Stop the buildprocess if the command exits with a |
| returncode other than 0. Only available if fork is true.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">dir</td> |
| <td valign="top">The directory to invoke the VM in. (ignored if |
| fork is disabled)</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>arg and jvmarg</h4> |
| <p>Use nested <code><arg></code> and <code><jvmarg></code> |
| elements to specify arguments for the or the forked VM. See <a |
| href="index.html#arg">Command line arguments</a>.</p> |
| <h4>sysproperty</h4> |
| <p>Use nested <code><sysproperty></code> |
| elements to specify system properties required by the class. |
| These properties will be made available to the VM during the execution |
| of the class (either ANT's VM or the forked VM). The attributes |
| for this element are the same as for <a href="index.html#env">environment |
| variables</a>.</p> |
| <h4>classpath</h4> |
| <p><code>Java</code>'s <em>classpath</em> attribute is a <a |
| href="#path">PATH like structure</a> and can also be set via a nested |
| <em>classpath</em> element.</p> |
| <h5>Example</h5> |
| <pre> |
| <java classname="test.Main" > |
| <arg value="-h" /> |
| <classpath> |
| <pathelement location="\test.jar" /> |
| <pathelement path="${java.class.path}" /> |
| </classpath> |
| </java> |
| </pre> |
| <h3>Examples</h3> |
| <pre> <java classname="test.Main" /></pre> |
| <pre> <java classname="test.Main" |
| fork="yes" > |
| <sysproperty key="DEBUG" value="true" /> |
| <arg value="-h" /> |
| <jvmarg value="-Xrunhprof:cpu=samples,file=log.txt,depth=3" /> |
| </java> |
| </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>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.</p> |
| <p>It is possible to use different compilers. This can be selected with the |
| "build.compiler" property. There are four 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> |
| <li>jvc (the Command-Line Compiler from Microsoft's SDK for Java / |
| Visual J++)</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, unless nested <code><src></code> elements are present.</td> |
| </tr> |
| <tr> |
| <td valign="top">destdir</td> |
| <td valign="top">location where to store the class files.</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 |
| ("yes"/"no"). 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">classpathref</td> |
| <td valign="top">the classpath to use, given as <a |
| href="#references">reference</a> to a PATH defined elsewhere.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">bootclasspathref</td> |
| <td valign="top">location of bootstrap class files, given as by <a |
| href="#references">reference</a> to a PATH defined elsewhere.</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">encoding</td> |
| <td valign="top">encoding of source files.</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 ("off").</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 ("off").</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 ("off").</td> |
| <td align="center" valign="top">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> |
| <tr> |
| <td valign="top">verbose</td> |
| <td valign="top">asks the compiler for verbose output.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">depend</td> <td valign="top">enables dependency |
| tracking for compilers that support this (jikes and classic)</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| |
| <h3>Parameters specified as nested elements</h3> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>srcdir</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</p> |
| <h4>src, classpath, bootclasspath and extdirs</h4> |
| <p><code>Javac</code>'s <em>srcdir</em>, <em>classpath</em>, |
| <em>bootclasspath</em> and <em>extdirs</em> attributes are <a |
| href="#path">PATH like structure</a> and can also be set via nested |
| <em>src</em>, <em>classpath</em>, <em>bootclasspath</em> and |
| <em>extdirs</em> elements respectively.</p> |
| |
| <h3>Examples</h3> |
| <pre> <javac srcdir="${src}" |
| destdir="${build}" |
| classpath="xyz.jar" |
| debug="on" |
| /></pre> |
| <p>compiles all .java files under the directory <code>${src}</code>, and stores |
| the .class files in the directory <code>${build}</code>. |
| The classpath used contains <code>xyz.jar</code>, and debug information is on.</p> |
| <pre> <javac srcdir="${src}" |
| destdir="${build}" |
| includes="mypackage/p1/**,mypackage/p2/**" |
| excludes="mypackage/p1/testpackage/**" |
| classpath="xyz.jar" |
| debug="on" |
| /></pre> |
| <p>compiles .java files under the directory <code>${src}</code>, and stores the |
| .class files in the directory <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> |
| |
| <pre> <javac srcdir="${src}:${src2}" |
| destdir="${build}" |
| includes="mypackage/p1/**,mypackage/p2/**" |
| excludes="mypackage/p1/testpackage/**" |
| classpath="xyz.jar" |
| debug="on" |
| /></pre> |
| |
| <p>is the same as the previous example with the addition of a second source path, defined by |
| the propery <code>src2</code>. This can also be represented using nested elements as follows |
| |
| <pre> <javac destdir="${build}" |
| classpath="xyz.jar" |
| debug="on"> |
| <src path="${src}" /> |
| <src path="${src2}" /> |
| <include name="mypackage/p1/**" /> |
| <include name="mypackage/p2/**" /> |
| <exclude name="mypackage/p1/testpackage/**" /> |
| </javac></pre> |
| |
| <p><b>Note:</b> If you are using Ant on Windows and a new DOS-Window pops up |
| for every use of an external compiler this may be a problem of the JDK you are using. |
| This problem may occur with all JDK's < 1.2.</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 |
| "changed" 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" rowspan="2">At least one of the two or nested |
| <code><sourcepath></code></td> |
| </tr> |
| <tr> |
| <td valign="top">sourcepathref</td> |
| <td valign="top">Specify where to find source files by <a |
| href="#references">reference</a> to a PATH defined elsewhere.</td> |
| <td align="center" valign="top">all</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">Comma 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">Comma 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">classpathref</td> |
| <td valign="top">Specify where to find user class files by <a |
| href="#references">reference</a> to a PATH defined elsewhere.</td> |
| <td align="center" valign="top">all</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">bootclasspathref</td> |
| <td valign="top">Override location of class files loaded by the |
| bootstrap class loader by <a href="#references">reference</a> to a |
| PATH defined elsewhere.</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 documentation (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">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">docletpathref</td> |
| <td valign="top">Specifies the path to the doclet class file that |
| is specified with the -doclet option by <a |
| href="#references">reference</a> to a PATH defined elsewhere.</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 nested elements</h3> |
| <h4>link</h4> |
| <p>Create link to javadoc output at the given URL. This performs the |
| same role as the link and linkoffline attributes. You can use either |
| syntax (or both at once), but with the nested elements you can easily |
| specify multiple occurrences of the arguments.</p> |
| <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> |
| <p>Separates packages on the overview page into whatever groups you |
| specify, one group per table. This performs the same role as the group |
| attribute. You can use either syntax (or both at once), but with the |
| nested elements you can easily specify multiple occurrences of the |
| arguments.</p> |
| |
| <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> |
| |
| <h4>doclet</h4> |
| <p>The doclet nested element is used to specify the doclet that javadoc will |
| use to process the input source files. A number of the standard javadoc arguments |
| are actually arguments of the standard doclet. If these are specified in the javadoc |
| task's attributes, they will be passed to the doclet specified in the |
| <code><doclet></code> nested element. Such attributes should only be specified, |
| therefore, if they can be interpreted by the doclet in use. |
| |
| <p>If the doclet requires additional parameters, these can be specified with |
| <code><param></code> elements within the <code><doclet></code> |
| element. These paramaters are restricted to simple strings. An example usage |
| of the doclet element is shown below: |
| |
| <pre> <javadoc ...> |
| <doclet name="theDoclet" |
| path="path/to/theDoclet"> |
| <param name="-foo" value="foovalue"/> |
| <param name="-bar" value="barvalue"/> |
| </doclet> |
| </javadoc> |
| </pre> |
| |
| <h4>sourcepath, classpath and bootclasspath</h4> |
| <p><code>Javadoc</code>'s <em>sourcepath</em>, <em>classpath</em> and |
| <em>bootclasspath</em> attributes are <a href="#path">PATH like |
| structure</a> and can also be set via nested <em>sourcepath</em>, |
| <em>classpath</em> and <em>bootclasspath</em> elements |
| respectively.</p> |
| |
| <h3>Example</h3> |
| <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>"> |
| <group title="Group 1 Packages" packages="com.dummy.test.a*"/> |
| <group title="Group 2 Packages" packages="com.dummy.test.b*"/> |
| <link offline="true" href="http://java.sun.com/products/jdk/1.2/docs/api/" packagelistLoc="C:\tmp"/> |
| <link href="http://developer.java.sun.com/developer/products/xml/docs/api/"/> |
| </javadoc></pre> |
| |
| <hr> |
| <h2><a name="mail">Mail</a></h2> |
| <h3>Description</h3> |
| <p>A task to send SMTP email.</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">from</td> |
| <td valign="top">Email address of sender.</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">tolist</td> |
| <td valign="top">Comma-separated list of recipients.</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">message</td> |
| <td valign="top">Message to send in the body of the email.</td> |
| <td align="center" valign="middle" rowspan="2">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">files</td> |
| <td valign="top">Filename(s) of text to send in the body of the email. |
| Multiple files are comma-separated.</td> |
| </tr> |
| <tr> |
| <td valign="top">mailhost</td> |
| <td valign="top">Host name of the mail server.</td> |
| <td align="center" valign="top">No, default to "localhost"</td> |
| </tr> |
| <tr> |
| <td valign="top">subject</td> |
| <td valign="top">Email subject line.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> |
| <mail from="me" tolist="you" subject="Results of nightly build" |
| files="build.log"/></pre> |
| <p>Sends an eMail from <i>me</i> to <i>you</i> with a subject of |
| <i>Results of nightly build</i> and includes the contents of <i>build.log</i> |
| in the body of the message.</p> |
| <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><mkdir dir="${dist}" /></pre> |
| <p>creates a directory <code>${dist}</code>.</p> |
| <pre><mkdir dir="${dist}/lib" /></pre> |
| <p>creates a directory <code>${dist}/lib</code>.</p> |
| <hr> |
| <h2><a name="move">Move</a></h2> |
| <h3>Description</h3> |
| <p>Moves a file to a new file or directory, or sets of files to |
| a new directory. By default, the |
| destination file is overwritten if it already exists. When <var>overwrite</var> is |
| turned off, then files are only moved if the source file is newer than |
| the destination file, or when the destination file does not exist.</p> |
| <p><a href="#fileset">FileSet</a>s are used to select sets of files |
| to move to the <var>todir</var> 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 move</td> |
| <td valign="top" align="center">One of <var>file</var> or |
| at least one nested fileset element</td> |
| </tr> |
| <tr> |
| <td valign="top">tofile</td> |
| <td valign="top">the file to move to</td> |
| <td valign="top" align="center" rowspan="2">With the <var>file</var> attribute, |
| either <var>tofile</var> or <var>todir</var> can be used. With a nested fileset, |
| only <var>todir</var> is allowed.</td> |
| </tr> |
| <tr> |
| <td valign="top">todir</td> |
| <td valign="top">the directory to move to</td> |
| </tr> |
| <tr> |
| <td valign="top">overwrite</td> |
| <td valign="top">overwrite existing files even if the destination |
| files are newer (default is "true")</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 move. See the <a href="#filter">filter</a> task for a description of |
| how filters work.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">flatten</td> |
| <td valign="top">ignore directory structure of source directory, |
| copy all files into a single directory, specified by the <var>todir</var> |
| attribute (default is "false").</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">includeEmptyDirs</td> |
| <td valign="top">Copy empty directories included with the nested FileSet(s). |
| Defaults to "yes".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <p><b>Move a single file (rename a file)</b></p> |
| <pre> |
| <move file="file.orig" tofile="file.moved" /> |
| </pre> |
| <p><b>Move a single file to a directory</b></p> |
| <pre> |
| <move file="file.orig" todir="dir/to/move/to" /> |
| </pre> |
| <p><b>Move a directory to a new directory</b></p> |
| <pre> |
| <move todir="new/dir/to/move/to"> |
| <fileset dir="src/dir"/> |
| </move> |
| </pre> |
| <p><b>Move a set of files to a new directory</b></p> |
| <pre> |
| <move todir="some/new/dir" > |
| <fileset dir="my/src/dir" > |
| <include name="**/*.jar" /> |
| <exclude name="**/ant.jar" /> |
| </fileset> |
| </move> |
| </pre> |
| <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">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> <patch patchfile="module.1.0-1.1.patch" /></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> <patch patchfile="module.1.0-1.1.patch" strip="1" /></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. |
| <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 four ways to set properties:</p> |
| <ul> |
| <li>By supplying both the <i>name</i> and <i>value</i> attribute.</li> |
| <li>By supplying both the <i>name</i> and <i>refid</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="5">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">refid</td> |
| <td valign="top"><a href="#references">Reference</a> to an object |
| defined elsewhere. Only yields reasonable results for references |
| to <a href="#path">PATH like structures</a> or properties.</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> |
| <tr> |
| <td valign="top">location</td> |
| <td valign="top">Sets the property to the absolute filename of the |
| given file. If the value of this attribute is an absolute path, it |
| is left unchanged (with / and \ characters converted to the |
| current platforms conventions). Otherwise it is taken as a path |
| relative to the project's basedir and expanded.</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <property name="foo.dist" value="dist" /></pre> |
| <p>sets the property <code>foo.dist</code> to the value "dist".</p> |
| <pre> <property file="foo.properties" /></pre> |
| <p>reads a set of properties from a file called "foo.properties".</p> |
| <pre> <property resource="foo.properties" /></pre> |
| <p>reads a set of properties from a resource called "foo.properties".</p> |
| <p>Note that you can reference a global properties file for all of your Ant |
| builds using the following: |
| <pre> <property file="${user.home}/.ant-global.properties" /></pre> |
| <p>since the "user.home" property is defined by the Java virtual machine |
| to be your home directory. This technique is more appropriate for Unix than |
| Windows since the notion of a home directory doesn't exist on Windows. On the |
| JVM that I tested, the home directory on Windows is "C:\". Different JVM |
| implementations may use other values for the home directory on Windows. |
| <hr> |
| <h2><a name="rename">Rename</a></h2> |
| <h3><i>Deprecated</i></h3> |
| <p><i>This task has been deprecated. Use the Move task instead.</i></p> |
| <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> <rename src="foo.jar" dest="${name}-${version}.jar" /></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 renaming <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> |
| <p>If you want to replace a text that crosses line boundaries, you |
| must use a nested <code><replacetoken></code> element.</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 align="center" rowspan="2">Exactly one of the two.</td> |
| </tr> |
| <tr> |
| <td valign="top">dir</td> |
| <td valign="top">The base directory to use when replacing a token in |
| multiple files.</td> |
| </tr> |
| <tr> |
| <td valign="top">token</td> |
| <td valign="top">the token which must be replaced.</td> |
| <td valign="top" align="center">Yes, unless a nested <code>replacetoken</code> |
| element is used.</td> |
| </tr> |
| <tr> |
| <td valign="top">value</td> |
| <td valign="top">the new value for the token. When omitted, an empty string |
| ("") 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 |
| ("yes"/"no"). Default excludes are used when omitted.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <replace file="${src}/index.html" token="@@@" value="wombat" /></pre> |
| <p>replaces occurrences of the string "@@@" with the string |
| "wombat", in the file <code>${src}/index.html</code>.</p> |
| <h3>Parameters specified as nested elements</h3> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> as well as the |
| nested <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</p> |
| <p>If either the text you want to replace or the replacement text |
| cross line boundaries, you can use nested elements to specify |
| them.</p> |
| <h3>Examples</h3> |
| <blockquote><pre> |
| <replace dir="${src}" value="wombat"> |
| <include name="**/*.html" /> |
| <replacetoken><[CDATA[multi line |
| token]]></replacetoken> |
| </replace> |
| </pre></blockquote> |
| <p>replaces occurrences of the string "multi |
| line<em>\n</em>token" with the string "wombat", in all |
| HTML files in the directory <code>${src}</code>.Where <em>\n</em> is |
| the platform specific line separator.</p> |
| <blockquote><pre> |
| <replace file="${src}/index.html"> |
| <replacetoken><[CDATA[two line |
| token]]></replacetoken> |
| <replacevalue><[CDATA[two line |
| token]]></replacevalue> |
| </replace> |
| </pre></blockquote> |
| <hr> |
| <h2><a name="rmic">Rmic</a></h2> |
| <h3>Description</h3> |
| <p>Runs the rmic compiler for a certain class.</p> |
| <p>Rmic can be run on a single class (as specified with the classname |
| attribute) or a number of classes at once (all classes below base that |
| are neither _Stub nor _Skel classes).</p> |
| <p>It is possible to refine the set of files that are being rmiced. 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.</p> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>base</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</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">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">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> |
| <tr> |
| <td valign="top">classpathref</td> |
| <td valign="top">The classpath to use during compilation, given as <a |
| href="#references">reference</a> to a PATH defined elsewhere</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 |
| ("yes"/"no"). Default excludes are used when omitted.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">verify</td> |
| <td valign="top">check that classes implement Remote before handing them |
| to rmic (default is false)</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>classpath</h4> |
| <p><code>Rmic</code>'s <em>classpath</em> attribute is a <a |
| href="#path">PATH like structure</a> and can also be set via a nested |
| <em>classpath</em> elements.</p> |
| <h3>Examples</h3> |
| <pre> <rmic classname="com.xyz.FooBar" base="${build}/classes" /></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> |
| <pre> <rmic base="${build}/classes" includes="**/Remote*.class" /></pre> |
| <p>runs the rmic compiler for all classes with <code>.class</code> |
| files below <code>${build}/classes</code> whose classname starts with |
| <i>Remote</i>. The compiled files will be stored in the directory |
| <code>${build}/classes</code>.</p> |
| |
| <hr> |
| <h2><a name="signjar">SignJar</a></h2> |
| <h3>Description</h3> |
| <p>Signs a jar or zip file with the javasign command line tool.</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">jar</td> |
| <td valign="top">the jar file to sign</td> |
| <td valign="top" align="center">Yes.</td> |
| </tr> |
| <tr> |
| <td valign="top">alias</td> |
| <td valign="top">the alias to sign under</td> |
| <td valign="top" align="center">Yes.</td> |
| </tr> |
| <tr> |
| <td valign="top">storepass</td> |
| <td valign="top">password for keystore integrity.</td> |
| <td valign="top" align="center">Yes.</td> |
| </tr> |
| <tr> |
| <td valign="top">keystore</td> |
| <td valign="top">keystore location</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">storetype</td> |
| <td valign="top">keystore type</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">keypass</td> |
| <td valign="top">password for private key (if different)</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">sigfile</td> |
| <td valign="top">name of .SF/.DSA file</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">signedjar</td> |
| <td valign="top">name of signed JAR file</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">verbose</td> |
| <td valign="top">(true | false) verbose output when signing</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">internalsf</td> |
| <td valign="top">(true | false) include the .SF file inside the signature |
| block</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">sectionsonly</td> |
| <td valign="top">(true | false) don't compute hash of entire manifest</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <blockquote> |
| <p><code><signjar jar="${dist}/lib/ant.jar" |
| alias="apache-group" storepass="secret" /></code></p> |
| </blockquote> |
| <p>signs the ant.jar with alias "apache-group" accessing the |
| keystore and private key via "secret" password.</p> |
| <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.</p> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>basedir</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</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">extension</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. Permissible |
| 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 |
| ("yes"/"no"). Default excludes are used when omitted.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <blockquote> |
| <p><pre> |
| <style basedir="doc" destdir="build/doc" |
| extension="html" style="style/apache.xml"/> |
| </pre></p> |
| </blockquote> |
| <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.</p> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>basedir</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</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 |
| ("yes"/"no"). Default excludes are used when omitted.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <tar tarfile="${dist}/manual.tar" basedir="htdocs/manual" /> |
| <gzip zipfile="${dist}/manual.tar.gz" src="${dist}/manual.tar" /></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> <tar tarfile="${dist}/manual.tar" |
| basedir="htdocs/manual" |
| excludes="mydocs/**, **/todo.html" |
| /></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 "<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">classname</td> |
| <td valign="top">the full class name implementing the task</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> <td valign="top">the classpath to |
| use when looking up <code>classname</code>.</td> <td |
| align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>classpath</h4> |
| <p><code>Taskdef</code>'s <em>classpath</em> attribute is a <a |
| href="#path">PATH like structure</a> and can also be set via a nested |
| <em>classpath</em> element.</p> |
| <h3>Examples</h3> |
| <pre> <taskdef name="myjavadoc" classname="com.mydomain.JavadocTask" /></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 omitted |
| the current time is assumed.</p> |
| <h3>Examples</h3> |
| <pre> <touch file="myfile" /></pre> |
| <p>creates <code>myfile</code> if it doesn't exist and changes the |
| modification time to the current time.</p> |
| <pre> <touch file="myfile" datetime="06/28/2000 2:02 pm" /></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 "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 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> <tstamp/></pre> |
| <hr> |
| <h2><a name="uptodate">Uptodate</a></h2> |
| <h3>Description</h3> |
| <p>Sets a property if a Target file is more up to date than a set of |
| Source files. Source files are specified by nested <srcfiles> |
| elements, these are <a href="#fileset">FileSet</a>s.</p> |
| <p>The value part of the property being set is <i>true</i> if the timestamp of the |
| Target file is more recent than the timestamp of every Source file.</p> |
| <p>Normally, this task is used to set properties that are useful to avoid target |
| execution depending on the relative age of the specified files.</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">targetfile</td> |
| <td valign="top">the file for which we want to determine the status.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <uptodate property="xmlBuild.notRequired" targetfile="${deploy}\xmlClasses.jar" > |
| <srcfiles dir= "${src}/xml" includes="**/*.dtd" /> |
| </uptodate></pre> |
| <p>sets the property <code><i>xmlBuild.notRequired</i></code> to the value "true" |
| if the <i>${deploy}/xmlClasses.jar</i> is more up to date than any of the DTD files in the <i>${src}/xml</i> directory.</p> |
| <hr> |
| <h2><a name="unzip">Unjar/Unwar/Unzip</a></h2> |
| <h3>Description</h3> |
| <p>Unzips a zip-, war- or jarfile.</p> |
| <p>For JDK 1.1 "last modified time" field is set to current time instead of being |
| carried from zipfile.</p> |
| <p>File permissions will not be restored on extracted files.</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><unzip src="${tomcat_src}/tools-src.zip" dest="${tools.home}" |
| /></code></p> |
| </blockquote> |
| <hr> |
| <h2><a name="untar">Untar</a></h2> |
| <h3>Description</h3> |
| <p>Untars a tarfile.</p> |
| <p>File permissions will not be restored on extracted files.</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> |
| <gunzip src="tools.tar.gz"/><br> |
| <untar src="tools.tar" dest="${tools.home}"/> |
| </code></p> |
| </blockquote> |
| <hr> |
| <h2><a name="war">War</a></h2> |
| <h3>Description</h3> |
| <p>An extension of the <a href="#jar">Jar</a> task with special |
| treatment for files that should end up in the <code>WEB-INF/lib</code>, |
| <code>WEB-INF/classes</code> or <code>WEB-INF</code> directories of the Web |
| Application Archive.</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">warfile</td> |
| <td valign="top">the war-file to create.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">webxml</td> |
| <td valign="top">The deployment descriptor to use (WEB-INF/web.xml).</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">No</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">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 |
| ("yes"/"no"). 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> |
| <tr> |
| <td valign="top">whenempty</td> |
| <td valign="top">Behavior to use if no files match.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Nested elements</h3> |
| <h4>lib</h4> |
| <p>The nested <code>lib</code> element specifies a <a |
| href="#fileset">FileSet</a>. All files included in this fileset will |
| end up in the <code>WEB-INF/lib</code> directory of the war file.</p> |
| <h4>classes</h4> |
| <p>The nested <code>classes</code> element specifies a <a |
| href="#fileset">FileSet</a>. All files included in this fileset will |
| end up in the <code>WEB-INF/classes</code> directory of the war file.</p> |
| <h4>webinf</h4> |
| <p>The nested <code>webinf</code> element specifies a <a |
| href="#fileset">FileSet</a>. All files included in this fileset will |
| end up in the <code>WEB-INF</code> directory of the war file. If this |
| fileset includes a file named <code>web.xml</code>, the file is |
| ignored and you will get a warning.</p> |
| <h3>Examples</h3> |
| <p>Assume the following structure in the project's base directory: |
| <pre> |
| thirdparty/libs/jdbc1.jar |
| thirdparty/libs/jdbc2.jar |
| build/main/com/myco/myapp/Servlet.class |
| src/metadata/myapp.xml |
| src/html/myapp/index.html |
| src/jsp/myapp/front.jsp |
| </pre> |
| then the war file <code>myapp.war</code> created with |
| <pre> |
| <war warfile="myapp.war" webxml="src/metadata/myapp.xml"> |
| <fileset dir="src/html/myapp" /> |
| <fileset dir="src/jsp/myapp" /> |
| <lib dir="thirdparty/libs"> |
| <exclude name="jdbc1.jar" /> |
| </lib> |
| <classes dir="build/main" /> |
| </war> |
| </pre> |
| will consist of |
| <pre> |
| WEB-INF/web.xml |
| WEB-INF/lib/jdbc2.jar |
| WEB-INF/classes/com/myco/myapp/Servlet.class |
| META-INF/MANIFEST.MF |
| index.html |
| front.jsp |
| </pre> |
| using Ant's default manifest file. The content of |
| <code>WEB-INF/web.xml</code> is identical to |
| <code>src/metadata/myapp.xml</code>.</p> |
| <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>Note that file permissions will not be stored in the resulting zipfile.</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. |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>basedir</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</p> |
| <p>Or, you may place within it nested file sets, or references to file sets. |
| In this case <code>basedir</code> is optional; the implicit file set is <em>only used</em> |
| if <code>basedir</code> is set. You may use any mixture of the implicit file set |
| (with <code>basedir</code> set, and optional attributes like <code>includes</code> |
| and optional subelements like <code><include></code>); explicit nested |
| <code><fileset></code> elements so long as at least one fileset total is specified. The ZIP file will |
| only reflect the relative paths of files <em>within</em> each fileset.</p> |
| <p>The <code>whenempty</code> parameter controls what happens when no files match. |
| If <code>skip</code> (the default), the ZIP is not created and a warning is issued. |
| If <code>fail</code>, the ZIP is not created and the build is halted with an error. |
| If <code>create</code>, an empty ZIP file (explicitly zero entries) is created, |
| which should be recognized as such by compliant ZIP manipulation tools.</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">No</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">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 |
| ("yes"/"no"). Default excludes are used when omitted.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">whenempty</td> |
| <td valign="top">Behavior when no files match.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre> <zip zipfile="${dist}/manual.zip" |
| basedir="htdocs/manual" |
| /></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> <zip zipfile="${dist}/manual.zip" |
| basedir="htdocs/manual" |
| excludes="mydocs/**, **/todo.html" |
| /></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> <zip zipfile="${dist}/manual.zip" |
| basedir="htdocs/manual" |
| includes="api/**/*.html" |
| excludes="**/todo.html" |
| /></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> |
| <pre> <zip zipfile="${dist}/manual.zip"> |
| <fileset dir="htdocs/manual"/> |
| <fileset dir="." includes="ChangeLog.txt"/> |
| </zip></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, and also adds the file <code>ChangeLog.txt</code> in the |
| current directory. <code>ChangeLog.txt</code> will be added to the top of the ZIP file, just as if |
| it had been located at <code>htdocs/manual/ChangeLog.txt</code>.</p> |
| |
| <hr> |
| <h2><a name="optionaltasks">Optional tasks</a></h2> |
| <ul> |
| <li><a href="#cab">Cab</a></li> |
| <li><a href="#ftp">FTP</a></li> |
| <li><a href="javacc.html">JavaCC</a></li> |
| <li><a href="jlink.html">Jlink</a></li> |
| <li><a href="junit.html">JUnit</a></li> |
| <li><a href="native2ascii.html">Native2Ascii</a></li> |
| <li><a href="#netrexxc">NetRexxC</a></li> |
| <li><a href="P4desc.html">Perforce</a></li> |
| <li><a href="#renameexts">RenameExtensions</a></li> |
| <li><a href="#script">Script</a></li> |
| <li><a href="#vssget">VssGet</a></li> |
| <li><a href="ejb.html">EJB Tasks</a></li> |
| </ul> |
| <hr> |
| <h2><a name="cab">Cab</a></h2> |
| <h3>Description</h3> |
| <p>The cab task creates Microsoft cab archive files. It is invoked |
| similar to the <a href="#jar">jar</a> or <a href="#zip">zip</a> tasks. |
| This task will only work on Windows, and will be silently ignored on |
| other platforms. You must have the Microsoft cabarc tool available in |
| your executable path.</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.</p> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>basedir</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</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">cabfile</td> |
| <td valign="top">the name of the cab file to create.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">basedir</td> |
| <td valign="top">the directory to start archiving files from.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">verbose</td> |
| <td valign="top">set to "yes" if you want to see the output from |
| the cabarc tool. defaults to "no".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">compress</td> |
| <td valign="top">set to "no" to store files without compressing. |
| defaults to "yes".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">options</td> |
| <td valign="top">use to set additional command-line options for |
| the cabarc tool. should not normally be necessary.</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 ("yes"/"no"). Default excludes are used when omitted.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <blockquote><pre> |
| <cab cabfile="${dist}/manual.cab" |
| basedir="htdocs/manual" |
| /> |
| </pre></blockquote> |
| <p>cabs all files in the htdocs/manual directory in a file called |
| manual.cab in the ${dist} directory.</p> |
| <blockquote><pre> |
| <cab cabfile="${dist}/manual.cab" |
| basedir="htdocs/manual" |
| excludes="mydocs/**, **/todo.html" |
| /> |
| </pre></blockquote> |
| <p>cabs all files in the htdocs/manual directory in a file called |
| manual.cab in the ${dist} directory. Files in the directory mydocs, |
| or files with the name todo.html are excluded.</p> |
| <blockquote><pre> |
| <cab cabfile="${dist}/manual.cab" |
| basedir="htdocs/manual" |
| includes="api/**/*.html" |
| excludes="**/todo.html" |
| verbose="yes" |
| /> |
| </pre></blockquote> |
| <p>cab all files in the htdocs/manual directory in a file called |
| manual.cab in the ${dist} directory. Only html files under the |
| directory api are archived, and files with the name todo.html are |
| excluded. Output from the cabarc tool is displayed in the build |
| output.</p> |
| <hr> |
| <h2><a name="ftp">FTP</a></h2> |
| <h3>Description</h3> |
| <p>The ftp task implements a basic FTP client that can send, receive, |
| list, and delete files. See below for descriptions and examples of how |
| to perform each task.</p> |
| <p>The ftp task makes no attempt to determine what file system syntax is |
| required by the remote server, and defaults to Unix standards. |
| <i>remotedir</i> must be specified in the exact syntax required by the ftp |
| server. If the usual Unix conventions are not supported by the server, |
| <i>separator</i> can be used to set the file separator that should be used |
| instead.</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.</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">server</td> |
| <td valign="top">the address of the remote ftp server.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">port</td> |
| <td valign="top">the port number of the remote ftp server. |
| Defaults to port 21.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">userid</td> |
| <td valign="top">the login id to use on the ftp server.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">password</td> |
| <td valign="top">the login password to use on the ftp server.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">remotedir</td> |
| <td valign="top">the directory to which to upload files on the |
| ftp server.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">action</td> |
| <td valign="top">the ftp action to perform, defaulting to "send". |
| Currently supports"put", "get", |
| "del", and "list".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">binary</td> |
| <td valign="top">selects binary-mode ("yes") or text-mode |
| ("no") transfers. |
| Defaults to "yes"</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">verbose</td> |
| <td valign="top">displays information on each file transferred if set |
| to "yes". Defaults to "no".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">depends</td> |
| <td valign="top">transfers only new or changed files if set to |
| "yes". Defaults to "no".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">newer</td> |
| <td valign="top">a synonym for <i>depends</i>.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">separator</td> |
| <td valign="top">sets the file separator used on the ftp server. |
| Defaults to "/".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">listing</td> |
| <td valign="top">the file to write results of the "list" action. |
| Required for the "list" action, ignored otherwise.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Sending Files</h3> |
| <p>The easiest way to describe how to send files is with a couple of examples:</p> |
| <pre> |
| <ftp server="ftp.apache.org" |
| userid="anonymous" |
| password="me@myorg.com"> |
| <fileset dir="htdocs/manual" /> |
| </ftp> |
| </pre> |
| <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and |
| uploads all files in the <code>htdocs/manual</code> directory |
| to the default directory for that user.</p> |
| <pre> <ftp server="ftp.apache.org" |
| remotedir="incoming" |
| userid="anonymous" |
| password="me@myorg.com" |
| depends="yes" |
| > |
| <fileset dir="htdocs/manual" /> |
| </ftp></pre> |
| <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and |
| uploads all new or changed files in the <code>htdocs/manual</code> directory |
| to the <code>incoming</code> directory relative to the default directory |
| for <code>anonymous</code>.</p> |
| <pre> <ftp server="ftp.apache.org" |
| port="2121" |
| remotedir="/pub/incoming" |
| userid="coder" |
| password="java1" |
| depends="yes" |
| binary="no" |
| > |
| <fileset dir="htdocs/manual"> |
| <include name="**/*.html" /> |
| </fileset> |
| </ftp></pre> |
| <p>Logs in to <code>ftp.apache.org</code> at port <code>2121</code> as |
| <code>coder</code> with password <code>java1</code> and uploads all new or |
| changed HTML files in the <code>htdocs/manual</code> directory to the |
| <code>/pub/incoming</code> directory. The files are transferred in text |
| mode.</p> |
| <pre> <ftp server="ftp.nt.org" |
| remotedir="c:\uploads" |
| userid="coder" |
| password="java1" |
| separator="\" |
| verbose="yes" |
| > |
| <fileset dir="htdocs/manual"> |
| <include name="**/*.html" /> |
| </fileset> |
| </ftp></pre> |
| <p>Logs in to the Windows-based <code>ftp.nt.org</code> as |
| <code>coder</code> with password <code>java1</code> and uploads all |
| HTML files in the <code>htdocs/manual</code> directory to the |
| <code>c:\uploads</code> directory. Progress messages are displayed as each |
| file is uploaded.</p> |
| <h3>Getting Files</h3> |
| <p>Getting files from an FTP server works pretty much the same way as |
| sending them does. The only difference is that the nested filesets |
| use the remotedir attribute as the base directory for the files on the |
| FTP server, and the dir attribute as the local directory to put the files |
| into. The file structure from the FTP site is preserved on the local machine.</p> |
| <pre> |
| <ftp action="get" |
| server="ftp.apache.org" |
| userid="anonymous" |
| password="me@myorg.com"> |
| <fileset dir="htdocs/manual" > |
| <include name="**/*.html" /> |
| </fileset> |
| </ftp> |
| </pre> |
| <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and |
| recursively downloads all .html files from default directory for that user |
| into the <code>htdocs/manual</code> directory on the local machine.</p> |
| <h3>Deleting Files</h3> |
| As you've probably guessed by now, you use nested fileset elements to |
| select the files to delete from the remote FTP server. Again, the |
| filesets are relative to the remote directory, not a local directory. In |
| fact, the dir attribute of the fileset is ignored completely. |
| <pre> |
| <ftp action="del" |
| server="ftp.apache.org" |
| userid="anonymous" |
| password="me@myorg.com" > |
| <fileset> |
| <include name="**/*.tmp" /> |
| </fileset> |
| </ftp> |
| </pre> |
| <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and |
| tries to delete all *.tmp files from the default directory for that user. |
| If you don't have permission to delete a file, a BuildException is thrown.</p> |
| <h3>Listing Files</h3> |
| <pre> |
| <ftp action="list" |
| server="ftp.apache.org" |
| userid=quot;anonymous" |
| password="me@myorg.com" |
| listing="data/ftp.listing" > |
| <fileset> |
| <include name="**" /> |
| </fileset> |
| </ftp> |
| </pre> |
| <p>This provides a file listing in <code>data/ftp.listing</code> of all the files on |
| the FTP server relative to the default directory of the <code>anonymous</code> |
| user. The listing is in whatever format the FTP server normally lists files.</p> |
| <hr> |
| <h2><a name="netrexxc">NetRexxC</a></h2> |
| <h3>Description</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.</p> |
| <p>This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>srcdir</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</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 |
| ("yes"/"no"). 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><netrexxc srcDir="/source/project" |
| includes="vnr/util/*" |
| destDir="/source/project/build" |
| classpath="/source/project2/proj.jar" |
| comments="true" |
| crossref="false" replace="true" |
| keep="true" /></code> |
| </p> |
| </blockquote> |
| <hr> |
| <h2><a name="renameexts">RenameExtensions</a></h2> |
| <h3>Description</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. |
| This task forms an implicit <a href="#fileset">FileSet</a> and |
| supports all attributes of <code><fileset></code> |
| (<code>dir</code> becomes <code>srcDir</code>) as well as the nested |
| <code><include></code>, <code><exclude></code> and |
| <code><patternset></code> elements.</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 |
| ("yes"/"no"). 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><renameext srcDir="/source/project1" |
| includes="**" |
| excludes="**/samples/*" |
| fromExtension=".java.keep" |
| toExtension=".java" |
| replace="true" /> |
| </code> |
| </p> |
| </blockquote> |
| |
| <hr> |
| <h2><a name="script">Script</a></h2> |
| <h3>Description</h3> |
| <p>Execute a script in a |
| <a href="http://oss.software.ibm.com/developerworks/opensource/bsf/">BSF</a> supported language. |
| <p>All items (tasks, targets, etc) of the running project are |
| accessible from the script, using either their <code>name</code> or |
| <code>id</code> attributes.</p> |
| <p>Scripts can do almost anything a task written in Java could do.</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">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><pre> |
| <project name="squares" default="main" basedir="."> |
| |
| <target name="setup"> |
| |
| <script language="javascript"> <![CDATA[ |
| |
| for (i=1; i<=10; i++) { |
| echo = squares.createTask("echo"); |
| main.addTask(echo); |
| echo.setMessage(i*i); |
| } |
| |
| ]]> </script> |
| |
| </target> |
| |
| <target name="main" depends="setup" /> |
| |
| </project> |
| </pre></blockquote> |
| <p>generates</p> |
| <blockquote><pre> |
| setup: |
| |
| main: |
| 1 |
| 4 |
| 9 |
| 16 |
| 25 |
| 36 |
| 49 |
| 64 |
| 81 |
| 100 |
| |
| BUILD SUCCESSFUL |
| </pre></blockquote> |
| <p>Another example, using <a href="#references">references by id</a> |
| and two different scripting languages:</p> |
| <blockquote><pre> |
| <project name="testscript" default="main"> |
| <target name="sub"> |
| <echo id="theEcho" /> |
| </target> |
| |
| <target name="sub1"> |
| <script language="netrexx"><![CDATA[ |
| theEcho.setMessage("In sub1") |
| sub.execute |
| ]]></script> |
| </target> |
| |
| <target name="sub2"> |
| <script language="javascript"><![CDATA[ |
| theEcho.setMessage("In sub2"); |
| sub.execute(); |
| ]]></script> |
| </target> |
| |
| <target name="main" depends="sub1,sub2" /> |
| </project> |
| </pre></blockquote> |
| <p>generates</p> |
| <blockquote><pre> |
| sub1: |
| In sub1 |
| |
| sub2: |
| In sub2 |
| |
| main: |
| |
| BUILD SUCCESSFUL |
| </pre></blockquote> |
| <hr> |
| <h2><a name="vssget">VssGet</a></h2> |
| <h3>Description</h3> |
| Task to perform GET commands to Microsoft Visual Source Safe. |
| <p>If you specify two or more attributes from version, date and |
| label only one will be used in the order version, date, label.</p> |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <th>Attribute</th> |
| <th>Values</th> |
| <th>Required</th> |
| </tr> |
| <tr> |
| <td>login</td> |
| <td>username,password</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>vsspath</td> |
| <td>SourceSafe path</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>localpath</td> |
| <td>Override the working directory and get to the specified path</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>writable</td> |
| <td>true or false</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>recursive</td> |
| <td>true or false</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>version</td> |
| <td>a version number to get</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>date</td> |
| <td>a date stamp to get at</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>label</td> |
| <td>a label to get for</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>ssdir</td> |
| <td>directory where <code>ss.exe</code> resides. By default the |
| task expects it to be in the PATH.</td> |
| <td>No</td> |
| </tr> |
| </table> |
| <p>Note that only one of version, date or label should be specified</p> |
| <h3>Examples</h3> |
| <blockquote> |
| <pre> |
| <vssget localPath="C:\mysrc\myproject" |
| recursive="true" |
| label="Release1" |
| login="me,mypassword" |
| vsspath="/source/aProject" |
| writable="true"/> |
| </pre> |
| </blockquote> |
| <p>Does a get on the VSS-Project <i>$/source/aproject</i> using the username |
| <i>me</i> and the password <i>mypassword</i>. It will recursively get the files |
| which are labeled <i>Release1</i> and write them to the local directory |
| <i>C:\mysrc\myproject</i>. The local files will be writable.</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 representation 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 a single argument. The |
| name of the method must begin with "set", followed by the |
| attribute name, with the first character in uppercase, and the rest in |
| lowercase. The type of the attribute can be <code>String</code>, any |
| primitive type (they are converted for you from their String-representation |
| in the build-file. If you specify a boolean your method will be passed the value |
| <i>true</i> if the value specified in the build-file is one of "true", |
| "yes" or "on"), <code>Class</code>, <code>File</code> |
| (in which case the value of the attribute is interpreted relative to the |
| project's basedir) or any other type that has a constructor with a single |
| <code>String</code> argument</li> |
| <li>If your task has enumerated attributes, you should consider using |
| a subclass of org.apache.tools.ant.types.EnumeratedAttribute as argument |
| to your setter method. See org.apache.tools.ant.taskdefs.FixCRLF for |
| an example.</li> |
| <li>If the task should support character data, write a <code>public void |
| addText(String)</code> method.</li> |
| <li>For each nested element, write a create or add method. A create method |
| must be a <code>public</code> method that takes no arguments and returns |
| an Object type. The name of the create method must begin with |
| "create", followed by the element name. An add method must be |
| a <code>public void</code> method that takes a single argument of an |
| Object type with a no argument constructor. The name of the add method |
| must begin with "add", followed by the element name. |
| <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> |
| <h3>The life cycle of a task</h3> |
| <ol> |
| <li>The task gets instantiated using a no-arg constructor at parser |
| time. This means even tasks that are never executed get |
| instantiated.</li> |
| |
| <li>The tasks gets references to its project and location inside the |
| build file via their inherited <code>project</code> and |
| <code>location</code> variables.</li> |
| |
| <li>If the user specified an id attribute to this task, the project |
| registers a reference to this newly created task - at parser |
| time.</li> |
| |
| <li>The task gets a reference to the target it belongs to via its |
| inherited <code>target</code> variable.</li> |
| |
| <li><code>init()</code> is called at parser time.</li> |
| |
| <li>All child elements of the XML element corresponding to this task |
| are created via this task's <code>createXXX()</code> methods or |
| instantiated and added to this task via its <code>addXXX()</code> |
| methods - at parser time.</li> |
| |
| <li>All attributes of this task get set via their corresponding |
| <code>setXXX</code> methods - at runtime.</li> |
| |
| <li>The content character data sections inside the XML element |
| corresponding to this task is added to the task via its |
| <code>addText</code> method - at runtime.</li> |
| |
| <li>All attributes of all child elements get set via their corresponding |
| <code>setXXX</code> methods - at runtime.</li> |
| |
| <li><code>execute()</code> is called at runtime.</li> |
| |
| </ol> |
| <h3>Example</h3> |
| <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>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 "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>Add a <i>taskdef</i> element to your project. 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><?xml version="1.0"?> |
| |
| <project name="OwnTaskExample" default="main" basedir="."> |
| <taskdef name="mytask" classname="com.mydomain.MyVeryOwnTask"/> |
| |
| <target name="main"> |
| <mytask message="Hello World! MyVeryOwnTask works!" /> |
| </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="faq">FAQ, DTD, external resources</a></h2> |
| <p>There is an online FAQ for Ant at <a |
| href="http://jakarta.apache.org/jyve-faq/Turbine/screen/DisplayTopics/action/SetAll/project_id/2/faq_id/16">jakarta.apache.org</a>. This |
| FAQ is interactive, which means you can ask and answer questions |
| online.</p> |
| <p>One of the questions poping up quite often is "Is there a DTD for |
| buildfiles?". Please refer to the FAQ for an answer.</p> |
| <hr> |
| <h2><a name="feedback">Feedback</a></h2> |
| <p>To provide feedback on this software, please subscribe to the Ant User |
| Mail List (<a href="mailto:ant-user-subscribe@jakarta.apache.org">ant-user-subscribe@jakarta.apache.org</a>)</p> |
| <p>If you want to contribute to Ant or stay current with the latest |
| development, join the Ant Development Mail List (<a |
| href="mailto:ant-dev-subscribe@jakarta.apache.org">ant-dev-subscribe@jakarta.apache.org</a>)</p> |
| <p>Archives of both lists can be found at <a |
| href="http://archive.covalent.net/">http://archive.covalent.net/</a>. Many |
| thanks to Covalent Technologies. Another archive can be found at <a |
| href="http://marc.theaimsgroup.com">http://marc.theaimsgroup.com</a>. If |
| you know of any additional archive sites, please report to the |
| lists.</p> |
| <hr> |
| <p align="center">Copyright © 2000 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| |
| </html> |
| |
