| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Ant User Manual</title> |
| </head> |
| |
| <body> |
| |
| <center> |
| <h1>Ant User Manual</h1> |
| <p>by</p> |
| </center> |
| <!-- Names are in alphabetical order, on last name --> |
| <ul> |
| <li>Stephane Bailliez (<a href="mailto:sbailliez@imediation.com">sbailliez@imediation.com</a>)</li> |
| <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>Diane Holt (<a href="mailto:holtdl@yahoo.com">holtdl@yahoo.com</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>Erik Meade (<a href="mailto:emeade@geekfarm.org">emeade@geekfarm.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>Jon S. Stevens (<a href="mailto:jon@latchkey.com">jon@latchkey.com</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> |
| |
| <center> |
| <p>Version: @VERSION@<br> |
| $Id$</p> |
| </center> |
| |
| <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="#installing">Installing Ant</a></li> |
| <li><a href="#buildingant">Building 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="#bitasks">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 |
| <i>make</i>, without <i>make</i>'s wrinkles.</p> |
| <h3>Why?</h3> |
| <p>Why another build tool when there is already |
| <i>make</i>, |
| <i>gnumake</i>, |
| <i>nmake</i>, |
| <i>jam</i>, |
| and |
| others? Because all those tools have limitations that Ant's original author |
| couldn't live with when developing software across multiple platforms. |
| Make-like |
| tools are inherently shell-based: they evaluate a set of dependencies, |
| then execute commands not unlike what you would issue on a shell. |
| This means that you |
| can easily extend these tools by using or writing any program for the OS that |
| you are working on; however, this also means that you limit yourself to the OS, |
| or at least the OS type, such as Unix, that you are working on.</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 have yet another format to use and remember.</p> |
| <p>Ant is different. Instead of a model where it is extended with shell-based |
| commands, Ant is extended using Java classes. Instead of writing shell commands, |
| the configuration files are XML-based, calling out a target tree where various |
| tasks get executed. Each task is run by an object that implements a particular |
| Task interface.</p> |
| <p>Granted, this removes some of the expressive power that is inherent in being |
| able to construct a shell command such as |
| <nobr><code>`find . -name foo -exec rm {}`</code></nobr>, but it |
| gives you the ability to be cross-platform – to work anywhere and |
| everywhere. And |
| hey, if you really need to execute a shell command, Ant has an |
| <exec> task that |
| allows different commands to be executed based on the OS it is executing |
| on.</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> |
| Both the binary and source distributions of Ant include the reference implementation of JAXP 1.0. |
| Please see <a href="http://java.sun.com/xml/">http://java.sun.com/xml/</a> for more information. |
| If you wish to use a different JAXP-compliant parser, you should remove |
| <code>jaxp.jar</code> and <code>parser.jar</code> |
| from Ant's <code>lib/core</code> directory. |
| You can then either put the jars from your preferred parser into Ant's |
| <code>lib/core</code> directory or put the jars on the system classpath. |
| <p> |
| For the current version of Ant, you will also need a JDK installed on |
| your system, version 1.1 or later. A future version of Ant will require |
| JDK 1.2 or later. |
| </p> |
| |
| <hr> |
| <h2><a name="installing">Installing Ant</a></h2> |
| <p>The binary distribution of Ant consists of four directories: |
| <code>bin</code>, |
| <code>docs</code>, |
| <code>lib</code> and |
| <code>src</code>. Only the <code>bin</code> |
| and <code>lib</code> directories are required 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 <code>ANT_HOME</code> environment variable. |
| This should be set to the directory |
| that contains the <code>bin</code> and <code>lib</code> directories.</li> |
| <li>(Optionally) Set the <code>JAVA_HOME</code> environment variable. |
| (See the <a href="#advanced">Advanced</a> section below.) |
| 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> |
| <a name="advanced"> |
| <h3>Advanced</h3> |
| </a> |
| <p>There are lots of variants that can be used to run Ant. What you need is at |
| least the following:</p> |
| <blockquote> |
| 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 |
| (such as for the <a href="#javac">javac</a> task or the |
| <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 <code>bin</code> directory, will add |
| the required JDK classes automatically, if the <code>JAVA_HOME</code> |
| environment variable is set.</p> |
| <p>When you are executing platform-specific applications (such as 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 |
| the <code>antRun</code> shell script necessary to run exec's on Unix.</p> |
| </blockquote> |
| <hr> |
| <h2><a name="buildingant">Building Ant</a></h2> |
| <p>To build Ant, you should install the Ant source distribution. |
| While the binary distribution |
| includes the Ant source code, it is intended for reference purposes only. |
| The bootstrap and build scripts used to build Ant itself are not included |
| in the binary distribution. |
| <p> |
| <p>Once you have installed the source distribution, go to the |
| <code>jakarta-ant</code> directory.</p> |
| <p>Set the <code>JAVA_HOME</code> environment variable |
| 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>Make sure you have downloaded any auxilliary jars required to |
| build tasks you are interested in. These should either be available |
| on the classpath or added to Ant's <code>lib</code> |
| directory. The list of auxilliary tasks and requirements is in |
| <code>lib/README</code>.</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 -Ddist.dir=<<i>directory_to_contain_Ant_distribution</i>> dist</code> (<i>Windows</i>)</p> |
| <p><code>build.sh -Ddist.dir=<<i>directory_to_contain_Ant_distribution</i>> dist</code> (<i>Unix</i>)</p> |
| </blockquote> |
| <p>to create a binary distribution of Ant. This distribution can be |
| found in the directory you specified.</p> |
| |
| If you wish to install the build into the current <code>ANT_HOME</code> |
| directory, you can use: |
| <blockquote> |
| <p><code>build install</code> (<i>Windows</i>)</p> |
| <p><code>build.sh install</code> (<i>Unix</i>)</p> |
| </blockquote> |
| |
| You can avoid the lengthy Javadoc step, if desired, with: |
| <blockquote> |
| <p><code>build mininstall</code> (<i>Windows</i>)</p> |
| <p><code>build.sh mininstall</code> (<i>Unix</i>)</p> |
| </blockquote> |
| This will only install the <code>bin</code> and <code>lib</code> directories. |
| <p>Both the <code>install</code> and |
| <code>mininstall</code> targets will overwrite |
| the current Ant version in <code>ANT_HOME</code>. |
| |
| <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. If found, it uses that file as the |
| buildfile. If you use the <nobr><code>-find</code></nobr> option, |
| Ant will search for a buildfile in |
| the parent directory, and so on, until the root of the filesystem |
| has been reached. To make Ant use |
| another buildfile, use the command-line |
| option <code>-buildfile <i>file</i></code>, |
| where <i>file</i> is the buildfile you want to use.</p> |
| <p>You can also set properties that override properties specified in the |
| buildfile (see the <a href="#property">property</a> task). |
| This can be done with |
| the <nobr><code>-D<i>property</i>=<i>value</i></code></nobr> option, |
| where <i>property</i> is the name of the property, |
| and <i>value</i> is the value for that property. |
| This can also be used to have access to your environment variables |
| (and is the only way, since Java cannot access them). |
| Just pass <nobr><code>-DMYVAR=%MYVAR%</code></nobr> (Windows) or |
| <nobr><code>-DMYVAR=$MYVAR</code></nobr> (Unix) |
| to Ant – you can then access |
| these variables inside your buildfile as <code>${MYVAR}</code>.</p> |
| <p>Two more options are: <nobr><code>-quiet</code></nobr>, |
| which instructs Ant to print less |
| information on the console when running, and |
| <nobr><code>-verbose</code></nobr>, which causes Ant to print |
| additional information to the console.</p> |
| <p>It is also possible to specify one or more targets that should be executed. |
| When omitted, the target that is specified in the |
| <code>default</code> attribute of the <code><project></code> tag is |
| used.</p> |
| <p>The <nobr><code>-projecthelp</code></nobr> |
| option gives a list of this project's |
| targets. First those with a description, then those without one.</p> |
| <p>Command-line 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 <i>file</i> use given file for log output |
| -logger <i>classname</i> the class that is to perform logging |
| -listener <i>classname</i> add an instance of class as a project listener |
| -buildfile <i>file</i> use specified buildfile |
| -find <i>file</i> search for buildfile towards the root of the filesystem and use the first one found |
| -D<i>property</i>=<i>value</i> set <i>property</i> to <i>value</i> |
| </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>, setting the <code>build</code> property to the |
| value <code>build/classes</code>.</p> |
| |
| <h3>Running Ant by Hand</h3> |
| <p>If 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 your classpath to include: |
| <ul> |
| <li><code>ant.jar</code> |
| <li>jars/classes for your XML parser |
| <li>the JDK's required jar/zip files |
| </ul> |
| <hr> |
| <h2><a name="buildfile">Writing a Simple Buildfile</a></h2> |
| <p>Ant's buildfiles are written in XML. Each buildfile contains one project.</p> |
| <p>Each task 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. (For additional information, see the |
| <a href="#tasks"> Tasks</a> section below.)</p> |
| <h3>Projects</h3> |
| <p>A <i>project</i> 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 beforehand. When this is done, it must be omitted in the |
| project tag. If neither the attribute nor the property have |
| been set, the parent directory of the buildfile will be used.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <p>Each project defines one or more <i>targets</i>. |
| A target is a set of <i>tasks</i> you want |
| to be executed. When starting Ant, you can select which target(s) you |
| want to have executed. When no target is given, |
| the project's default is used.</p> |
| |
| <h3>Targets</h3> |
| <p>A target can depend on other targets. You might have a target for compiling, |
| for example, and a target for creating a distributable. You can only build a |
| distributable when you have compiled first, so the distribute target |
| <i>depends on</i> the compile target. Ant resolves these dependencies.</p> |
| <p>It should be noted, however, that Ant's <code>depends</code> attribute |
| only specifies the <i>order</i> in which targets should be executed – it |
| does not affect whether the target that specifies the dependency(s) gets |
| executed if the dependent target(s) did not (need to) run. |
| </p> |
| <p>Ant tries to execute the targets in the <code>depends</code> |
| 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 |
| <code>depends</code> 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 than one target |
| depends on it (see the previous example).</p> |
| <p>A target also has the ability to perform its execution if (or |
| unless) a property has been set. This allows, for example, better |
| control on the building process depending on the state of the system |
| (java version, OS, command-line property defines, etc.). To make a target |
| <i>sense</i> this property, you should add the <code>if</code> (or |
| <code>unless</code>) 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 <code>if</code> and no <code>unless</code> attribute is present, |
| the target will always be executed.</p> |
| <p>The optional <code>description</code> attribute can be used to provide a one-line description of this target, which is printed by the |
| <nobr><code>-projecthelp</code></nobr> command-line option.</p> |
| <p>It is a good practice to place your <a |
| href="#tstamp">tstamp</a> tasks in a so-called |
| <i>initialization</i> 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>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 target's function.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| |
| <a name="tasks"> |
| <h3>Tasks</h3> |
| </a> |
| <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><<i>name</i> <i>attribute1</i>="<i>value1</i>" <i>attribute2</i>="<i>value2</i>" ... /></pre> |
| </blockquote> |
| <p>where <i>name</i> is the name of the task, |
| <i>attributeN</i> is the attribute name, and |
| <i>valueN</i> is the value for this attribute.</p> |
| <p>There is a set of <a href="#bitasks">built-in tasks</a>, along with a |
| number of |
| <a href="#optionaltasks"> optional tasks</a>, but it is also very |
| easy to <a href="#writingowntask">write your own</a>.</p> |
| <p>All tasks share a task name attribute. The value of |
| this attribute will be used in the logging messages generated by |
| Ant.</p> |
| Tasks can be assigned an <code>id</code> attribute: |
| <blockquote> |
| <pre><<i>taskname</i> id="<i>taskID</i>" ... /></pre> |
| </blockquote> |
| where <i>taskname</i> is the name of the task, and <i>taskID</i> is |
| a unique name for this task. |
| You can refer to the |
| corresponding task object in scripts or other tasks via this name. |
| For example, in scripts you could do: |
| <blockquote> |
| <pre> |
| <script ... > |
| task1.setFoo("bar"); |
| </script> |
| </pre> |
| </blockquote> |
| to set the <code>foo</code> attribute of this particular task instance. |
| In another task (written in Java), you can access the instance via |
| <code>project.getReference("task1")</code>. |
| <p> |
| Note<sup>1</sup>: If "task1" has not been run yet, then |
| it has not been configured (ie., no attributes have been set), and if it is |
| going to be configured later, anything you've done to the instance may |
| be overwritten. |
| </p> |
| <p> |
| Note<sup>2</sup>: Future versions of Ant will most likely <i>not</i> |
| be backward-compatible with this behaviour, since there will likely be no |
| task instances at all, only proxies. |
| </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 may be used in the value of |
| task attributes. This is done by placing the property name between |
| "<code>${</code>" and "<code>}</code>" in the |
| attribute value. For example, |
| if there is a "builddir" property with the value |
| "build", then this could be used in an attribute like this: |
| <code>${builddir}/classes</code>. |
| This is resolved as <code>build/classes</code>.</p> |
| |
| <h3>Built-in Properties</h3> |
| <p>Ant provides access to all system properties as if they had been |
| defined using a <code><property></code> task. |
| For example, <code>${os.name}</code> expands to the |
| name of the operating system.</p> |
| <p>In addition, Ant has some built-in properties:</p> |
| <pre> |
| basedir the absolute path of the project's basedir (as set |
| with the basedir attribute of <project>). |
| ant.file the absolute path of the buildfile. |
| ant.project.name the name of the project that is currently executing; |
| it is set in the name attribute of <project>. |
| ant.java.version the JVM version Ant detected; currently it can hold |
| the values "1.1", "1.2" and "1.3". |
| </pre> |
| |
| <h3>Example</h3> |
| <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="init"> |
| <!-- Create the time stamp --> |
| <tstamp/> |
| <!-- Create the build directory structure used by compile --> |
| <mkdir dir="${build}"/> |
| </target> |
| |
| <target name="compile" depends="init"> |
| <!-- Compile the java code from ${src} into ${build} --> |
| <javac srcdir="${src}" destdir="${build}"/> |
| </target> |
| |
| <target name="dist" depends="compile"> |
| <!-- Create the distribution directory --> |
| <mkdir dir="${dist}/lib"/> |
| |
| <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file --> |
| <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/> |
| </target> |
| |
| <target name="clean"> |
| <!-- Delete the ${build} and ${dist} directory trees --> |
| <delete dir="${build}"/> |
| <delete dir="${dist}"/> |
| </target> |
| </project> |
| </pre> |
| |
| <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 potentially be a very harmful behavior, |
| the tokens in the files <b>must</b> |
| be of the form <code>@</code><i>token</i><code>@</code>, 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 as with documentation systems.</p> |
| <p>Note: If a token with the format <code>@</code><i>token</i><code>@</code> |
| is found in a file, but no |
| filter is associated with that token, no changes take place; |
| therefore, no escaping |
| method is available – but as long as you choose appropriate names for your |
| tokens, this should not cause problems.</p> |
| |
| <h3><a name="path">Path-like Structures</a></h3> |
| <p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type |
| references using both |
| "<code>:</code>" and "<code>;</code>" as separator |
| characters. Ant will |
| convert the separator 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 colon- |
| or semicolon-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 <code><classpath></code> tag |
| supports <code>path</code> and |
| <code>location</code> 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 a 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 that 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 <i>target</i>s, and reference them via their |
| <i>id</i> 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 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> |
| The shortcuts previously mentioned for <code><classpath></code> are also valid for <code><path></code>.For example: |
| <pre> |
| <path id="base.path"> |
| <pathelement path="${classpath}"/> |
| </path> |
| </pre> |
| can be written as: |
| <pre> |
| <path id="base.path" path="${classpath}"/> |
| </pre> |
| |
| <h3><a name="arg">Command-line Arguments</a></h3> |
| <p>Several tasks take arguments that will be passed to another |
| process on the command line. To make it easier to specify arguments |
| that contain space characters, nested <code>arg</code> 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.</td> |
| </tr> |
| <tr> |
| <td valign="top">path</td> |
| <td valign="top">A string that will be treated as a path-like |
| string as a single command-line argument; you can use <code>;</code> |
| or <code>:</code> 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>represents two separate command-line arguments.</p> |
| <blockquote><pre> |
| <arg path="/dir;/dir2:\dir3"/> |
| </pre></blockquote> |
| <p>is a single command-line argument with the 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 example, the <a |
| href="#javac">javac</a> task, which works upon a directory tree |
| with <code>.java</code> 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 a 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><b>Examples:</b></p> |
| <p> |
| <code>*.java</code> matches <code>.java</code>, |
| <code>x.java</code> and <code>FooBar.java</code>, but |
| not <code>FooBar.xml</code> (does not end with <code>.java</code>).</p> |
| <p> |
| <code>?.java</code> matches <code>x.java</code>, |
| <code>A.java</code>, but not <code>.java</code> or <code>xyz.java</code> |
| (both don't have one character before <code>.java</code>).</p> |
| <p> |
| Combinations of <code>*</code>'s and <code>?</code>'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 directory is matched, and so on. For example, when we have the pattern <code>/?abc/*/*.java</code> |
| and the path <code>/xabc/foobar/test.java</code>, |
| the first <code>?abc</code> is matched with <code>xabc</code>, |
| then <code>*</code> is matched with <code>foobar</code>, |
| and finally <code>*.java</code> is matched with <code>test.java</code>. |
| They all match, so the path matches the pattern.</p> |
| <p>To make things a bit more flexible, we add one extra feature, which makes it |
| possible to match multiple directory levels. This can be used to match a |
| complete directory tree, or a file anywhere in the directory tree. |
| To do this, <code>**</code> |
| must be used as the name of a directory. |
| When <code>**</code> is used as the name of a |
| directory in the pattern, it matches zero or more directories. |
| For example: |
| <code>/test/**</code> matches all files/directories under <code>/test/</code>, |
| such as <code>/test/x.java</code>, |
| or <code>/test/foo/bar/xyz.html</code>, but not <code>/xyz.xml</code>.</p> |
| <p>There is one "shorthand" – if a pattern ends |
| with <code>/</code> |
| or <code>\</code>, then <code>**</code> |
| is appended. |
| For example, <code>mypackage/test/</code> is interpreted as if it were |
| <code>mypackage/test/**</code>.</p> |
| <p><b>Example patterns:</b></p> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><code>**/CVS/*</code></td> |
| <td valign="top">Matches all files in <code>CVS</code> directories that can be located |
| anywhere in the directory tree.<br> |
| Matches: |
| <pre> |
| CVS/Repository |
| org/apache/CVS/Entries |
| org/apache/jakarta/tools/ant/CVS/Entries |
| </pre> |
| But not: |
| <pre> |
| org/apache/CVS/foo/bar/Entries (<code>foo/bar/</code> part does not match)</td> |
| </pre> |
| </tr> |
| <tr> |
| <td valign="top"><code>org/apache/jakarta/**</code></td> |
| <td valign="top">Matches all files in the <code>org/apache/jakarta</code> directory tree.<br> |
| Matches: |
| <pre> |
| org/apache/jakarta/tools/ant/docs/index.html |
| org/apache/jakarta/test.xml |
| </pre> |
| But not: |
| <pre> |
| org/apache/xyz.java |
| </pre> |
| (<code>jakarta/</code> part is missing).</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>org/apache/**/CVS/*</code></td> |
| <td valign="top">Matches all files in <code>CVS</code> directories |
| that are located anywhere in the directory tree under |
| <code>org/apache</code>.<br> |
| Matches: |
| <pre> |
| org/apache/CVS/Entries |
| org/apache/jakarta/tools/ant/CVS/Entries |
| </pre> |
| But not: |
| <pre> |
| org/apache/CVS/foo/bar/Entries |
| </pre> |
| (<code>foo/bar/</code> part does not match)</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>**/test/**</code></td> |
| <td valign="top">Matches all files that have a <code>test</code> |
| element in their path, including <code>test</code> 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 <code>images</code> that are |
| located in the directory tree defined by <code>${src}</code> to the |
| destination directory defined by <code>${dist}</code>, |
| but excludes all <code>*.gif</code> files from the copy.</p> |
| <p> This example can also be expressed using nested elements: |
| <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 that 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. |
| <h3><a name="patternset">PatternSets</a></h3> |
| <p>Patterns can be grouped to sets and later be referenced by their |
| <code>id</code> |
| 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 <code>includes</code> and |
| <code>excludes</code> 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> |
| <p>The nested <include> and <exclude> elements allow you to use |
| if and unless arguments to specify that the element should only be used if a |
| property is set, or that it should be used only if a property is not set.</p> |
| <p>For example</p> |
| <blockquote><pre> |
| <patternset id="sources" > |
| <include name="std/**/*.java"/> |
| <include name="prof/**/*.java" if="professional"/> |
| <exclude name="**/*Test*"/> |
| </patternset> |
| </pre></blockquote> |
| <p>will only include the files in the sub-directory <em>prof</em> if the property |
| <em>professional</em> is set to some value.</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 tasks |
| 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 |
| (<code>yes | no</code>); 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 above.</p> |
| |
| <h3><a name="mapper">Mapping File Names</a></h3> |
| <p>Some tasks take source files and create target files. Depending on |
| the task, it may be quite obvious which name a target file will have |
| (using <a href="#javac">javac</a>, you know there will be |
| <code>.class</code> files for your <code>.java</code> files) – in |
| other cases you may want to specify the target files, either to help |
| Ant or to get an extra bit of functionality.</p> |
| <p>While source files are usually specified as <a |
| href="#fileset">fileset</a>s, you don't specify target files directly – |
| instead, you tell Ant how to find the target file(s) for one source file. An |
| instance of <code>org.apache.tools.ant.util.FileNameMapper</code> is |
| responsible for this. It constructs target file names based on rules |
| that can be parameterized with <code>from</code> and <code>to</code> |
| attributes – the exact meaning of which is implementation-dependent.</p> |
| <p>These instances are defined in <code><mapper></code> elements |
| with 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">type</td> |
| <td valign="top">specifies one of the built-in implementations.</td> |
| <td align="center" valign="center" rowspan="2">Exactly one of both</td> |
| </tr> |
| <tr> |
| <td valign="top">classname</td> |
| <td valign="top">specifies the implementation by class name.</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> |
| <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">from</td> |
| <td valign="top">the <code>from</code> attribute for the given |
| implementation.</td> |
| <td align="center" valign="top">Depends on implementation.</td> |
| </tr> |
| <tr> |
| <td valign="top">to</td> |
| <td valign="top">the <code>to</code> attribute for the given |
| implementation.</td> |
| <td align="center" valign="top">Depends on implementation.</td> |
| </tr> |
| </table> |
| <p>The classpath can be specified via a nested |
| <code><classpath></code>, as well – that is, |
| a <a href="#path">path</a>-like structure.</p> |
| <p>The built-in mapper types are:</p> |
| <h4><a name="identity-mapper">identity</a></h4> |
| <p>The target file name is identical to the source file name. Both |
| <code>to</code> and <code>from</code> will be ignored.</p> |
| <b>Examples:</b> |
| <blockquote><pre> |
| <mapper type="identity"/> |
| </pre></blockquote> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Source file name</b></td> |
| <td valign="top"><b>Target file name</b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>A.java</code></td> |
| <td valign="top"><code>A.java</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>C.properties</code></td> |
| <td valign="top"><code>C.properties</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> |
| <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> |
| </tr> |
| </table> |
| <h4><a name="flatten-mapper">flatten</a></h4> |
| <p>The target file name is identical to the source file name, with all |
| leading directory information stripped off. Both <code>to</code> and |
| <code>from</code> will be ignored.</p> |
| <b>Examples:</b> |
| <blockquote><pre> |
| <mapper type="flatten"/> |
| </pre></blockquote> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Source file name</b></td> |
| <td valign="top"><b>Target file name</b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>A.java</code></td> |
| <td valign="top"><code>A.java</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| <td valign="top"><code>B.java</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>C.properties</code></td> |
| <td valign="top"><code>C.properties</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> |
| <td valign="top"><code>A.properties</code></td> |
| </tr> |
| </table> |
| <h4><a name="merge-mapper">merge</a></h4> |
| <p>The target file name will always be the same, as defined by |
| <code>to</code> – <code>from</code> will be ignored.</p> |
| <h5>Examples:</h5> |
| <blockquote><pre> |
| <mapper type="merge" to="archive.tar"/> |
| </pre></blockquote> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Source file name</b></td> |
| <td valign="top"><b>Target file name</b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>A.java</code></td> |
| <td valign="top"><code>archive.tar</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| <td valign="top"><code>archive.tar</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>C.properties</code></td> |
| <td valign="top"><code>archive.tar</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> |
| <td valign="top"><code>archive.tar</code></td> |
| </tr> |
| </table> |
| <h4><a name="glob-mapper">glob</a></h4> |
| <p>Both <code>to</code> and <code>from</code> define patterns that may |
| contain at most one <code>*</code>. For each source file that matches |
| the <code>from</code> pattern, a target file name will be constructed |
| from the <code>to</code> pattern by substituting the <code>*</code> in |
| the <code>to</code> pattern with the text that matches the |
| <code>*</code> in the <code>from</code> pattern. Source file names |
| that don't match the <code>from</code> pattern will be ignored.</p> |
| <b>Examples:</b> |
| <blockquote><pre> |
| <mapper type="glob" from="*.java" to="*.java.bak"/> |
| </pre></blockquote> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Source file name</b></td> |
| <td valign="top"><b>Target file name</b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>A.java</code></td> |
| <td valign="top"><code>A.java.bak</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| <td valign="top"><code>foo/bar/B.java.bak</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>C.properties</code></td> |
| <td valign="top">ignored</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> |
| <td valign="top">ignored</td> |
| </tr> |
| </table> |
| <blockquote><pre> |
| <mapper type="glob" from="C*ies" to="Q*y"/> |
| </pre></blockquote> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Source file name</b></td> |
| <td valign="top"><b>Target file name</b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>A.java</code></td> |
| <td valign="top">ignored</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| <td valign="top">ignored</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>C.properties</code></td> |
| <td valign="top"><code>Q.property</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> |
| <td valign="top"><code>Qlasses/dir/dir2/A.property</td> |
| </tr> |
| </table> |
| <h4><a name="regexp-mapper">regexp</a></h4> |
| <p>Both <code>to</code> and <code>from</code> define regular |
| expressions. If the source file name matches the <code>from</code> |
| pattern, the target file name will be constructed from the |
| <code>to</code> pattern, using <code>\0</code> to <code>\9</code> as |
| back-references for the full |
| match (<code>\0</code>) or the matches of the subexpressions in |
| parentheses. |
| Source |
| files not matching the <code>from</code> pattern will be ignored.</p> |
| <p>Note that you need to escape a dollar-sign (<code>$</code>) with |
| another dollar-sign in Ant.</p> |
| <p>The regexp mapper needs a supporting library and an implementation |
| of <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that |
| hides the specifics of the library. Ant comes with implementations for |
| <a href="http://jakarta.apache.org/regexp/">jakarta-regexp</a> and <a |
| href="http://jakarta.apache.org/oro/">jakarta-ORO</a>. If you compile |
| from sources and plan to use one of them, make sure the libraries are |
| in your <code>CLASSPATH</code>.</a> For information about using <a |
| href="http://www.cacas.org/~wes/java/">gnu.regexp</a> or <a |
| href="http://www.crocodile.org/~sts/Rex/">gnu.rex</a> with Ant, see <a |
| href="http://marc.theaimsgroup.com/?l=ant-dev&m=97550753813481&w=2">this</a> |
| article.</p> |
| <p>Ant will choose the regular-expression library based on the |
| following algorithm: |
| <ul> |
| <li>If the system property |
| <code>ant.regexp.matcherimpl</code> has been set, it is taken as the |
| name of the class implementing |
| <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that |
| should be used.</li> |
| <li>If it has not been set, first try jakarta-ORO; if that |
| cannot be found, try jakarta-regexp.</li> |
| </ul> |
| </p> |
| <b>Examples:</b> |
| <blockquote><pre> |
| <mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/> |
| </pre></blockquote> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Source file name</b></td> |
| <td valign="top"><b>Target file name</b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>A.java</code></td> |
| <td valign="top"><code>A.java.bak</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| <td valign="top"><code>foo/bar/B.java.bak</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>C.properties</code></td> |
| <td valign="top">ignored</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> |
| <td valign="top">ignored</td> |
| </tr> |
| </table> |
| <blockquote><pre> |
| <mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/> |
| </pre></blockquote> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Source file name</b></td> |
| <td valign="top"><b>Target file name</b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>A.java</code></td> |
| <td valign="top">ignored</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| <td valign="top"><code>foo/bar/bar-B.java</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>C.properties</code></td> |
| <td valign="top">ignored</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> |
| <td valign="top"><code>Classes/dir/dir2/dir2-A.properties</code></td> |
| </tr> |
| </table> |
| <blockquote><pre> |
| <mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/> |
| </pre></blockquote> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Source file name</b></td> |
| <td valign="top"><b>Target file name</b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>A.java</code></td> |
| <td valign="top"><code>java.A</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| <td valign="top"><code>java.foo/bar/B</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>C.properties</code></td> |
| <td valign="top"><code>properties.C</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> |
| <td valign="top"><code>properties.Classes/dir/dir2/A</code></td> |
| </tr> |
| </table> |
| |
| <hr> |
| <h2><a name="bitasks">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="#apply">Apply</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 buildfiles 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="apply">Apply</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. The timestamp of each source file is compared to the |
| timestamp of a target file which is defined by a nested <a |
| href="#mapper">mapper</a> element. At least one fileset and exactly |
| one mapper element are 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">dest</td> |
| <td valign="top">the directory where the target files will be placed.</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. If false, command will be executed once for every file. |
| Defaults to false. </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">type</td> |
| <td valign="top">One of <i>file</i>, <i>dir</i> or |
| <i>both</i>. If set to <i>file</i>, only the names of plain |
| files will be sent to the command. If set to <i>dir</i>, only |
| the names of directories are considered.</td> |
| <td align="center" valign="top">No, default is <i>file</i></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>srcfile</h4> |
| <p>By default the file names of the source files will be added to the |
| end of the command line. If you need to place it somewhere different, |
| use a nested <code><srcfile></code> element between your |
| <code><arg></code> elements to mark the insertion point.</code> |
| <h4>targetfile</h4> |
| <p><code><targetfile></code> is similar to |
| <code><srcfile></code> and marks the position of the target |
| filename on the command line. If omitted, the target filenames will |
| not be added to the command line at all.</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> |
| <apply executable="cc" dest="src/C" parallel="false"> |
| <arg value="-c"/> |
| <arg value="-o"/> |
| <targetfile/> |
| <srcfile/> |
| <fileset dir="src/C" includes="*.c"/> |
| <mapper type="glob" from="*.c" to="*.o"/> |
| </apply> |
| </pre></blockquote> |
| <p>invokes <code>cc -c -o TARGETFILE SOURCEFILE</code> for each |
| <code>.c</code> file that is newer than the corresponding |
| <code>.o</code>, replacing TARGETFILE with the absolute filename of |
| the <code>.o</code> and SOURCEFILE with the absolute name of the |
| <code>.c</code> file.</p> |
| <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> |
| <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> |
| |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>classpath</h4> |
| <p><code>Available</code>'s <i>classpath</i> attribute is a <a |
| href="#path">path-like structure</a> and can also be set via a nested |
| <i>classpath</i> 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 class <i>org.whatever.Myclass</i> is found in Ant's classpath.</p> |
| <pre> |
| <property name="jaxp.jar" value="./lib/jaxp11/jaxp.jar"/> |
| <available file="${jaxp.jar}" property="jaxp.jar.present"/> |
| </pre> |
| <p>sets the property <code><i>jaxp.jar.present</i></code> to the value "true" |
| if the file <i>./lib/jaxp11/jaxp.jar</i> is found.</p> |
| <pre> |
| ...in project ... |
| <property name="jaxp.jar" value="./lib/jaxp11/jaxp.jar"/> |
| <path id="jaxp" location="${jaxp.jar}"/> |
| ...in target ... |
| <available classname="javax.xml.transform.Transformer" classpathref="jaxp" property="jaxp11.present"/> |
| </pre> |
| <p>sets the property <code><i>jaxp11.present</i></code> to the value "true" |
| if the class <i>javax.xml.transform.Transformer</i> is found in the classpath referenced by <code>jaxp</code> (in this case, it is <code>./lib/jaxp11/jaxp.jar</code>). |
| </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 <i>file</i>, <i>dir</i> or |
| <i>both</i>. If set to <i>file</i>, only the permissions of |
| plain files are going to be changed. If set to <i>dir</i>, only |
| the directories are considered.</td> |
| <td align="center" valign="top">No, default is <i>file</i></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">preservelastmodified</td> |
| <td valign="top">Give the copied files the same last modified |
| time as the original files. Defaults to "no".</td> |
| <td valign="top" align="center">No</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". Note that you can achieve the |
| same effect by using a <a href="#flatten-mapper">flatten mapper</a></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>Parameters specified as nested elements</h3> |
| <h4>mapper</h4> |
| <p>You can define file name transformations by using a nested <a |
| href="#mapper">mapper</a> element. The default mapper used by |
| <code><copy></code> is the <a |
| href="#identity-mapper">identity</a>.</p> |
| <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> |
| <p><b>Copy a set of files to a directory appending |
| "<code>.bak</code>" to the file name on the fly</b></p> |
| <pre> |
| <copy todir="../backup/dir" > |
| <fileset dir="src_dir" /> |
| <mapper type="glob" from="*" to="*.bak"/> |
| </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 <code>dest</code> |
| attribute (default is <code>false</code>).</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 <i>not</i> removed by default. |
| To remove empty directories, use the <em>includeEmptyDirs</em> atribute.</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">quiet</td> |
| <td valign="top">If the file does not exist, do not display a diagnostic |
| message or modify the exit status to reflect an error. |
| This means that if a file or directory cannot be deleted, |
| then no error is reported. This setting emulates the |
| -f option to the Unix "rm" command. |
| ("true"/"false"). |
| Default is "false" meaning things are "noisy".</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">includeEmptyDirs</td> |
| <td valign="top">Set to "true" to delete empty directores when |
| using filesets. Default is "false".</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 the <code>lib</code> directory, including all files |
| and subdirectories of <code>lib</code>.</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> |
| <pre> <delete includeEmptyDirs="true" > |
| <fileset dir="build" /> |
| </delete> |
| </pre> |
| <p>deletes all files and subdirectories of <code>build</code>, but not |
| <code>build</code> itself.<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> |
| <tr> |
| <td valign="top">newenvironment</td> |
| <td valign="top">Do not propagate old environment when new environment |
| variables are specified.</td> |
| <td align="center" valign="top">No, default is <i>false</i></td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <blockquote> |
| <p> |
| <pre> |
| <exec dir="${src}" executable="cmd.exe" os="Windows 2000" output="dir.txt"> |
| <arg line="/c dir"/> |
| </exec></pre></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">newenvironment</td> |
| <td valign="top">Do not propagate old environment when new environment |
| variables are specified.</td> |
| <td align="center" valign="top">No, default is <i>false</i></td> |
| </tr> |
| <tr> |
| <td valign="top">parallel</td> |
| <td valign="top">Run the command only once, appending all files as |
| arguments. If false, command will be executed once for every file. |
| Defaults to false. </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">type</td> |
| <td valign="top">One of <i>file</i>, <i>dir</i> or |
| <i>both</i>. If set to <i>file</i>, only the names of plain |
| files will be sent to the command. If set to <i>dir</i>, only |
| the names of directories are considered.</td> |
| <td align="center" valign="top">No, default is <i>file</i></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>srcfile</h4> |
| <p>By default the file names of the source files will be added to the |
| end of the command line. If you need to place it somewhere different, |
| use a nested <code><srcfile></code> element between your |
| <code><arg></code> elements to mark the insertion point.</code> |
| <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> |
| <blockquote><pre> |
| <execon executable="somecommand" parallel="false" > |
| <arg value="arg1"/> |
| <srfile/> |
| <arg value="arg2"/> |
| <fileset dir="/tmp"/> |
| </execon> |
| </pre></blockquote> |
| <p>invokes <code>somecommand arg1 SOURCEFILENAME arg2</code> for each |
| file in <code>/tmp</code> replacing SOURCEFILENAME with the absolute |
| filename of each file in turn. If <code>parallel</code> had been set |
| to true, SOURCEFILENAME would be replaced with the absolute filenames |
| of all files separated by spaces.</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> |
| |
| <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> |
| |
| <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>usetimestamp</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">usetimestamp</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" |
| usetimestamp="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. |
| The extended fileset attributes from the zip task are also available |
| in the jar task. |
| 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. |
| <p>(The Jar task is a shortcut for specifying the manifest file of a JAR file. |
| The same thing can be accomplished by using the <i>fullpath</i> |
| attribute of a zipfileset in a Zip task. The one difference is that if the |
| <i>manifest</i> attribute is not specified, the Jar task will |
| include an empty one for you.)</p> |
| </p> |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">jarfile</td> |
| <td valign="top">the jar-file to create.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">basedir</td> |
| <td valign="top">the directory from which to jar the files.</td> |
| <td valign="top" align="center">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 into 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 into 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 into 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 into 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> |
| <tr> |
| <td valign="top">output</td> |
| <td valign="top">Name of a file to write the output to.</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 <i>classpath</i> attribute is a <a |
| href="#path">PATH like structure</a> and can also be set via a nested |
| <i>classpath</i> 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, classic is the default. For JDK 1.3, modern is the default. |
| If you wish to use a different compiler interface than one of the four |
| supplied, write a class that implements the CompilerAdapter interface |
| (package org.apache.tools.ant.taskdefs.compilers). Supply the full |
| classname in the "build.compiler" property. |
| </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 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 that contains |
| include patterns.</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 that contains |
| exclude patterns.</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 |
| (<code>yes</code> | <code>no</code>); 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 |
| <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 a |
| <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 source should be compiled with debug |
| information; defaults to <code>off</code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">optimize</td> |
| <td valign="top">indicates whether source should be compiled with |
| optimization; defaults to <code>off</code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">deprecation</td> |
| <td valign="top">indicates whether source should be compiled with |
| deprecation information; defaults to <code>off</code>.</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., |
| <code>1.1</code> or <code>1.2</code>).</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> |
| <tr> |
| <td valign="top">includeAntRuntime</td> |
| <td valign="top">whether to include the Ant run-time libraries; |
| defaults to <code>no</code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">includeJavaRuntime</td> |
| <td valign="top">whether to include the default run-time |
| libraries from the executing VM; defaults to <code>no</code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">failonerror</td> <td valign="top"> |
| indicates whether the build will continue even if there are compilation errors; defaults to <code>true</code>. |
| </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><code>src</code>, <code>classpath</code>, <code>bootclasspath</code> and <code>extdirs</code></h4> |
| <p><code>Javac</code>'s <i>srcdir</i>, <i>classpath</i>, |
| <i>bootclasspath</i> and <i>extdirs</i> attributes are <a |
| href="#path">path-like structures</a> and can also be set via nested |
| <code><src></code>, |
| <code><classpath></code>, |
| <code><bootclasspath></code> and |
| <code><extdirs></code> elements, respectively.</p> |
| |
| <h3>Examples</h3> |
| <pre> <javac srcdir="${src}" |
| destdir="${build}" |
| classpath="xyz.jar" |
| debug="on" |
| /></pre> |
| <p>compiles all <code>.java</code> files under the <code>${src}</code> |
| directory, and stores |
| the <code>.class</code> files in the <code>${build}</code> directory. |
| 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 <code>.java</code> files under the <code>${src}</code> |
| directory, and stores the |
| <code>.class</code> files in the <code>${build}</code> directory. |
| 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 |
| from compilation.</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 property <code>src2</code>. This can also be represented using nested |
| <code><src></code> 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 JDKs < 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> |
| <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">all</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 <i>sourcepath</i>, <i>classpath</i> and |
| <i>bootclasspath</i> attributes are <a href="#path">PATH like |
| structure</a> and can also be set via nested <i>sourcepath</i>, |
| <i>classpath</i> and <i>bootclasspath</i> 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").Note that you can achieve the |
| same effect by using a <a href="#flatten-mapper">flatten mapper</a></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>Parameters specified as nested elements</h3> |
| <h4>mapper</h4> |
| <p>You can define file name transformations by using a nested <a |
| href="#mapper">mapper</a> element. The default mapper used by |
| <code><copy></code> is the <a |
| href="#identity-mapper">identity</a>.</p> |
| <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> |
| <p><b>Append <code>".bak"</code> to the names of all files |
| in a directory.</b></p> |
| <pre> |
| <move todir="my/src/dir" > |
| <fileset dir="my/src/dir" > |
| <exclude name="**/*.bak"/> |
| </fileset> |
| <mapper type="glob" from="*" to="*.bak"/> |
| </move> |
| </pre> |
| <hr> |
| <h2><a name="patch">Patch</a></h2> |
| <h3>Description</h3> |
| <p>Applies a diff file to originals.</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">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 five 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> |
| <li>By setting the <i>environment</i> attribute with a prefix to use. |
| Properties will be defined for every environment variable by |
| prefixing the suplied name and a period to the name of the variable.</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> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top">the classpath to use when looking up a resource.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">classpathref</td> |
| <td valign="top">the classpath to use when looking up a resource, |
| given as <a href="#references">reference</a> to a PATH defined |
| elsewhere..</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>classpath</h4> |
| <p><code>Property</code>'s <i>classpath</i> attribute is a <a |
| href="#path">PATH like structure</a> and can also be set via a nested |
| <i>classpath</i> element.</p> |
| <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.</p> |
| <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">propertyFile</td> |
| <td valign="top">valid property file from which properties specified using nested <code><replacefilter></code> elements are drawn.</td> |
| <td valign="top" align="center">Yes only if <i>property</i> attribute of <code><replacefilter></code> is used.</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<i>\n</i>token" with the string "wombat", in all |
| HTML files in the directory <code>${src}</code>.Where <i>\n</i> 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> |
| <h4>replacefilter</h4> |
| <p>In addition to allowing for multiple replacements, optional nested <code><replacefilter></code> elements allow replacement values to be extracted from a property file. The name of this file is specified using the <code><replace></code> attribute <i>propertyFile</i>. |
| </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">token</td> |
| <td valign="top">The string to search for.</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">value</td> |
| <td valign="top">The replacement string.</td> |
| <td align="center" rowspan="2">Either may be specified, but not both. Both can be omitted, if desired.</td> |
| </tr> |
| <tr> |
| <td valign="top">property</td> |
| <td valign="top">Name of the property whose value is to serve as the replacement value.</td> |
| </tr> |
| </table> |
| <p>If neither <i>value</i> nor <i>property</i> is used, the value provided using the <code><replace></code> attribute <i>value</i> and/or the <code><replacevalue></code> element is used. If no value was specified using either of these options, the token is replaced with an empty string. |
| </p> |
| <h3>Examples</h3> |
| <blockquote><pre> |
| <replace |
| file="configure.sh" |
| value="defaultvalue" |
| propertyFile="source/name.properties" > |
| <replacefilter |
| token="@token1@" /> |
| <replacefilter |
| token="@token2@" |
| value="value2"/> |
| <replacefilter |
| token="@token3@" |
| property="property.key"/> |
| </replace> |
| </pre></blockquote> |
| <p>In file <code>configure.sh</code>, replace all instances of "@token1@" with "defaultvalue", all instances of "@token2@" with "value2", and all instances of "@token3@" with the value of the property "property.key", as it appears in property file <code>src/name.properties</code>.</p> |
| <p><b>Note:</b> It is possible to use either the <i>token</i>/<code><replacetoken></code> and <i>value</i>/<code><replacevalue></code> attributes/elements, the nested replacefilter elements, or both in the same operation. |
| </p> |
| <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> |
| <tr> |
| <td valign="top">iiop</td> |
| <td valign="top">indates that portable (RMI/IIOP) stubs should be generated</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">iiopopts</td> |
| <td valign="top">additional arguments for IIOP class generation</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">idl</td> |
| <td valign="top">indates that IDL output files should be generated</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">idlopts</td> |
| <td valign="top">additional arguments for IDL file generation</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">debug</td> |
| <td valign="top">generate debug info (passes -g to rmic). Defaults to 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 <i>classpath</i> attribute is a <a |
| href="#path">PATH like structure</a> and can also be set via a nested |
| <i>classpath</i> 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> |
| <p>Style supports the use of a <param> element which is use to pass values |
| to an <xsl:param> declaration.</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 |
| "trax" for a TraX compliant processor, "xslp" for the |
| XSL:P processor, "xalan" for the Apache XML Xalan (version 1) |
| processor, or the name of an arbitrary XSLTLiaison class. Defaults to trax, |
| followed by xslp then xalan (in that order). The first one found in your |
| class path is the one that is used.</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">in</td> |
| <td valign="top">specifies a single XML document to be styled. Should be used |
| with the out attribute.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">out</td> |
| <td valign="top">specifies the output name for the sytled result from the |
| in attribute.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>param</h4> |
| <p>Param is used to pass a parameter to the XSL stylesheet.</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">name</td> |
| <td valign="top">Name of the XSL parameter</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">expression</td> |
| <td valign="top">XSL expression to be placed into the param. To pass a text |
| value into the style sheet it needs to be escaped using single quotes.</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <blockquote> |
| <p> |
| <pre> |
| <style basedir="doc" destdir="build/doc" |
| extension="html" style="style/apache.xsl"/></pre> |
| <h4><br> |
| Using XSL parameters<br> |
| </h4> |
| <pre><style basedir="doc" destdir="build/doc" |
| extension="html" style="style/apache.xsl"> |
| <param name="date" expression="'07-01-2000'"/> |
| </style></pre> |
| <p>This will replace an xsl:param definition<xsl:param name="date"></xsl:param> |
| with the text value 07-01-2000 </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 into 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 into 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 <i>classpath</i> attribute is a <a |
| href="#path">PATH like structure</a> and can also be set via a nested |
| <i>classpath</i> 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> |
| <tr> <td colspan="3"/> No parameters</td> |
| </tr> |
| </table> |
| |
| <h3>Nested Elements</h3> |
| The tstamp task supports a format nested element which allows a property to be |
| given the current date and time in a given format. The date/time patterns are as defined in the Java |
| SimpleDateFormat class. |
| <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">property</td> |
| <td valign="top"> |
| The property which is to receive the date/time string in the given pattern |
| </td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">pattern</td> |
| <td valign="top">The date/time pattern to be used. The values are defined by the Java |
| SimpleDateFormat class</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| </table> |
| |
| <h3>Examples</h3> |
| <p> Set the standard DSTAMP, TSTAMP and TODAY properties according to the formats above |
| <pre> <tstamp/></pre> |
| |
| <p> As for the above example, set the standard properties and also set the property |
| "TODAY_UK" with the date/time pattern "d MMM yyyy" |
| |
| <pre> <tstamp> |
| <format property="TODAY_UK" pattern="d MMMM yyyy"> |
| </tstamp> |
| </pre> |
| |
| <hr> |
| <h2><a name="uptodate">Uptodate</a></h2> |
| <h3>Description</h3> |
| <p>Sets a property if a target files are 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, while target |
| files are specified using a nested <a href="#mapper">mapper</a> |
| element.</p> |
| <p>The value part of the property being set is <i>true</i> if the |
| timestamp of the target files is more recent than the timestamp of |
| every corresponding source file.</p> |
| <p>The default behavior is to use a <a href="#merge-mapper">merge |
| mapper</a> whith the <code>to</code> attribute set to the value of the |
| targetfile attribute.</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, unless a nested mapper element is |
| present.</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> |
| <p>This can be written as |
| <pre> <uptodate property="xmlBuild.notRequired" > |
| <srcfiles dir= "${src}/xml" includes="**/*.dtd"/> |
| <mapper type="merge" to="${deploy}\xmlClasses.jar"/> |
| </uptodate></pre> |
| <p>as well.</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>(The War task is a shortcut for specifying the particular layout of a WAR file. |
| The same thing can be accomplished by using the <i>prefix</i> and <i>fullpath</i> |
| attributes of zipfilesets in a Zip or Jar task.)</p> |
| <p>The extended zipfileset element from the zip task (with attributes <i>prefix</i>, <i>fullpath</i>, and <i>src</i>) is available in the War task.</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 |
| src/graphics/images/gifs/small/logo.gif |
| src/graphics/images/gifs/large/logo.gif |
| </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"/> |
| <zipfileset dir="src/graphics/images/gifs" |
| prefix="images"/> |
| </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 |
| images/small/logo.gif |
| images/large/logo.gif |
| </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>. |
| <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 <i>only used</i> |
| 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 <i>within</i> each fileset. The Zip task and its derivatives know a special form of a fileset named zipfileset that has additional attributes (described below). </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>Parameters specified as nested elements</h3> |
| <h4>fileset</h4> |
| <p>The zip task supports any number of nested <a |
| href="#fileset"><code><fileset></code></a> elements to specify |
| the files to be included in the archive.</p> |
| <h4>zipfileset</h4> |
| <p>A <code><zipfileset></code> has three additional attributes: <i>prefix</i>, <i>fullpath</i>, and <i>src</i>. The |
| <i>prefix</i> and <i>fullpath</i> attributes modify the location of the files when they are placed |
| inside the archive. If the <i>prefix</i> attribute is set, all files in the fileset are prefixed |
| with that path in the archive. If the <i>fullpath</i> attribute is set, the file described by the fileset is placed at that |
| exact location in the archive. (The <i>fullpath</i> attribute can only be set for filesets that represent a single file. The <i>prefix</i> and <i>fullpath</i> attributes cannot both be set on the same fileset.) The <i>src</i> attribute |
| may be used in place of the <i>dir</i> attribute to specify a zip file whose |
| contents will be extracted and included in the archive. As with directories, include and exclude patterns may be used to specify a subset of the zip file |
| for inclusion in the archive. |
| |
| <h3>Examples</h3> |
| <pre> <zip zipfile="${dist}/manual.zip" |
| basedir="htdocs/manual" |
| /></pre> |
| <p>zips all files in the <code>htdocs/manual</code> directory into 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. 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. 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, 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> |
| <pre> <zip zipfile="${dist}/manual.zip"> |
| <zipfileset dir="htdocs/manual" prefix="docs/user-guide"/> |
| <zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/> |
| <zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/> |
| </zip></pre> |
| <p>zips all files in the <code>htdocs/manual</code> directory into the <code>docs/user-guide</code> directory |
| in the archive, adds the file <code>ChangeLog27.txt</code> in the |
| current directory as <code>docs/ChangeLog.txt</code>, and includes all the html files in <code>examples.zip</code> under <code>docs/examples</code>. The archive might end up containing the files: |
| <pre><code> docs/user-guide/html/index.html |
| docs/ChangeLog.txt |
| docs/examples/index.html |
| </code></pre> |
| </p> |
| |
| <hr> |
| <h2><a name="optionaltasks">Optional tasks</a></h2> |
| <p>The tasks listed here are not included in the ant.jar included in the binary distribution |
| of Ant. To use them you should download optional.jar and put in the lib-subdirectory of your |
| Ant-installation. Additionaly some of these tasks require external libraries to be put on |
| your CLASSPATH.</p> |
| <ul> |
| <li><a href="dotnet.html">.NET Tasks</a></li> |
| <li><a href="antlr.html">ANTLR</a></li> |
| <li><a href="#cab">Cab</a></li> |
| <li><a href="clearcase.html">Clearcase Tasks</a></li> |
| <li><a href="ejb.html">EJB Tasks</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="propertyfile.html">PropertyFile</a></li> |
| <li><a href="perforce.html">Perforce Tasks</a></li> |
| <li><a href="#renameexts">RenameExtensions</a></li> |
| <li><a href="#script">Script</a></li> |
| <li><a href="#sound">Sound</a></li> |
| <li><a href="#telnet">Telnet</a></li> |
| <li><a href="#vssget">VssGet</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 into 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 into 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 into 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><b>Note:</b> The ftp-task uses the NetComponents-Package which you will need to download from |
| <a href="http://www.savarese.org">http://www.savarese.org</a> and add to your classpath.</p> |
| <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">passive</td> |
| <td valign="top">selects passive-mode ("yes") transfers. |
| Defaults to "no"</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. Passive mode has been switched on to send files from behind a firewall.</p> |
| <pre> <ftp server="ftp.nt.org" |
| remotedir="c:\uploads" |
| userid="coder" |
| password="java1" |
| separator="\" |
| verbose="yes"</pre> |
| <PRE> |
| > |
| <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><i>Deprecated</i></h3> |
| <p><i>This task has been deprecated. Use the <a href="#move">move</a> |
| task with a <a href="#glob-mapper">glob mapper</a> instead.</i></p> |
| <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="sound">Sound</a></h2> |
| <h3>Description</h3> |
| <p>Plays a sound-file at the end of the build, according to whether |
| the build failed or succeeded. You can specify either a specific |
| sound-file to play, or, if a directory is specified, the |
| <code><sound></code> task will randomly select a file to play. |
| Note: At this point, the random selection is based on all the files |
| in the directory, not just those ending in appropriate suffixes |
| for sound-files, so be sure you only have sound-files in the |
| directory you specify. |
| |
| <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">loops</td> |
| <td valign="top">the number of extra times to play the sound-file; |
| default is <code>0</code>. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">duration</td> |
| <td valign="top">the amount of time (in milliseconds) to play |
| the sound-file. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <p> |
| To specify the sound-files or the sound-file directories, use the |
| nested <code><success></code> and <code><fail></code> |
| elements: |
| <blockquote> |
| <pre> |
| <success> the path to a sound-file directory, or the name of a |
| specific sound-file, to be played if the build succeeded. |
| <fail> the path to a sound-file directory, or the name of a |
| specific sound-file, to be played if the build succeeded. |
| </pre> |
| </blockquote> |
| |
| <h3>Examples</h3> |
| <blockquote> |
| <pre> |
| <target name="fun" if="fun" unless="fun.done"> |
| <sound loops="2"> |
| <success source="${user.home}/sounds/bell.wav"/> |
| <fail source="${user.home}/sounds/ohno.wav"/> |
| </sound> |
| <property name="fun.done" value="true"/> |
| </target> |
| </pre> |
| </blockquote> |
| plays the <code>bell.wav</code> sound-file if the build succeeded, or |
| the <code>ohno.wav</code> sound-file if the build failed, three times, |
| if the <code>fun</code> property is set to <code>true</code>. |
| If the target |
| is a dependency of an "initialization" target that other |
| targets depend on, the |
| <code>fun.done</code> property prevents the target from being executed |
| more than once. |
| <blockquote> |
| <pre> |
| <target name="fun" if="fun" unless="fun.done"> |
| <sound> |
| <success source="//intranet/sounds/success"/> |
| <fail source="//intranet/sounds/failure"/> |
| </sound> |
| <property name="fun.done" value="true"/> |
| </target> |
| </pre> |
| </blockquote> |
| randomly selects a sound-file to play when the build succeeds or fails. |
| |
| <hr> |
| <h2><a name="telnet">Telnet</a></h2> |
| <h3>Description</h3> |
| Task to automate a remote telnet session. The task uses nested <read> to indicate strings to wait for, and <write> tags to specify text to send. |
| |
| <p>If you do specify a userid and password, the system will assume a common unix prompt to wait on. This behavior can be easily over-ridden.</p> |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <th>Attribute</th> |
| <th>Values</th> |
| <th>Required</th> |
| </tr> |
| <tr> |
| <td>userid</td> |
| <td>the login id to use on the telnet server.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>password</td> |
| <td>the login password to use on the telnet server.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>server</td> |
| <td>the address of the remote telnet server.</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>port</td> |
| <td>the port number of the remote telnet server. Defaults to port 23.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>initialCR</td> |
| <td>send a cr after connecting ("yes"). Defaults to "no".</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>timeout</td> |
| <td>set a default timeout to wait for a response. Specified in seconds. Default is no timeout.</td> |
| <td>No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| A simple example of connecting to a server and running a command. This assumes a prompt of "ogin:" for the userid, and a prompt of "assword:" for the password. |
| <blockquote><pre> |
| <telnet userid="bob" password="badpass" server="localhost"> |
| <read>/home/bob</read> |
| <write>ls</write> |
| <read string="/home/bob"/> |
| </telnet> |
| </pre></blockquote> |
| |
| This task can be rewritten as: |
| <blockquote><pre> |
| <telnet server="localhost"> |
| <read>ogin:</read> |
| <write>bob</write> |
| <read>assword:</read> |
| <write>badpass</write> |
| <read>/home/bob</read> |
| <write>ls</write> |
| <read>/home/bob</read> |
| </telnet> |
| </pre></blockquote> |
| |
| A timeout can be specified at the <telnet> level or at the <read> level. This will connect, issue a sleep command that is suppressed from displaying and wait 10 seconds before quitting. |
| <blockquote><pre> |
| <telnet userid="bob" password="badpass" server="localhost" timeout="20"> |
| <read>/home/bob</read> |
| <write echo="false">sleep 15</write> |
| <read timeout="10">/home/bob</read> |
| </telnet> |
| </pre></blockquote> |
| |
| The task can be used with other ports as well: |
| <blockquote><pre> |
| <telnet port="80" server="localhost" timeout="20"> |
| <read/> |
| <write>GET / http/0.9</write> |
| <write/> |
| <read timeout="10">&lt;/HTML&gt;</read> |
| </telnet> |
| </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 |
| <code>-listener</code> option. For example: |
| <blockquote> |
| <pre>ant -listener org.apache.tools.ant.XmlLogger</pre> |
| </blockquote> |
| will run Ant with a listener that generates an XML representation of the build progress. This |
| listener is included with Ant, as is the default listener, which generates the logging to standard output. |
| |
| <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 <i>setter</i> 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 <code>set</code>, followed by the |
| attribute name, with the first character of the name in uppercase, and the rest in |
| lowercase. The type of the attribute can be: |
| <ul> |
| <li> |
| <code>String</code> |
| </li> |
| <li> |
| any primitive type (they are converted for you from their String-representation |
| in the buildfile) |
| </li> |
| <li> |
| boolean – your method will be passed the value |
| <i>true</i> if the value specified in the buildfile is one of <code>true</code>, |
| <code>yes</code>, or <code>on</code>) |
| </li> |
| <li> |
| <code>Class</code> |
| <li> |
| <code>File</code> |
| (in which case the value of the attribute is interpreted relative to the |
| project's basedir) |
| </li> |
| <li> |
| any other type that has a constructor with a single |
| <code>String</code> argument |
| </li> |
| </ul> |
| <li>If your task has enumerated attributes, you should consider using |
| a subclass of <code>org.apache.tools.ant.types.EnumeratedAttribute</code> |
| as an argument |
| to your setter method. See |
| <code>org/apache/tools/ant/taskdefs/FixCRLF.java</code> 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 <i>create</i> or <i>add</i> method. |
| A create method |
| must be a <code>public</code> method that takes no arguments and returns |
| an <code>Object</code> type. The name of the create method must begin with |
| <code>create</code>, followed by the element name. An add method must be |
| a <code>public void</code> method that takes a single argument of an |
| <code>Object</code> type with a no-argument constructor. |
| The name of the add method |
| must begin with <code>add</code>, 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-argument constructor, at parser |
| time. This means even tasks that are never executed get |
| instantiated.</li> |
| |
| <li>The task gets references to its project and location inside the |
| buildfile via its inherited <code>project</code> and |
| <code>location</code> variables.</li> |
| |
| <li>If the user specified an <code>id</code> 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. While the above initialization |
| steps only occur once, the execute() method may be |
| called more than once, if the task is invoked more than once. For example, |
| if <code>target1</code> and <code>target2</code> both depend |
| on <code>target3</code>, then running |
| <code>'ant target1 target2'</code> will run all tasks in |
| <code>target3</code> twice.</li> |
| </ol> |
| |
| <h3>Example</h3> |
| <p>Let's write our own task, which prints a message on the |
| <code>System.out</code> stream. |
| The |
| task has one attribute, called <code>message</code>.</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 <code><taskdef></code> 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 on-line 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 |
| on line.</p> |
| <p>One of the questions popping 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. A searchable 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 them to the |
| lists.</p> |
| <hr> |
| <p align="center">Copyright © 2000,2001 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
| |