youys
/
ant
Not watched
1
0
Fork 1
Code
Releases 0 Wiki Activity
Issues 0 Pull Requests 0 Datasets Model Cloudbrain
You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.
Tree: 4ca5683c2a
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '4ca5683c2a'
${ noResults }
ant/docs/index.html

6623 lines
256 KiB
Raw Blame History 

  1. <html>

  2. 

  3. <head>

  4. <meta http-equiv="Content-Language" content="en-us">

  5. <title>Ant User Manual</title>

  6. </head>

  7. 

  8. <body>

  9. 

  10. <center>

  11. <h1>Ant User Manual</h1>

  12. <p>by</p>

  13. </center>

  14. <!-- Names are in alphabetical order, on last name -->

  15. <ul>

  16.   <li>Jacques Bergeron (<a href="mailto:jacques.bergeron@dogico.com">jacques.bergeron@dogico.com</a>)</li>

  17.   <li>Stefan Bodewig (<a href="mailto:stefan.bodewig@epost.de">stefan.bodewig@epost.de</a>)</li>

  18.   <li>Patrick Chanezon (<a href="mailto:chanezon@netscape.com">chanezon@netscape.com</a>)</li>

  19.   <li>James Duncan Davison (<a href="mailto:duncan@x180.com">duncan@x180.com</a>)</li>

  20.   <li>Tom Dimock (<a href="mailto:tad1@cornell.edu">tad1@cornell.edu</a>)</li>

  21.   <li>Diane Holt (<a href="mailto:holtdl@yahoo.com">holtdl@yahoo.com</a>)</li>

  22.   <li>Bill Kelly (<a href="mailto:bill.kelly@softwired-inc.com">bill.kelly@softwired-inc.com</a>)</li>

  23.   <li>Arnout J. Kuiper (<a href="mailto:ajkuiper@wxs.nl">ajkuiper@wxs.nl</a>)</li>

  24.   <li>Conor MacNeill (<a href="mailto:conor@cortexebusiness.com.au">conor@cortexebusiness.com.au</a>)</li>

  25.   <li>Stefano Mazzocchi (<a href="mailto:stefano@apache.org">stefano@apache.org</a>)</li>

  26.   <li>Erik Meade (<a href="mailto:emeade@geekfarm.org">emeade@geekfarm.org</a>)</li>

  27.   <li>Sam Ruby (<a href="mailto:rubys@us.ibm.com">rubys@us.ibm.com</a>)</li>

  28.   <li>Nico Seessle (<a href="mailto:nico@seessle.de">nico@seessle.de</a>)</li>

  29.   <li>Jon S. Stevens (<a href="mailto:jon@latchkey.com">jon@latchkey.com</a>)</li>

  30.   <li>Roger Vaughn (<a href="mailto:rvaughn@seaconinc.com">rvaughn@seaconinc.com</a>)</li>

  31.   <li>Dave Walend (<a href="mailto:dwalend@cs.tufts.edu">dwalend@cs.tufts.edu</a>)</li>

  32. </ul>

  33. 

  34. <center>

  35. <p>Version: @VERSION@<br>

  36. $Id$</p>

  37. </center>

  38. 

  39. <hr>

  40. <h2>Table of Contents</h2>

  41. <ul>

  42.   <li><a href="#introduction">Introduction</a></li>

  43.   <li><a href="#getting">Getting Ant</a></li>

  44.   <li><a href="#sysrequirements">System Requirements</a></li>

  45.   <li><a href="#installing">Installing Ant</a></li>

  46.   <li><a href="#buildingant">Building Ant</a></li>

  47.   <li><a href="#running">Running Ant</a></li>

  48.   <li><a href="#buildfile">Writing a Simple Buildfile</a>

  49.   <li><a href="#directorybasedtasks">Directory-based Tasks</a></li>

  50.   <li><a href="#bitasks">Built-in Tasks</a>

  51.   <li><a href="#optionaltasks">Optional Tasks</a>

  52.   <li><a href="#buildevents">Build Events</a>

  53.   <li><a href="#writingowntask">Writing Your Own Task</a></li>

  54.   <li><a href="#faq">FAQ, DTD, External Resources</a>

  55.   <li><a href="../LICENSE">License</a></li>

  56.   <li><a href="#feedback">Feedback</a></li>

  57. </ul>

  58. 

  59. <hr>

  60. <h2><a name="introduction">Introduction</a></h2>

  61. <p>Ant is a Java-based build tool. In theory, it is kind of like

  62. <i>make</i>, without <i>make</i>'s wrinkles.</p>

  63. <h3>Why?</h3>

  64. <p>Why another build tool when there is already

  65. <i>make</i>,

  66. <i>gnumake</i>,

  67. <i>nmake</i>,

  68. <i>jam</i>,

  69. and

  70. others? Because all those tools have limitations that Ant's original author

  71. couldn't live with when developing software across multiple platforms.

  72. Make-like

  73. tools are inherently shell-based: they evaluate a set of dependencies,

  74. then execute commands not unlike what you would issue on a shell.

  75. This means that you

  76. can easily extend these tools by using or writing any program for the OS that

  77. you are working on; however, this also means that you limit yourself to the OS,

  78. or at least the OS type, such as Unix, that you are working on.</p>

  79. <p>Makefiles are inherently evil as well. Anybody who has worked on them for any

  80. time has run into the dreaded tab problem. &quot;Is my command not executing

  81. because I have a space in front of my tab?!!&quot; said the original author of

  82. Ant way too many times. Tools like Jam took care of this to a great degree, but

  83. still have yet another format to use and remember.</p>

  84. <p>Ant is different. Instead of a model where it is extended with shell-based

  85. commands, Ant is extended using Java classes. Instead of writing shell commands,

  86. the configuration files are XML-based, calling out a target tree where various

  87. tasks get executed. Each task is run by an object that implements a particular

  88. Task interface.</p>

  89. <p>Granted, this removes some of the expressive power that is inherent in being

  90. able to construct a shell command such as

  91. <nobr><code>`find . -name foo -exec rm {}`</code></nobr>, but it

  92. gives you the ability to be cross-platform &#150; to work anywhere and

  93. everywhere. And

  94. hey, if you really need to execute a shell command, Ant has an

  95. &lt;exec&gt; task that

  96. allows different commands to be executed based on the OS it is executing

  97. on.</p>

  98. 

  99. <hr>

  100. <h2><a name="getting">Getting Ant</a></h2>

  101. <h3>Binary edition</h3>

  102. <p>The latest stable version of Ant can be downloaded from <a

  103. href="http://jakarta.apache.org/builds/ant/release/v1.2/bin/">

  104. http://jakarta.apache.org/builds/ant/release/v1.2/bin/</a>.

  105. If you like living on the edge, you can download the latest version from <a

  106. href="http://jakarta.apache.org/builds/ant/nightly/">http://jakarta.apache.org/builds/ant/nightly/</a>.</p>

  107. <h3>Source Edition</h3>

  108. <p>If you prefer the source edition, you can download Ant from <a

  109. href="http://jakarta.apache.org/builds/ant/release/v1.2/src/">

  110. http://jakarta.apache.org/builds/ant/release/v1.2/src/</a>

  111. (latest stable) or from <a

  112. href="http://jakarta.apache.org/from-cvs/jakarta-tools/">http://jakarta.apache.org/from-cvs/jakarta-ant/</a>

  113. (current). See the section <a href="#buildingant">Building Ant</a> on how to

  114. build Ant from the source code.</p>

  115. 

  116. <hr>

  117. <h2><a name="sysrequirements">System Requirements</a></h2>

  118. <p>

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

  120. <p>

  121. Both the binary and source distributions of Ant include the reference implementation of JAXP 1.0.

  122. Please see <a href="http://java.sun.com/xml/">http://java.sun.com/xml/</a> for more information. 

  123. If you wish to use a different JAXP-compliant parser, you should remove

  124. <code>jaxp.jar</code> and <code>parser.jar</code>

  125. from Ant's <code>lib/core</code> directory.

  126. You can then either put the jars from your preferred parser into Ant's 

  127. <code>lib/core</code> directory or put the jars on the system classpath.

  128. <p>

  129. For the current version of Ant, you will also need a JDK installed on

  130. your system, version 1.1 or later. A future version of Ant will require

  131. JDK 1.2 or later.

  132. </p>

  133.   

  134. <hr>

  135. <h2><a name="installing">Installing Ant</a></h2>

  136. <p>The binary distribution of Ant consists of four directories:

  137. <code>bin</code>,

  138. <code>docs</code>,

  139. <code>lib</code> and

  140. <code>src</code>. Only the <code>bin</code> 

  141. and <code>lib</code> directories are required for running Ant. To run Ant, the 

  142. following must be done:</p>

  143. <ul>

  144. <li>Add the <code>bin</code> directory to your path.</li>

  145. <li>Set the <code>ANT_HOME</code> environment variable.

  146. This should be set to the directory

  147. that contains the <code>bin</code> and <code>lib</code> directories.</li>

  148. <li>(Optionally) Set the <code>JAVA_HOME</code> environment variable.

  149. (See the <a href="#advanced">Advanced</a> section below.)

  150. This should be set to the directory where the JDK is installed.</li>

  151. </ul>

  152. <h3>Windows</h3>

  153. <p>Assume Ant is installed in <code>c:\ant\</code>. The following sets up the

  154. environment:</p>

  155. <pre>set ANT_HOME=c:\ant

  156. set JAVA_HOME=c:\jdk1.2.2

  157. set PATH=%PATH%;%ANT_HOME%\bin</pre>

  158. <h3>Unix (bash)</h3>

  159. <p>Assume Ant is installed in <code>/usr/local/ant</code>. The following sets up

  160. the environment:</p>

  161. <pre>export ANT_HOME=/usr/local/ant

  162. export JAVA_HOME=/usr/local/jdk-1.2.2

  163. export PATH=${PATH}:${ANT_HOME}/bin</pre>

  164. <a name="advanced">

  165. <h3>Advanced</h3>

  166. </a>

  167. <p>There are lots of variants that can be used to run Ant. What you need is at

  168. least the following:</p>

  169. <blockquote>

  170. The classpath for Ant must contain <code>ant.jar</code> and any jars/classes 

  171. needed for your chosen JAXP-compliant XML parser.</p>

  172. <p>When you need JDK functionality

  173. (such as for the <a href="#javac">javac</a> task or the

  174. <a href="#rmic">rmic</a> task), then for JDK 1.1, the <code>classes.zip</code>

  175. file of the JDK must be added to the classpath; for JDK 1.2 or JDK 1.3, <code>tools.jar</code>

  176. must be added. The scripts supplied with Ant,

  177. in the <code>bin</code> directory, will add 

  178. the required JDK classes automatically, if the <code>JAVA_HOME</code>

  179. environment variable is set.</p>

  180. <p>When you are executing platform-specific applications (such as the <a

  181. href="#exec">exec</a> task or the <a href="#cvs">cvs</a> task), the property <code>ant.home</code>

  182. must be set to the directory containing

  183. the <code>antRun</code> shell script necessary to run exec's on Unix.</p>

  184. </blockquote>

  185. <hr>  

  186. <h2><a name="buildingant">Building Ant</a></h2>

  187. <p>To build Ant, you should install the Ant source distribution.

  188. While the binary distribution 

  189. includes the Ant source code, it is intended for reference purposes only.

  190. The bootstrap and build scripts used to build Ant itself are not included

  191. in the binary distribution.

  192. <p>

  193. <p>Once you have installed the source distribution, go to the 

  194. <code>jakarta-ant</code> directory.</p>

  195. <p>Set the <code>JAVA_HOME</code> environment variable

  196. to the directory where the JDK is installed.

  197. See <a href="#installing">Installing Ant</a>

  198. for examples on how to do this for your operating system. </p>

  199. <p>Make sure you have downloaded any auxilliary jars required to

  200. build tasks you are interested in. These should either be available

  201. on the classpath or added to Ant's <code>lib</code>

  202. directory. The list of auxilliary tasks and requirements is in

  203. <code>lib/README</code>.</p>

  204. 

  205. <p>Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX)

  206. to build a bootstrap version of Ant.</p>

  207. <p>When finished, use:</p>

  208. <blockquote>

  209.   <p><code>build -Dant.dist.dir=&lt;<i>directory_to_contain_Ant_distribution</i>&gt; dist</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>

  210.   <p><code>build.sh -Dant.dist.dir=&lt;<i>directory_to_contain_Ant_distribution</i>&gt; dist</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>

  211. </blockquote>

  212. <p>to create a binary distribution of Ant. This distribution can be

  213. found in the directory you specified.</p>

  214. 

  215. If you wish to install the build into the current <code>ANT_HOME</code>

  216. directory, you can use:

  217. <blockquote>

  218.   <p><code>build install</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>

  219.   <p><code>build.sh install</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>

  220. </blockquote>

  221. 

  222. You can avoid the lengthy Javadoc step, if desired, with:

  223. <blockquote>

  224.   <p><code>build mininstall</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>

  225.   <p><code>build.sh mininstall</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>

  226. </blockquote>

  227. This will only install the <code>bin</code> and <code>lib</code> directories. 

  228. <p>Both the <code>install</code> and 

  229. <code>mininstall</code> targets will overwrite 

  230. the current Ant version in <code>ANT_HOME</code>.

  231. 

  232. <hr>

  233. <h2><a name="running">Running Ant</a></h2>

  234. <p>Running Ant is simple, when you installed it as described in the previous

  235. section. Just type <code>ant</code>.</p>

  236. <p>When nothing is specified, Ant looks for a <code>build.xml</code>

  237. file in the current directory. If found, it uses that file as the

  238. buildfile. If you use the <nobr><code>-find</code></nobr> option,

  239. Ant will search for a buildfile in 

  240. the parent directory, and so on, until the root of the filesystem 

  241. has been reached. To make Ant use

  242. another buildfile, use the command-line

  243. option <code>-buildfile <i>file</i></code>,

  244. where <i>file</i> is the buildfile you want to use.</p>

  245. <p>You can also set properties that override properties specified in the

  246. buildfile (see the <a href="#property">property</a> task). 

  247. This can be done with

  248. the <nobr><code>-D<i>property</i>=<i>value</i></code></nobr> option,

  249. where <i>property</i> is the name of the property,

  250. and <i>value</i> is the value for that property.

  251. This can also be used to have access to your environment variables

  252. (and is the only way, since Java cannot access them).

  253. Just pass <nobr><code>-DMYVAR=%MYVAR%</code></nobr> (Windows) or

  254. <nobr><code>-DMYVAR=$MYVAR</code></nobr> (Unix)

  255. to Ant &#150; you can then access

  256. these variables inside your buildfile as <code>${MYVAR}</code>.</p>

  257. <p>Two more options are: <nobr><code>-quiet</code></nobr>,

  258. which instructs Ant to print less

  259. information on the console when running, and

  260. <nobr><code>-verbose</code></nobr>, which causes Ant to print

  261. additional information to the console.</p>

  262. <p>It is also possible to specify one or more targets that should be executed.

  263. When omitted, the target that is specified in the

  264. <code>default</code> attribute of the <code>&lt;project&gt;</code> tag is

  265. used.</p>

  266. <p>The <nobr><code>-projecthelp</code></nobr>

  267. option gives a list of this project's

  268. targets. First those with a description, then those without one.</p>

  269. <p>Command-line option summary:</p>

  270. <pre>ant [options] [target [target2 [target3] ...]]

  271. Options:

  272. -help                  print this message

  273. -projecthelp           print project help information

  274. -version               print the version information and exit

  275. -quiet                 be extra quiet

  276. -verbose               be extra verbose

  277. -debug                 print debugging information

  278. -emacs                 produce logging information without adornments

  279. -logfile <i>file</i>          use given file for log output

  280. -logger <i>classname</i>      the class that is to perform logging

  281. -listener <i>classname</i>    add an instance of class as a project listener

  282. -buildfile <i>file</i>        use specified buildfile

  283. -find <i>file</i>             search for buildfile towards the root of the filesystem and use the first one found

  284. -D<i>property</i>=<i>value</i>       set <i>property</i> to <i>value</i>

  285. </pre>

  286. <h3>Examples</h3>

  287. <blockquote>

  288.   <pre>ant</pre>

  289. </blockquote>

  290. <p>runs Ant using the <code>build.xml</code> file in the current directory, on

  291. the default target.</p>

  292. <blockquote>

  293.   <pre>ant -buildfile test.xml</pre>

  294. </blockquote>

  295. <p>runs Ant using the <code>test.xml</code> file in the current directory, on

  296. the default target.</p>

  297. <blockquote>

  298.   <pre>ant -buildfile test.xml dist</pre>

  299. </blockquote>

  300. <p>runs Ant using the <code>test.xml</code> file in the current directory, on a

  301. target called <code>dist</code>.</p>

  302. <blockquote>

  303.   <pre>ant -buildfile test.xml -Dbuild=build/classes dist</pre>

  304. </blockquote>

  305. <p>runs Ant using the <code>test.xml</code> file in the current directory, on a

  306. target called <code>dist</code>, setting the <code>build</code> property to the

  307. value <code>build/classes</code>.</p>

  308. 

  309. <h3>Running Ant by Hand</h3>

  310. <p>If you have installed Ant in the do-it-yourself way, Ant can be started

  311. with:</p>

  312. <blockquote>

  313.   <pre>java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre>

  314. </blockquote>

  315. 

  316. <p>These instructions actually do exactly the same as the <code>ant</code>

  317. command. The options and target are the same as when running Ant with the <code>ant</code>

  318. command. This example assumes you have set your classpath to include:

  319. <ul>

  320. <li><code>ant.jar</code>

  321. <li>jars/classes for your XML parser

  322. <li>the JDK's required jar/zip files

  323. </ul>

  324. <hr>

  325. <h2><a name="buildfile">Writing a Simple Buildfile</a></h2>

  326. <p>Ant's buildfiles are written in XML. Each buildfile contains one project.</p>

  327. <p>Each task element of the buildfile can have an <code>id</code> attribute and

  328. can later be referred to by the value supplied to this. The value has

  329. to be unique. (For additional information, see the

  330. <a href="#tasks"> Tasks</a> section below.)</p>

  331. <h3>Projects</h3>

  332. <p>A <i>project</i> has three attributes:</p>

  333. <table border="1" cellpadding="2" cellspacing="0">

  334.   <tr>

  335.     <td valign="top"><b>Attribute</b></td>

  336.     <td valign="top"><b>Description</b></td>

  337.     <td align="center" valign="top"><b>Required</b></td>

  338.   </tr>

  339.   <tr>

  340.     <td valign="top">name</td>

  341.     <td valign="top">the name of the project.</td>

  342.     <td align="center" valign="top">No</td>

  343.   </tr>

  344.   <tr>

  345.     <td valign="top">default</td>

  346.     <td valign="top">the default target to use when no target is supplied.</td>

  347.     <td align="center" valign="top">Yes</td>

  348.   </tr>

  349.   <tr>

  350.     <td valign="top">basedir</td>

  351.     <td valign="top">the base directory from which all path calculations are

  352.       done. This attribute might be overridden by setting

  353.       the &quot;basedir&quot;

  354.       property beforehand. When this is done, it must be omitted in the

  355.       project tag. If neither the attribute nor the property have

  356.       been set, the parent directory of the buildfile will be used.</td>

  357.     <td align="center" valign="top">No</td>

  358.   </tr>

  359. </table>

  360. <p>Each project defines one or more <i>targets</i>.

  361. A target is a set of <i>tasks</i> you want

  362. to be executed. When starting Ant, you can select which target(s) you

  363. want to have executed. When no target is given,

  364. the project's default is used.</p>

  365. 

  366. <h3>Targets</h3>

  367. <p>A target can depend on other targets. You might have a target for compiling,

  368. for example, and a target for creating a distributable. You can only build a

  369. distributable when you have compiled first, so the distribute target

  370. <i>depends on</i> the compile target. Ant resolves these dependencies.</p>

  371. <p>It should be noted, however, that Ant's <code>depends</code> attribute

  372. only specifies the <i>order</i> in which targets should be executed &#150; it

  373. does not affect whether the target that specifies the dependency(s) gets

  374. executed if the dependent target(s) did not (need to) run.

  375. </p>

  376. <p>Ant tries to execute the targets in the <code>depends</code>

  377. attribute in the order

  378. they appear (from left to right). Keep in mind that it is possible that a target

  379. can get executed earlier when an earlier target depends on it:</p>

  380. <blockquote>

  381. <pre>&lt;target name=&quot;A&quot;/&gt;

  382. &lt;target name=&quot;B&quot; depends=&quot;A&quot;/&gt;

  383. &lt;target name=&quot;C&quot; depends=&quot;B&quot;/&gt;

  384. &lt;target name=&quot;D&quot; depends=&quot;C,B,A&quot;/&gt;</pre>

  385. </blockquote>

  386. <p>Suppose we want to execute target D. From its

  387. <code>depends</code> attribute, you

  388. might think that first target C, then B and then A is executed.

  389. Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.</p>

  390. <p>A target gets executed only once, even when more than one target

  391. depends on it (see the previous example).</p>

  392. <p>A target also has the ability to perform its execution if (or

  393. unless) a property has been set. This allows, for example, better

  394. control on the building process depending on the state of the system

  395. (java version, OS, command-line property defines, etc.).  To make a target

  396. <i>sense</i> this property, you should add the <code>if</code> (or

  397. <code>unless</code>) attribute with the name of the property that the target

  398. should react to. For example:</p>

  399. <blockquote>

  400.   <pre>&lt;target name=&quot;build-module-A&quot; if=&quot;module-A-present&quot;/&gt;</pre>

  401.   <pre>&lt;target name=&quot;build-own-fake-module-A&quot; unless=&quot;module-A-present&quot;/&gt;</pre>

  402. </blockquote>

  403. <p>If no <code>if</code> and no <code>unless</code> attribute is present,

  404. the target will always be executed.</p>

  405. <p>The optional <code>description</code> attribute can be used to provide a one-line description of this target, which is printed by the

  406. <nobr><code>-projecthelp</code></nobr> command-line option.</p>

  407. <p>It is a good practice to place your <a

  408. href="#tstamp">tstamp</a> tasks in a so-called

  409. <i>initialization</i> target, on which

  410. all other targets depend. Make sure that target is always the first one in

  411. the depends list of the other targets. In this manual, most initialization targets

  412. have the name &quot;init&quot;.</p>

  413. <p>A target has the following attributes:</p>

  414. <table border="1" cellpadding="2" cellspacing="0">

  415.   <tr>

  416.     <td valign="top"><b>Attribute</b></td>

  417.     <td valign="top"><b>Description</b></td>

  418.     <td align="center" valign="top"><b>Required</b></td>

  419.   </tr>

  420.   <tr>

  421.     <td valign="top">name</td>

  422.     <td valign="top">the name of the target.</td>

  423.     <td align="center" valign="top">Yes</td>

  424.   </tr>

  425.   <tr>

  426.     <td valign="top">depends</td>

  427.     <td valign="top">a comma-separated list of names of targets on which this

  428.       target depends.</td>

  429.     <td align="center" valign="top">No</td>

  430.   </tr>

  431.   <tr>

  432.     <td valign="top">if</td>

  433.     <td valign="top">the name of the property that must be set in order for this

  434.       target to execute.</td>

  435.     <td align="center" valign="top">No</td>

  436.   </tr>

  437.   <tr>

  438.     <td valign="top">unless</td>

  439.     <td valign="top">the name of the property that must not be set in order 

  440.       for this target to execute.</td>

  441.     <td align="center" valign="top">No</td>

  442.   </tr>

  443.   <tr>

  444.     <td valign="top">description</td>

  445.     <td valign="top">a short description of this target's function.</td>

  446.     <td align="center" valign="top">No</td>

  447.   </tr>

  448. </table>

  449. 

  450. <a name="tasks">

  451. <h3>Tasks</h3>

  452. </a>

  453. <p>A task is a piece of code that can be executed.</p>

  454. <p>A task can have multiple attributes (or arguments, if you prefer). The value

  455. of an attribute might contain references to a property. These references will be

  456. resolved before the task is executed.</p>

  457. <p>Tasks have a common structure:</p>

  458. <blockquote>

  459.   <pre>&lt;<i>name</i> <i>attribute1</i>=&quot;<i>value1</i>&quot; <i>attribute2</i>=&quot;<i>value2</i>&quot; ... /&gt;</pre>

  460. </blockquote>

  461. <p>where <i>name</i> is the name of the task,

  462. <i>attributeN</i> is the attribute name, and

  463. <i>valueN</i> is the value for this attribute.</p>

  464. <p>There is a set of <a href="#bitasks">built-in tasks</a>, along with a 

  465. number of

  466. <a href="#optionaltasks"> optional tasks</a>, but it is also very

  467. easy to <a href="#writingowntask">write your own</a>.</p>

  468. <p>All tasks share a task name attribute. The value of

  469. this attribute will be used in the logging messages generated by

  470. Ant.</p>

  471. Tasks can be assigned an <code>id</code> attribute:

  472. <blockquote>

  473. <pre>&lt;<i>taskname</i> id="<i>taskID</i>" ... /&gt;</pre>

  474. </blockquote>

  475. where <i>taskname</i> is the name of the task, and <i>taskID</i> is

  476. a unique name for this task.

  477. You can refer to the

  478. corresponding task object in scripts or other tasks via this name.

  479. For example, in scripts you could do:

  480. <blockquote>

  481. <pre>

  482. &lt;script ... &gt;

  483.   task1.setFoo("bar");

  484. &lt;/script&gt;

  485. </pre>

  486. </blockquote>

  487. to set the <code>foo</code> attribute of this particular task instance.

  488. In another task (written in Java), you can access the instance via

  489. <code>project.getReference("task1")</code>.

  490. <p>

  491. Note<sup>1</sup>: If "task1" has not been run yet, then

  492. it has not been configured (ie., no attributes have been set), and if it is

  493. going to be configured later, anything you've done to the instance may

  494. be overwritten.

  495. </p>

  496. <p>

  497. Note<sup>2</sup>: Future versions of Ant will most likely <i>not</i>

  498. be backward-compatible with this behaviour, since there will likely be no

  499. task instances at all, only proxies.

  500. </p>

  501. 

  502. <h3>Properties</h3>

  503. <p>A project can have a set of properties. These might be set in the buildfile

  504. by the <a href="#property">property task</a>, or might be set outside Ant. A

  505. property has a name and a value. Properties may be used in the value of

  506. task attributes. This is done by placing the property name between

  507. &quot;<code>${</code>&quot; and &quot;<code>}</code>&quot; in the

  508. attribute value. For example,

  509. if there is a &quot;builddir&quot; property with the value

  510. &quot;build&quot;, then this could be used in an attribute like this:

  511. <code>${builddir}/classes</code>.

  512. This is resolved as <code>build/classes</code>.</p>

  513. 

  514. <h3>Built-in Properties</h3>

  515. <p>Ant provides access to all system properties as if they had been

  516. defined using a <code>&lt;property&gt;</code> task.

  517. For example, <code>${os.name}</code> expands to the

  518. name of the operating system.</p>

  519. <p>In addition, Ant has some built-in properties:</p>

  520. <pre>

  521. basedir             the absolute path of the project's basedir (as set

  522.                     with the basedir attribute of &lt;project&gt;).

  523. ant.file            the absolute path of the buildfile.

  524. ant.project.name    the name of the project that is currently executing;

  525.                     it is set in the name attribute of &lt;project&gt;.

  526. ant.java.version    the JVM version Ant detected; currently it can hold

  527.                     the values &quot;1.1&quot;, &quot;1.2&quot; and &quot;1.3&quot;.

  528. </pre>

  529. 

  530. <h3>Example</h3>

  531. <pre>

  532. &lt;project name=&quot;MyProject&quot; default=&quot;dist&quot; basedir=&quot;.&quot;&gt;

  533. 

  534.   &lt;!-- set global properties for this build --&gt;

  535.   &lt;property name=&quot;src&quot; value=&quot;.&quot;/&gt;

  536.   &lt;property name=&quot;build&quot; value=&quot;build&quot;/&gt;

  537.   &lt;property name=&quot;dist&quot;  value=&quot;dist&quot;/&gt;

  538. 

  539.   &lt;target name=&quot;init&quot;&gt;

  540.     &lt;!-- Create the time stamp --&gt;

  541.     &lt;tstamp/&gt;

  542.     &lt;!-- Create the build directory structure used by compile --&gt;

  543.     &lt;mkdir dir=&quot;${build}&quot;/&gt;

  544.   &lt;/target&gt;

  545. 

  546.   &lt;target name=&quot;compile&quot; depends=&quot;init&quot;&gt;

  547.     &lt;!-- Compile the java code from ${src} into ${build} --&gt;

  548.     &lt;javac srcdir=&quot;${src}&quot; destdir=&quot;${build}&quot;/&gt;

  549.   &lt;/target&gt;

  550. 

  551.   &lt;target name=&quot;dist&quot; depends=&quot;compile&quot;&gt;

  552.     &lt;!-- Create the distribution directory --&gt;

  553.     &lt;mkdir dir=&quot;${dist}/lib&quot;/&gt;

  554. 

  555.     &lt;!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file --&gt;

  556.     &lt;jar jarfile=&quot;${dist}/lib/MyProject-${DSTAMP}.jar&quot; basedir=&quot;${build}&quot;/&gt;

  557.   &lt;/target&gt;

  558. 

  559.   &lt;target name=&quot;clean&quot;&gt;

  560.     &lt;!-- Delete the ${build} and ${dist} directory trees --&gt;

  561.     &lt;delete dir=&quot;${build}&quot;/&gt;

  562.     &lt;delete dir=&quot;${dist}&quot;/&gt;

  563.   &lt;/target&gt;

  564. &lt;/project&gt;

  565. </pre>

  566. 

  567. <h3>Token Filters</h3>

  568. <p>A project can have a set of tokens that might be automatically expanded if

  569. found when a file is copied, when the filtering-copy behavior is selected in the

  570. tasks that support this. These might be set in the buildfile

  571. by the <a href="#filter">filter task</a>.&nbsp;</p>

  572. <p>Since this can potentially be a very harmful behavior,

  573. the tokens in the files <b>must</b>

  574. be of the form <code>@</code><i>token</i><code>@</code>, where

  575. <i>token</i> is the token name that is set

  576. in the filter task. This token syntax matches the syntax of other build systems

  577. that perform such filtering and remains sufficiently orthogonal to most

  578. programming and scripting languages, as well as with documentation systems.</p>

  579. <p>Note: If a token with the format <code>@</code><i>token</i><code>@</code>

  580. is found in a file, but no

  581. filter is associated with that token, no changes take place;

  582. therefore, no escaping

  583. method is available &#150; but as long as you choose appropriate names for your

  584. tokens, this should not cause problems.</p>

  585. 

  586. <h3><a name="path">Path-like Structures</a></h3>

  587. <p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type

  588. references using both

  589. &quot;<code>:</code>&quot; and &quot;<code>;</code>&quot; as separator

  590. characters. Ant will

  591. convert the separator to the correct character of the current operating

  592. system.</p>

  593. <p>Wherever path-like values need to be specified, a nested element can

  594. be used. This takes the general form of:</p>

  595. <pre>

  596.     &lt;classpath&gt;

  597.       &lt;pathelement path=&quot;${classpath}&quot;/&gt;

  598.       &lt;pathelement location=&quot;lib/helper.jar&quot;/&gt;

  599.     &lt;/classpath&gt;

  600. </pre>

  601. <p>The <code>location</code> attribute specifies a single file or

  602. directory relative to the project's base directory (or an absolute

  603. filename), while the <code>path</code> attribute accepts colon-

  604. or semicolon-separated lists of locations. The <code>path</code>

  605. attribute is intended to be used with predefined paths &#150; in any other

  606. case, multiple elements with <code>location</code> attributes should be

  607. preferred.</p>

  608. <p>As a shortcut, the <code>&lt;classpath&gt;</code> tag

  609. supports <code>path</code> and

  610. <code>location</code> attributes of its own, so:</p>

  611. <pre>

  612.     &lt;classpath&gt;

  613.       &lt;pathelement path=&quot;${classpath}&quot;/&gt;

  614.     &lt;/classpath&gt;

  615. </pre>

  616. <p>can be abreviated to:</p>

  617. <pre>

  618.     &lt;classpath path=&quot;${classpath}&quot;/&gt;

  619. </pre>

  620. <p>In addition, <a href="#fileset">FileSet</a>s can be specified via

  621. nested <code>&lt;fileset&gt;</code> elements. The order in which the files

  622. building up a fileset are added to the path-like structure is not

  623. defined.</p>

  624. <pre>

  625.     &lt;classpath&gt;

  626.       &lt;pathelement path=&quot;${classpath}&quot;/&gt;

  627.       &lt;fileset dir=&quot;lib&quot;&gt;

  628.         &lt;include name=&quot;**/*.jar&quot;/&gt;

  629.       &lt;/fileset&gt;

  630.       &lt;pathelement location=&quot;classes&quot;/&gt;

  631.     &lt;/classpath&gt;

  632. </pre>

  633. <p>Builds a path that holds the value of <code>${classpath}</code>,

  634. followed by all jar files in the <code>lib</code> directory, followed

  635. by the <code>classes</code> directory.</p>

  636. <p>If you want to use the same path-like structure for several tasks,

  637. you can define them with a <code>&lt;path&gt;</code> element at the

  638. same level as <i>target</i>s, and reference them via their

  639. <i>id</i> attribute &#150; see <a href="#references">References</a> for an

  640. example.</p>

  641. <p>A path-like structure can include a reference to another path-like

  642. structure via nested <code>&lt;path&gt;</code> elements:</p>

  643. <pre>

  644.     &lt;path id=&quot;base.path&quot;&gt;

  645.       &lt;pathelement path=&quot;${classpath}&quot;/&gt;

  646.       &lt;fileset dir=&quot;lib&quot;&gt;

  647.         &lt;include name=&quot;**/*.jar&quot;/&gt;

  648.       &lt;/fileset&gt;

  649.       &lt;pathelement location=&quot;classes&quot;/&gt;

  650.     &lt;/path&gt;

  651. 

  652.     &lt;path id=&quot;tests.path&quot;&gt;

  653.       &lt;path refid=&quot;base.path&quot;/&gt;

  654.       &lt;pathelement location=&quot;testclasses&quot;/&gt;

  655.     &lt;/path&gt;

  656. </pre>

  657. 

  658. <h3><a name="arg">Command-line Arguments</a></h3>

  659. <p>Several tasks take arguments that will be passed to another

  660. process on the command line. To make it easier to specify arguments

  661. that contain space characters, nested <code>arg</code> elements can be used.</p>

  662. <table border="1" cellpadding="2" cellspacing="0">

  663. <tr>

  664.   <td width="12%" valign="top"><b>Attribute</b></td>

  665.   <td width="78%" valign="top"><b>Description</b></td>

  666.   <td width="10%" valign="top"><b>Required</b></td>

  667. </tr>

  668.   <tr>

  669.     <td valign="top">value</td> 

  670.     <td valign="top">a single command-line argument; can contain space

  671.       characters.</td>

  672.     <td align="center" rowspan="4">Exactly one of these.</td>

  673.   </tr>

  674.   <tr>

  675.     <td valign="top">line</td> 

  676.     <td valign="top">a space-delimited list of command-line arguments.</td>

  677.   </tr>

  678.   <tr>

  679.     <td valign="top">file</td> 

  680.     <td valign="top">The name of a file as a single command-line

  681.       argument; will be replaced with the absolute filename of the file.</td>

  682.   </tr>

  683.   <tr>

  684.     <td valign="top">path</td> 

  685.     <td valign="top">A string that will be treated as a path-like

  686.       string as a single command-line argument; you can use <code>;</code>

  687.       or <code>:</code> as

  688.       path separators and Ant will convert it to the platform's local

  689.       conventions.</td>

  690.   </tr>

  691. </table>

  692. <h4>Examples</h4>

  693. <blockquote><pre>

  694.   &lt;arg value=&quot;-l -a&quot;/&gt;

  695. </pre></blockquote>

  696. <p>is a single command-line argument containing a space character.</p>

  697. <blockquote><pre>

  698.   &lt;arg line=&quot;-l -a&quot;/&gt;

  699. </pre></blockquote>

  700. <p>represents two separate command-line arguments.</p>

  701. <blockquote><pre>

  702.   &lt;arg path=&quot;/dir;/dir2:\dir3&quot;/&gt;

  703. </pre></blockquote>

  704. <p>is a single command-line argument with the value

  705. <code>\dir;\dir2;\dir3</code> on DOS-based systems and

  706. <code>/dir:/dir2:/dir3</code> on Unix-like systems.</p>

  707. 

  708. <h3><a name="references">References</a></h3>

  709. <p>The <code>id</code> attribute of the buildfile's elements can be

  710. used to refer to them. This can useful if you are going to replicate

  711. the same snippet of XML over and over again &#150; using a

  712. <code>&lt;classpath&gt;</code> structure more than once for

  713. example.</p>

  714. <p>The following example:</p>

  715. <blockquote><pre>

  716. &lt;project ... &gt;

  717.   &lt;target ... &gt;

  718.     &lt;rmic ...&gt;

  719.       &lt;classpath&gt;

  720.         &lt;pathelement location=&quot;lib/&quot;/&gt;

  721.         &lt;pathelement path=&quot;${java.class.path}/&quot;/&gt;

  722.         &lt;pathelement path=&quot;${additional.path}&quot;/&gt;

  723.       &lt;/classpath&gt;

  724.     &lt;/rmic&gt;

  725.   &lt;/target&gt;

  726. 

  727.   &lt;target ... &gt;

  728.     &lt;javac ...&gt;

  729.       &lt;classpath&gt;

  730.         &lt;pathelement location=&quot;lib/&quot;/&gt;

  731.         &lt;pathelement path=&quot;${java.class.path}/&quot;/&gt;

  732.         &lt;pathelement path=&quot;${additional.path}&quot;/&gt;

  733.       &lt;/classpath&gt;

  734.     &lt;/javac&gt;

  735.   &lt;/target&gt;

  736. &lt;/project&gt;

  737. </pre></blockquote>

  738. <p>could be rewritten as:</p>

  739. <blockquote><pre>

  740. &lt;project ... &gt;

  741.   &lt;path id=&quot;project.class.path&quot;&gt;

  742.     &lt;pathelement location=&quot;lib/&quot;/&gt;

  743.     &lt;pathelement path=&quot;${java.class.path}/&quot;/&gt;

  744.     &lt;pathelement path=&quot;${additional.path}&quot;/&gt;

  745.   &lt;/path&gt;

  746. 

  747.   &lt;target ... &gt;

  748.     &lt;rmic ...&gt;

  749.       &lt;classpath refid=&quot;project.class.path&quot;/&gt;

  750.     &lt;/rmic&gt;

  751.   &lt;/target&gt;

  752. 

  753.   &lt;target ... &gt;

  754.     &lt;javac ...&gt;

  755.       &lt;classpath refid=&quot;project.class.path&quot;/&gt;

  756.     &lt;/javac&gt;

  757.   &lt;/target&gt;

  758. &lt;/project&gt;

  759. </pre></blockquote>

  760. <p>All tasks that use nested elements for <a

  761. href="#patternset">PatternSet</a>s, <a href="#fileset">FileSet</a>s or

  762. <a href="#path">path-like structures</a> accept references to these

  763. structures as well.</p>

  764. 

  765. <hr>

  766. <h2><a name="directorybasedtasks">Directory-based Tasks</a></h2>

  767. <p>Some tasks use directory trees for the task they perform.

  768. For example, the <a

  769. href="#javac">javac</a> task, which works upon a directory tree

  770. with <code>.java</code> files.

  771. Sometimes it can be very useful to work on a subset of that directory tree. This

  772. section describes how you can select a subset of such a directory tree.</p>

  773. <p>Ant gives you two ways to create a subset, both of which can be used at the same

  774. time:</p>

  775. <ul>

  776.   <li>Only include files/directories that match at least one pattern of a set of

  777.     patterns.</li>

  778.   <li>Exclude files/directories that match at least one pattern a set of

  779.     patterns.</li>

  780. </ul>

  781. <p>When both inclusion and exclusion are used, only files/directories that match

  782. the include patterns, and don't match the exclude patterns, are used.</p>

  783. <p>Patterns can be specified inside the buildfile via task attributes or

  784. nested elements and via external files. Each line of the external file

  785. is taken as a pattern that is added to the list of include or exclude 

  786. patterns.</p>

  787. <h3>Patterns</h3>

  788. <p>As described earlier, patterns are used for the inclusion and exclusion.

  789. These patterns look very much like the patterns used in DOS and UNIX:</p>

  790. <p>'*' matches zero or more characters, '?' matches one character.</p>

  791. <p><b>Examples:</b></p>

  792. <p>

  793. <code>*.java</code>&nbsp;&nbsp;matches&nbsp;&nbsp;<code>.java</code>,

  794. <code>x.java</code> and <code>FooBar.java</code>, but

  795. not <code>FooBar.xml</code> (does not end with <code>.java</code>).</p>

  796. <p>

  797. <code>?.java</code>&nbsp;&nbsp;matches&nbsp;&nbsp;<code>x.java</code>,

  798. <code>A.java</code>, but not <code>.java</code> or <code>xyz.java</code>

  799. (both don't have one character before <code>.java</code>).</p>

  800. <p>

  801. Combinations of <code>*</code>'s and <code>?</code>'s are allowed.</p>

  802. <p>Matching is done per-directory. This means that first the first directory in

  803. the pattern is matched against the first directory in the path to match. Then

  804. the second directory is matched, and so on. For example, when we have the pattern <code>/?abc/*/*.java</code>

  805. and the path <code>/xabc/foobar/test.java</code>,

  806. the first <code>?abc</code> is matched with <code>xabc</code>,

  807. then <code>*</code> is matched with <code>foobar</code>,

  808. and finally <code>*.java</code> is matched with <code>test.java</code>.

  809. They all match, so the path matches the pattern.</p>

  810. <p>To make things a bit more flexible, we add one extra feature, which makes it

  811. possible to match multiple directory levels. This can be used to match a

  812. complete directory tree, or a file anywhere in the directory tree.

  813. To do this, <code>**</code>

  814. must be used as the name of a directory.

  815. When <code>**</code> is used as the name of a

  816. directory in the pattern, it matches zero or more directories.

  817. For example:

  818. <code>/test/**</code> matches all files/directories under <code>/test/</code>,

  819. such as <code>/test/x.java</code>,

  820. or <code>/test/foo/bar/xyz.html</code>, but not <code>/xyz.xml</code>.</p>

  821. <p>There is one &quot;shorthand&quot; &#150; if a pattern ends

  822. with <code>/</code>

  823. or <code>\</code>, then <code>**</code>

  824. is appended.

  825. For example, <code>mypackage/test/</code> is interpreted as if it were

  826. <code>mypackage/test/**</code>.</p>

  827. <p><b>Example patterns:</b></p>

  828. <table border="1" cellpadding="2" cellspacing="0">

  829.   <tr>

  830.     <td valign="top"><code>**/CVS/*</code></td>

  831.     <td valign="top">Matches all files in <code>CVS</code> directories that can be located

  832.       anywhere in the directory tree.<br>

  833.       Matches:

  834.       <pre>

  835.       CVS/Repository

  836.       org/apache/CVS/Entries

  837.       org/apache/jakarta/tools/ant/CVS/Entries

  838.       </pre>

  839.       But not:

  840.       <pre>

  841.       org/apache/CVS/foo/bar/Entries (<code>foo/bar/</code> part does not match)</td>

  842.       </pre>

  843.   </tr>

  844.   <tr>

  845.     <td valign="top"><code>org/apache/jakarta/**</code></td>

  846.     <td valign="top">Matches all files in the <code>org/apache/jakarta</code> directory tree.<br>

  847.       Matches:

  848.       <pre>

  849.       org/apache/jakarta/tools/ant/docs/index.html

  850.       org/apache/jakarta/test.xml

  851.       </pre>

  852.       But not:

  853.       <pre>

  854.       org/apache/xyz.java

  855.       </pre>

  856.       (<code>jakarta/</code> part is missing).</td>

  857.   </tr>

  858.   <tr>

  859.     <td valign="top"><code>org/apache/**/CVS/*</code></td>

  860.     <td valign="top">Matches all files in <code>CVS</code> directories

  861.       that are located anywhere in the directory tree under

  862.       <code>org/apache</code>.<br>

  863.       Matches:

  864.       <pre>

  865.       org/apache/CVS/Entries

  866.       org/apache/jakarta/tools/ant/CVS/Entries

  867.       </pre>

  868.       But not:

  869.       <pre>

  870.       org/apache/CVS/foo/bar/Entries

  871.       </pre>

  872.       (<code>foo/bar/</code> part does not match)</td>

  873.   </tr>

  874.   <tr>

  875.     <td valign="top"><code>**/test/**</code></td>

  876.     <td valign="top">Matches all files that have a <code>test</code>

  877.         element in their path, including <code>test</code> as a filename.</td>

  878.   </tr>

  879. </table>

  880. <p>When these patterns are used in inclusion and exclusion, you have a powerful

  881. way to select just the files you want.</p>

  882. 

  883. <h3>Examples</h3>

  884. <pre>  

  885. &lt;copy todir=&quot;${dist}&quot;>

  886.   &lt;fileset dir=&quot;${src}&quot; 

  887.            includes=&quot;**/images/*&quot; 

  888.            excludes=&quot;**/*.gif&quot; 

  889.   /&gt;

  890. &lt;/copy&gt;</pre>

  891. <p>This copies all files in directories called <code>images</code> that are

  892. located in the directory tree defined by <code>${src}</code> to the

  893. destination directory defined by <code>${dist}</code>,

  894. but excludes all <code>*.gif</code> files from the copy.</p>

  895. <p> This example can also be expressed using nested elements:

  896. <pre>

  897. &lt;copy todir=&quot;${dist}&quot;>

  898.   &lt;fileset dir=&quot;${src}&quot;/&gt;

  899.     &lt;include name=&quot;**/images/*&quot;/&gt;

  900.     &lt;exclude name=&quot;**/*.gif&quot;/&gt;

  901.   &lt;/fileset&gt;

  902. &lt;/copy&gt;

  903. </pre>

  904. 

  905. <h3>Default Excludes</h3>

  906. <p>There are a set of definitions that are excluded by default from all directory-based tasks.

  907. They are:

  908. <pre>

  909.      **/*~

  910.      **/#*#

  911.      **/%*%

  912.      **/CVS

  913.      **/CVS/**

  914.      **/.cvsignore

  915. </pre>

  916. If you do not want these default excludes applied, you may disable them with the 

  917. <code>defaultexcludes=&quot;no&quot;</code> attribute.

  918. <h3><a name="patternset">PatternSets</a></h3>

  919. <p>Patterns can be grouped to sets and later be referenced by their

  920. <code>id</code>

  921. attribute. They are defined via a <code>patternset</code> element,

  922. which can appear nested into a <a href="#fileset">FileSet</a> or a

  923. directory-based task that constitutes an implicit FileSet. In addition,

  924. <code>patternset</code>s can be defined at the same level as

  925. <code>target</code> &#151; i.e., as children of <code>project</code>.</p>

  926. <p>Patterns can be specified by nested <code>&lt;include&gt;</code> or

  927. <code>&lt;exclude&gt;</code> elements or the following attributes.</p>

  928. <table border="1" cellpadding="2" cellspacing="0">

  929.   <tr>

  930.     <td valign="top"><b>Attribute</b></td>

  931.     <td valign="top"><b>Description</b></td>

  932.   </tr>

  933.   <tr>

  934.     <td valign="top">includes</td>

  935.     <td valign="top">comma-separated list of patterns of files that must be

  936.       included. All files are included when omitted.</td>

  937.   </tr>

  938.   <tr>

  939.     <td valign="top">includesfile</td>

  940.     <td valign="top">the name of a file; each line of this file is

  941.       taken to be an include pattern.</td>

  942.   </tr>

  943.   <tr>

  944.     <td valign="top">excludes</td>

  945.     <td valign="top">comma-separated list of patterns of files that must be

  946.       excluded; no files (except default excludes) are excluded when omitted.</td>

  947.   </tr>

  948.   <tr>

  949.     <td valign="top">excludesfile</td>

  950.     <td valign="top">the name of a file; each line of this file is

  951.       taken to be an exclude pattern.</td>

  952.   </tr>

  953. </table>

  954. 

  955. <h4>Examples</h4>

  956. <blockquote><pre>

  957. &lt;patternset id=&quot;non.test.sources&quot; &gt;

  958.   &lt;include name=&quot;**/*.java&quot;/&gt;

  959.   &lt;exclude name=&quot;**/*Test*&quot;/&gt;

  960. &lt;/patternset&gt;

  961. </pre></blockquote>

  962. <p>Builds a set of patterns that matches all <code>.java</code> files

  963. that do not contain the text <code>Test</code> in their name. This set

  964. can be <a href="#references">referred</a> to via

  965. <code>&lt;patternset refid=&quot;non.test.sources&quot;/&gt;</code>,

  966. by tasks that support this feature, or by FileSets.</p>

  967. <p>Note that while the <code>includes</code> and

  968. <code>excludes</code> attributes accept

  969. multiple elements separated by commas or spaces, the nested

  970. &lt;include&gt; and &lt;exclude&gt; elements expect their name

  971. attribute to hold a single pattern.</p>

  972. 

  973. <h3><a name="fileset">FileSets</a></h3>

  974. <p>FileSets are groups of files. These files can be found in a

  975. directory tree starting in a base directory and are matched by

  976. patterns taken from a number of <a

  977. href="#patternset">PatternSets</a>. FileSets can appear inside tasks

  978. that support this feature or at the same level as <code>target</code>

  979. &#150; i.e., as children of <code>project</code>.</p>

  980. <p>PatternSets can be specified as nested

  981. <code>&lt;patternset&gt;</code> 

  982. elements. In addition, FileSet holds an implicit PatternSet and

  983. supports the nested <code>&lt;include&gt;</code> and

  984. <code>&lt;exclude&gt;</code> elements of PatternSet directly, as well

  985. as PatternSet's attributes.</p>

  986. <table border="1" cellpadding="2" cellspacing="0">

  987.   <tr>

  988.     <td valign="top"><b>Attribute</b></td>

  989.     <td valign="top"><b>Description</b></td>

  990.     <td align="center" valign="top"><b>Required</b></td>

  991.   </tr>

  992.   <tr>

  993.     <td valign="top">dir</td>

  994.     <td valign="top">the root of the directory tree of this FileSet.</td>

  995.     <td valign="top" align="center">Yes</td>

  996.   </tr>

  997.   <tr>

  998.     <td valign="top">defaultexcludes</td>

  999.     <td valign="top">indicates whether default excludes should be used or not

  1000.       (<code>yes | no</code>); default excludes are used when omitted.</td>

  1001.     <td valign="top" align="center">No</td>

  1002.   </tr>

  1003.   <tr>

  1004.     <td valign="top">includes</td>

  1005.     <td valign="top">comma-separated list of patterns of files that must be

  1006.       included; all files are included when omitted.</td>

  1007.     <td valign="top" align="center">No</td>

  1008.   </tr>

  1009.   <tr>

  1010.     <td valign="top">includesfile</td>

  1011.     <td valign="top">the name of a file; each line of this file is

  1012.       taken to be an include pattern.</td>

  1013.     <td valign="top" align="center">No</td>

  1014.   </tr>

  1015.   <tr>

  1016.     <td valign="top">excludes</td>

  1017.     <td valign="top">comma-separated list of patterns of files that must be

  1018.       excluded; no files (except default excludes) are excluded when omitted.</td>

  1019.     <td valign="top" align="center">No</td>

  1020.   </tr>

  1021.   <tr>

  1022.     <td valign="top">excludesfile</td>

  1023.     <td valign="top">the name of a file; each line of this file is

  1024.       taken to be an exclude pattern.</td>

  1025.     <td valign="top" align="center">No</td>

  1026.   </tr>

  1027. </table>

  1028. 

  1029. <h4>Examples</h4>

  1030. <blockquote><pre>

  1031. &lt;fileset dir=&quot;${server.src}&quot; &gt;

  1032.   &lt;patternset id=&quot;non.test.sources&quot; &gt;

  1033.     &lt;include name=&quot;**/*.java&quot;/&gt;

  1034.     &lt;exclude name=&quot;**/*Test*&quot;/&gt;

  1035.   &lt;/patternset&gt;

  1036. &lt;/fileset&gt;

  1037. </pre></blockquote>

  1038. <p>Groups all files in directory <code>${server.src}</code> that are Java

  1039. source files and don't have the text <code>Test</code> in their

  1040. name.</p>

  1041. <blockquote><pre>

  1042. &lt;fileset dir=&quot;${client.src}&quot; &gt;

  1043.   &lt;patternset refid=&quot;non.test.sources&quot;/&gt;

  1044. &lt;/fileset&gt;

  1045. </pre></blockquote>

  1046. <p>Groups all files in directory <code>${client.src}</code>, using the

  1047. same patterns as the example above.</p>

  1048. 

  1049. <h3><a name="mapper">Mapping File Names</a></h3>

  1050. <p>Some tasks take source files and create target files. Depending on

  1051. the task, it may be quite obvious which name a target file will have

  1052. (using <a href="#javac">javac</a>, you know there will be

  1053. <code>.class</code> files for your <code>.java</code> files) &#150; in

  1054. other cases you may want to specify the target files, either to help

  1055. Ant or to get an extra bit of functionality.</p>

  1056. <p>While source files are usually specified as <a

  1057. href="#fileset">fileset</a>s, you don't specify target files directly &#150;

  1058. instead, you tell Ant how to find the target file(s) for one source file. An

  1059. instance of <code>org.apache.tools.ant.util.FileNameMapper</code> is

  1060. responsible for this. It constructs target file names based on rules

  1061. that can be parameterized with <code>from</code> and <code>to</code>

  1062. attributes &#150; the exact meaning of which is implementation-dependent.</p>

  1063. <p>These instances are defined in <code>&lt;mapper&gt;</code> elements

  1064. with the following attributes:</p>

  1065. <table border="1" cellpadding="2" cellspacing="0">

  1066.   <tr>

  1067.     <td valign="top"><b>Attribute</b></td>

  1068.     <td valign="top"><b>Description</b></td>

  1069.     <td align="center" valign="top"><b>Required</b></td>

  1070.   </tr>

  1071.   <tr>

  1072.     <td valign="top">type</td>

  1073.     <td valign="top">specifies one of the built-in implementations.</td>

  1074.     <td align="center" valign="center" rowspan="2">Exactly one of both</td>

  1075.   </tr>

  1076.   <tr>

  1077.     <td valign="top">classname</td>

  1078.     <td valign="top">specifies the implementation by class name.</td>

  1079.   </tr>

  1080.   <tr>

  1081.     <td valign="top">classpath</td> 

  1082.     <td valign="top">the classpath to use when looking up

  1083.       <code>classname</code>.</td>

  1084.     <td align="center" valign="top">No</td>

  1085.   </tr>

  1086.   <tr>

  1087.     <td valign="top">classpathref</td>

  1088.     <td valign="top">the classpath to use, given as <a

  1089.       href="#references">reference</a> to a path defined elsewhere.</td>

  1090.     <td align="center" valign="top">No</td>

  1091.   </tr>

  1092.   <tr>

  1093.     <td valign="top">from</td> 

  1094.     <td valign="top">the <code>from</code> attribute for the given

  1095.       implementation.</td>

  1096.     <td align="center" valign="top">Depends on implementation.</td>

  1097.   </tr>

  1098.   <tr>

  1099.     <td valign="top">to</td> 

  1100.     <td valign="top">the <code>to</code> attribute for the given

  1101.       implementation.</td>

  1102.     <td align="center" valign="top">Depends on implementation.</td>

  1103.   </tr>

  1104. </table>

  1105. <p>The classpath can be specified via a nested

  1106. <code>&lt;classpath&gt;</code>, as well &#150; that is,

  1107. a <a href="#path">path</a>-like structure.</p>

  1108. <p>The built-in mapper types are:</p>

  1109. <h4><a name="identity-mapper">identity</a></h4>

  1110. <p>The target file name is identical to the source file name. Both

  1111. <code>to</code> and <code>from</code> will be ignored.</p>

  1112. <b>Examples:</b>

  1113. <blockquote><pre>

  1114. &lt;mapper type=&quot;identity&quot;/&gt;

  1115. </pre></blockquote>

  1116. <table border="1" cellpadding="2" cellspacing="0">

  1117.   <tr>

  1118.     <td valign="top"><b>Source file name</b></td>

  1119.     <td valign="top"><b>Target file name</b></td>

  1120.   </tr>

  1121.   <tr>

  1122.     <td valign="top"><code>A.java</code></td>

  1123.     <td valign="top"><code>A.java</code></td>

  1124.   </tr>

  1125.   <tr>

  1126.     <td valign="top"><code>foo/bar/B.java</code></td>

  1127.     <td valign="top"><code>foo/bar/B.java</code></td>

  1128.   </tr>

  1129.   <tr>

  1130.     <td valign="top"><code>C.properties</code></td>

  1131.     <td valign="top"><code>C.properties</code></td>

  1132.   </tr>

  1133.   <tr>

  1134.     <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>

  1135.     <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>

  1136.   </tr>

  1137. </table>

  1138. <h4><a name="flatten-mapper">flatten</a></h4>

  1139. <p>The target file name is identical to the source file name, with all

  1140. leading directory information stripped off. Both <code>to</code> and

  1141. <code>from</code> will be ignored.</p>

  1142. <b>Examples:</b>

  1143. <blockquote><pre>

  1144. &lt;mapper type=&quot;flatten&quot;/&gt;

  1145. </pre></blockquote>

  1146. <table border="1" cellpadding="2" cellspacing="0">

  1147.   <tr>

  1148.     <td valign="top"><b>Source file name</b></td>

  1149.     <td valign="top"><b>Target file name</b></td>

  1150.   </tr>

  1151.   <tr>

  1152.     <td valign="top"><code>A.java</code></td>

  1153.     <td valign="top"><code>A.java</code></td>

  1154.   </tr>

  1155.   <tr>

  1156.     <td valign="top"><code>foo/bar/B.java</code></td>

  1157.     <td valign="top"><code>B.java</code></td>

  1158.   </tr>

  1159.   <tr>

  1160.     <td valign="top"><code>C.properties</code></td>

  1161.     <td valign="top"><code>C.properties</code></td>

  1162.   </tr>

  1163.   <tr>

  1164.     <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>

  1165.     <td valign="top"><code>A.properties</code></td>

  1166.   </tr>

  1167. </table>

  1168. <h4><a name="merge-mapper">merge</a></h4>

  1169. <p>The target file name will always be the same, as defined by

  1170. <code>to</code> &#150; <code>from</code> will be ignored.</p>

  1171. <h5>Examples:</h5>

  1172. <blockquote><pre>

  1173. &lt;mapper type=&quot;merge&quot; to=&quot;archive.tar&quot;/&gt;

  1174. </pre></blockquote>

  1175. <table border="1" cellpadding="2" cellspacing="0">

  1176.   <tr>

  1177.     <td valign="top"><b>Source file name</b></td>

  1178.     <td valign="top"><b>Target file name</b></td>

  1179.   </tr>

  1180.   <tr>

  1181.     <td valign="top"><code>A.java</code></td>

  1182.     <td valign="top"><code>archive.tar</code></td>

  1183.   </tr>

  1184.   <tr>

  1185.     <td valign="top"><code>foo/bar/B.java</code></td>

  1186.     <td valign="top"><code>archive.tar</code></td>

  1187.   </tr>

  1188.   <tr>

  1189.     <td valign="top"><code>C.properties</code></td>

  1190.     <td valign="top"><code>archive.tar</code></td>

  1191.   </tr>

  1192.   <tr>

  1193.     <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>

  1194.     <td valign="top"><code>archive.tar</code></td>

  1195.   </tr>

  1196. </table>

  1197. <h4><a name="glob-mapper">glob</a></h4>

  1198. <p>Both <code>to</code> and <code>from</code> define patterns that may

  1199. contain at most one <code>*</code>. For each source file that matches

  1200. the <code>from</code> pattern, a target file name will be constructed

  1201. from the <code>to</code> pattern by substituting the <code>*</code> in

  1202. the <code>to</code> pattern with the text that matches the

  1203. <code>*</code> in the <code>from</code> pattern. Source file names

  1204. that don't match the <code>from</code> pattern will be ignored.</p>

  1205. <b>Examples:</b>

  1206. <blockquote><pre>

  1207. &lt;mapper type=&quot;glob&quot; from=&quot;*.java&quot; to=&quot;*.java.bak&quot;/&gt;

  1208. </pre></blockquote>

  1209. <table border="1" cellpadding="2" cellspacing="0">

  1210.   <tr>

  1211.     <td valign="top"><b>Source file name</b></td>

  1212.     <td valign="top"><b>Target file name</b></td>

  1213.   </tr>

  1214.   <tr>

  1215.     <td valign="top"><code>A.java</code></td>

  1216.     <td valign="top"><code>A.java.bak</code></td>

  1217.   </tr>

  1218.   <tr>

  1219.     <td valign="top"><code>foo/bar/B.java</code></td>

  1220.     <td valign="top"><code>foo/bar/B.java.bak</code></td>

  1221.   </tr>

  1222.   <tr>

  1223.     <td valign="top"><code>C.properties</code></td>

  1224.     <td valign="top">ignored</td>

  1225.   </tr>

  1226.   <tr>

  1227.     <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>

  1228.     <td valign="top">ignored</td>

  1229.   </tr>

  1230. </table>

  1231. <blockquote><pre>

  1232. &lt;mapper type=&quot;glob&quot; from=&quot;C*ies&quot; to=&quot;Q*y&quot;/&gt;

  1233. </pre></blockquote>

  1234. <table border="1" cellpadding="2" cellspacing="0">

  1235.   <tr>

  1236.     <td valign="top"><b>Source file name</b></td>

  1237.     <td valign="top"><b>Target file name</b></td>

  1238.   </tr>

  1239.   <tr>

  1240.     <td valign="top"><code>A.java</code></td>

  1241.     <td valign="top">ignored</td>

  1242.   </tr>

  1243.   <tr>

  1244.     <td valign="top"><code>foo/bar/B.java</code></td>

  1245.     <td valign="top">ignored</td>

  1246.   </tr>

  1247.   <tr>

  1248.     <td valign="top"><code>C.properties</code></td>

  1249.     <td valign="top"><code>Q.property</code></td>

  1250.   </tr>

  1251.   <tr>

  1252.     <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>

  1253.     <td valign="top"><code>Qlasses/dir/dir2/A.property</td>

  1254.   </tr>

  1255. </table>

  1256. <h4><a name="regexp-mapper">regexp</a></h4>

  1257. <p>Both <code>to</code> and <code>from</code> define regular

  1258. expressions. If the source file name matches the <code>from</code>

  1259. pattern, the target file name will be constructed from the

  1260. <code>to</code> pattern, using <code>\0</code> to <code>\9</code> as

  1261. back-references for the full

  1262. match (<code>\0</code>) or the matches of the subexpressions in

  1263. parentheses.

  1264. Source

  1265. files not matching the <code>from</code> pattern will be ignored.</p>

  1266. <p>Note that you need to escape a dollar-sign (<code>$</code>) with

  1267. another dollar-sign in Ant.</p>

  1268. <p>The regexp mapper needs a supporting library and an implementation

  1269. of <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that

  1270. hides the specifics of the library. Ant comes with implementations for

  1271. <a href="http://jakarta.apache.org/regexp/">jakarta-regexp</a> and <a

  1272. href="http://jakarta.apache.org/oro/">jakarta-ORO</a>. If you compile

  1273. from sources and plan to use one of them, make sure the libraries are

  1274. in your <code>CLASSPATH</code>.</a> For information about using <a

  1275. href="http://www.cacas.org/~wes/java/">gnu.regexp</a> or <a

  1276. href="http://www.crocodile.org/~sts/Rex/">gnu.rex</a> with Ant, see <a

  1277. href="http://marc.theaimsgroup.com/?l=ant-dev&m=97550753813481&w=2">this</a>

  1278. article.</p>

  1279. <p>Ant will choose the regular-expression library based on the

  1280. following algorithm:

  1281. <ul>

  1282. <li>If the system property

  1283. <code>ant.regexp.matcherimpl</code> has been set, it is taken as the

  1284. name of the class implementing

  1285. <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that

  1286. should be used.</li>

  1287. <li>If it has not been set, first try jakarta-ORO; if that

  1288. cannot be found, try jakarta-regexp.</li>

  1289. </ul>

  1290. </p>

  1291. <b>Examples:</b>

  1292. <blockquote><pre>

  1293. &lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)\.java$$&quot; to=&quot;\1.java.bak&quot;/&gt;

  1294. </pre></blockquote>

  1295. <table border="1" cellpadding="2" cellspacing="0">

  1296.   <tr>

  1297.     <td valign="top"><b>Source file name</b></td>

  1298.     <td valign="top"><b>Target file name</b></td>

  1299.   </tr>

  1300.   <tr>

  1301.     <td valign="top"><code>A.java</code></td>

  1302.     <td valign="top"><code>A.java.bak</code></td>

  1303.   </tr>

  1304.   <tr>

  1305.     <td valign="top"><code>foo/bar/B.java</code></td>

  1306.     <td valign="top"><code>foo/bar/B.java.bak</code></td>

  1307.   </tr>

  1308.   <tr>

  1309.     <td valign="top"><code>C.properties</code></td>

  1310.     <td valign="top">ignored</td>

  1311.   </tr>

  1312.   <tr>

  1313.     <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>

  1314.     <td valign="top">ignored</td>

  1315.   </tr>

  1316. </table>

  1317. <blockquote><pre>

  1318. &lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)/([^/]+)/([^/]*)$$&quot; to=&quot;\1/\2/\2-\3&quot;/&gt;

  1319. </pre></blockquote>

  1320. <table border="1" cellpadding="2" cellspacing="0">

  1321.   <tr>

  1322.     <td valign="top"><b>Source file name</b></td>

  1323.     <td valign="top"><b>Target file name</b></td>

  1324.   </tr>

  1325.   <tr>

  1326.     <td valign="top"><code>A.java</code></td>

  1327.     <td valign="top">ignored</td>

  1328.   </tr>

  1329.   <tr>

  1330.     <td valign="top"><code>foo/bar/B.java</code></td>

  1331.     <td valign="top"><code>foo/bar/bar-B.java</code></td>

  1332.   </tr>

  1333.   <tr>

  1334.     <td valign="top"><code>C.properties</code></td>

  1335.     <td valign="top">ignored</td>

  1336.   </tr>

  1337.   <tr>

  1338.     <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>

  1339.     <td valign="top"><code>Classes/dir/dir2/dir2-A.properties</code></td>

  1340.   </tr>

  1341. </table>

  1342. <blockquote><pre>

  1343. &lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)\.(.*)$$&quot; to=&quot;\2.\1&quot;/&gt;

  1344. </pre></blockquote>

  1345. <table border="1" cellpadding="2" cellspacing="0">

  1346.   <tr>

  1347.     <td valign="top"><b>Source file name</b></td>

  1348.     <td valign="top"><b>Target file name</b></td>

  1349.   </tr>

  1350.   <tr>

  1351.     <td valign="top"><code>A.java</code></td>

  1352.     <td valign="top"><code>java.A</code></td>

  1353.   </tr>

  1354.   <tr>

  1355.     <td valign="top"><code>foo/bar/B.java</code></td>

  1356.     <td valign="top"><code>java.foo/bar/B</code></td>

  1357.   </tr>

  1358.   <tr>

  1359.     <td valign="top"><code>C.properties</code></td>

  1360.     <td valign="top"><code>properties.C</code></td>

  1361.   </tr>

  1362.   <tr>

  1363.     <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>

  1364.     <td valign="top"><code>properties.Classes/dir/dir2/A</code></td>

  1365.   </tr>

  1366. </table>

  1367. 

  1368. <hr>

  1369. <h2><a name="bitasks">Built-in Tasks</a></h2>

  1370. <ul>

  1371.   <li><a href="#ant">Ant</a></li>

  1372.   <li><a href="#antcall">AntCall</a></li>

  1373.   <li><a href="#antstructure">AntStructure</a></li>

  1374.   <li><a href="#available">Available</a></li>

  1375.   <li><a href="#chmod">Chmod</a></li>

  1376.   <li><a href="#copy">Copy</a></li>

  1377.   <li><a href="#copydir">Copydir</a></li>

  1378.   <li><a href="#copyfile">Copyfile</a></li>

  1379.   <li><a href="#cvs">Cvs</a></li>

  1380.   <li><a href="#delete">Delete</a></li>

  1381.   <li><a href="#deltree">Deltree</a></li>

  1382.   <li><a href="#echo">Echo</a></li>

  1383.   <li><a href="#exec">Exec</a></li>

  1384.   <li><a href="#execon">ExecOn</a></li>

  1385.   <li><a href="#fail">Fail</a></li>

  1386.   <li><a href="#filter">Filter</a></li>

  1387.   <li><a href="#fixcrlf">FixCRLF</a></li>

  1388.   <li><a href="#genkey">GenKey</a></li>

  1389.   <li><a href="#get">Get</a></li>

  1390.   <li><a href="#gunzip">GUnzip</a></li>

  1391.   <li><a href="#gzip">GZip</a></li>

  1392.   <li><a href="#jar">Jar</a></li>

  1393.   <li><a href="#java">Java</a></li>

  1394.   <li><a href="#javac">Javac</a></li>

  1395.   <li><a href="#javadoc">Javadoc/Javadoc2</a></li>

  1396.   <li><a href="#mail">Mail</a></li>

  1397.   <li><a href="#mkdir">Mkdir</a></li>

  1398.   <li><a href="#move">Move</a></li>

  1399.   <li><a href="#patch">Patch</a></li>

  1400.   <li><a href="#property">Property</a></li>

  1401.   <li><a href="#rename">Rename</a></li>

  1402.   <li><a href="#replace">Replace</a></li>

  1403.   <li><a href="#rmic">Rmic</a></li>

  1404.   <li><a href="#signjar">SignJar</a></li>

  1405.   <li><a href="sql.html">Sql</a></li>

  1406.   <li><a href="#style">Style</a></li>

  1407.   <li><a href="#tar">Tar</a></li>

  1408.   <li><a href="#taskdef">Taskdef</a></li>

  1409.   <li><a href="#touch">Touch</a></li>

  1410.   <li><a href="#transform">Transform</a></li>

  1411.   <li><a href="#tstamp">Tstamp</a></li>

  1412.   <li><a href="#unzip">Unjar</a></li>

  1413.   <li><a href="#untar">Untar</a></li>

  1414.   <li><a href="#unzip">Unwar</a></li>

  1415.   <li><a href="#unzip">Unzip</a></li>

  1416.   <li><a href="#uptodate">Uptodate</a></li>

  1417.   <li><a href="#war">War</a></li>

  1418.   <li><a href="#zip">Zip</a></li>

  1419. </ul>

  1420. <hr>

  1421. <h2><a name="ant">Ant</a></h2>

  1422. <h3>Description</h3>

  1423. <p>Runs Ant on a supplied buildfile. This can be used to build subprojects.</p>

  1424. <p>When the <i>antfile</i> attribute is omitted, the file &quot;build.xml&quot;

  1425. in the supplied directory (<i>dir</i> attribute) is used.</p>

  1426. <p>If no target attribute is supplied, the default target of the new project is

  1427. used.</p>

  1428. <p>The properties of the current project will be available in the new project.

  1429. These properties will override the properties that are set in the new project.

  1430. (See also the <a href="#property">properties task</a>). You can set properties

  1431. in the new project from the old project by using nested property tags. This

  1432. allows you to parameterize your subprojects.</p>

  1433. <h3>Parameters</h3>

  1434. <table border="1" cellpadding="2" cellspacing="0">

  1435.   <tr>

  1436.     <td valign="top"><b>Attribute</b></td>

  1437.     <td valign="top"><b>Description</b></td>

  1438.     <td align="center" valign="top"><b>Required</b></td>

  1439.   </tr>

  1440.   <tr>

  1441.     <td valign="top">antfile</td>

  1442.     <td valign="top">the buildfile to use. Defaults to &quot;build.xml&quot;.</td>

  1443.     <td valign="top" align="center">No</td>

  1444.   </tr>

  1445.   <tr>

  1446.     <td valign="top">dir</td>

  1447.  	<td valign="top">the directory to use as a basedir for the new Ant project. 

  1448. 					 Defaults to the current directory.</td>

  1449.     <td valign="top" align="center">No</td>

  1450.   </tr>

  1451.   <tr>

  1452.     <td valign="top">target</td>

  1453.     <td valign="top">the target of the new Ant project that should be executed.</td>

  1454.     <td valign="top" align="center">No</td>

  1455.   </tr>

  1456.   <tr>

  1457.     <td valign="top">output</td>

  1458.     <td valign="top">Filename to write the ant output to.

  1459.     </td>

  1460.     <td align="center" valign="top">No</td>

  1461.   </tr>

  1462. </table>

  1463. <h3>Examples</h3>

  1464. <pre>

  1465.   &lt;ant antfile=&quot;subproject/subbuild.xml&quot; dir=&quot;subproject&quot; target=&quot;compile&quot;/&gt;

  1466. 

  1467.   &lt;ant dir=&quot;subproject&quot;/&gt;

  1468. 

  1469.   &lt;ant antfile=&quot;subproject/property_based_subbuild.xml&quot;&gt;

  1470.     &lt;property name=&quot;param1&quot; value=&quot;version 1.x&quot;/&gt;

  1471.     &lt;property file=&quot;config/subproject/default.properties&quot;/&gt;

  1472.   &lt;/ant&gt;

  1473. </pre>

  1474. <hr>

  1475. <h2><a name="antcall">AntCall</a></h2>

  1476. <h3>Description</h3>

  1477. <p>Call another target within the same build-file optionally specifying some

  1478. properties (param's in this context)</p>

  1479. <h3>Parameters</h3>

  1480. <table border="1" cellpadding="2" cellspacing="0">

  1481.   <tr>

  1482.     <td valign="top"><b>Attribute</b></td>

  1483.     <td valign="top"><b>Description</b></td>

  1484.     <td align="center" valign="top"><b>Required</b></td>

  1485.   </tr>

  1486.   <tr>

  1487.     <td valign="top">target</td>

  1488.     <td valign="top">The target to execute.</td>

  1489.     <td valign="top" align="center">Yes</td>

  1490.   </tr>

  1491. </table>

  1492. <h3>Parameters specified as nested elements</h3>

  1493. <h4>param</h4>

  1494. <p>Specifies the properties to set before running the specified target. See <a

  1495. href="#property">property</a> for usage guidelines.</p>

  1496. <h3>Examples</h3>

  1497. <pre>

  1498.   &lt;target name=&quot;default&quot;&gt;

  1499.     &lt;antcall target=&quot;doSomethingElse&quot;&gt;

  1500.       &lt;param name=&quot;param1&quot; value=&quot;value&quot;/&gt;

  1501.     &lt;/antcall&gt;

  1502.   &lt;/target&gt;

  1503. 

  1504.   &lt;target name=&quot;doSomethingElse&quot;&gt;

  1505.     &lt;echo message=&quot;param1=${param1}&quot;/&gt;

  1506.   &lt;/target&gt;

  1507. </pre>

  1508. <p>Will run the target 'doSomethingElse' and echo 'param1=value'.</p>

  1509. <hr>

  1510. <h2><a name="antstructure">AntStructure</a></h2>

  1511. <h3>Description</h3> 

  1512. <p>Generates a DTD for Ant buildfiles which contains information

  1513. about all tasks currently known to Ant.</p> 

  1514. <p>Note that the DTD generated by this task is incomplete, you can

  1515. always add XML entities using <a

  1516. href="#taskdef"><code>&lt;taskdef&gt;</code></a>. See <a

  1517. href="http://www.sdv.fr/pages/casa/html/ant-dtd.en.html">here</a> for

  1518. a way to get around this problem.</p>

  1519. <p>This task doesn't know about required attributes, all will be

  1520. listed as <code>#IMPLIED</code>.</p>

  1521. <h3>Parameters</h3>

  1522. <table border="1" cellpadding="2" cellspacing="0">

  1523.   <tr>

  1524.     <td valign="top"><b>Attribute</b></td>

  1525.     <td valign="top"><b>Description</b></td>

  1526.     <td align="center" valign="top"><b>Required</b></td>

  1527.   </tr>

  1528.   <tr>

  1529.     <td valign="top">output</td>

  1530.     <td valign="top">file to write the DTD to.</td>

  1531.     <td valign="top" align="center">Yes</td>

  1532.   </tr>

  1533. </table>

  1534. <h3>Examples</h3>

  1535. <blockquote><pre>

  1536. &lt;antstructure output=&quot;project.dtd&quot;/&gt;

  1537. </pre></blockquote>

  1538. <hr>

  1539. <h2><a name="available">Available</a></h2>

  1540. <h3>Description</h3>

  1541. <p>Sets a property if a resource is available at runtime. This resource can be a

  1542. file resource, a class in classpath or a JVM system resource.</p>

  1543. <p>If the resource is present, the property value is set to true by

  1544. default, otherwise the property is not set. You can set the value to

  1545. something specific by using the value attribute.</p>

  1546. <p>Normally, this task is used to set properties that are useful to avoid target

  1547. execution depending on system parameters.</p>

  1548. <h3>Parameters</h3>

  1549. <table border="1" cellpadding="2" cellspacing="0">

  1550.   <tr>

  1551.     <td valign="top"><b>Attribute</b></td>

  1552.     <td valign="top"><b>Description</b></td>

  1553.     <td align="center" valign="top"><b>Required</b></td>

  1554.   </tr>

  1555.   <tr>

  1556.     <td valign="top">property</td>

  1557.     <td valign="top">the name of the property to set.</td>

  1558.     <td valign="top" align="center">Yes</td>

  1559.   </tr>

  1560.   <tr>

  1561.     <td valign="top">value</td>

  1562.     <td valign="top">the value to set the property to. Defaults to &quot;true&quot;.</td>

  1563.     <td valign="top" align="center">No</td>

  1564.   </tr>

  1565.   <tr>

  1566.     <td valign="top">classname</td>

  1567.     <td valign="top">the class to look for in classpath.</td>

  1568.     <td valign="middle" align="center" rowspan="3">Yes</td>

  1569.   </tr>

  1570.   <tr>

  1571.     <td valign="top">resource</td>

  1572.     <td valign="top">the resource to look for in the JVM</td>

  1573.   </tr>

  1574.   <tr>

  1575.     <td valign="top">file</td>

  1576.     <td valign="top">the file to look for.</td>

  1577.   </tr>

  1578.   <tr>

  1579.     <td valign="top">classpath</td> <td valign="top">the classpath to

  1580.       use when looking up <code>classname</code>.</td> <td

  1581.     align="center" valign="top">No</td>

  1582.   </tr>

  1583. </table>

  1584. <h3>Parameters specified as nested elements</h3>

  1585. <h4>classpath</h4>

  1586. <p><code>Available</code>'s <i>classpath</i> attribute is a <a

  1587. href="#path">path-like structure</a> and can also be set via a nested

  1588. <i>classpath</i> element.</p>

  1589. <h3>Examples</h3>

  1590. <pre>  &lt;available classname=&quot;org.whatever.Myclass&quot; property=&quot;Myclass.present&quot;/&gt;</pre>

  1591. <p>sets the property <code><i>Myclass.present</i></code> to the value &quot;true&quot;

  1592. if the <i>org.whatever.Myclass</i> is found in Ant's classpath.</p>

  1593. <hr>

  1594. <h2><a name="chmod">Chmod</a></h2>

  1595. <h3>Description</h3>

  1596. <p>Changes the permissions of a file or all files inside specified directories. Right now it has effect only under Unix.

  1597. The permissions are also UNIX style, like the argument for the chmod command.</p>

  1598. <p>See the section on <a href="#directorybasedtasks">directory based

  1599. tasks</a>, on how the inclusion/exclusion of files works, and how to

  1600. write patterns.</p>

  1601. <p>This task holds an implicit <a href="#fileset">FileSet</a> and

  1602. supports all of FileSet's attributes and nested elements

  1603. directly. More FileSets can be specified using nested

  1604. <code>&lt;fileset&gt;</code> elements.</p>

  1605. <h3>Parameters</h3>

  1606. <table border="1" cellpadding="2" cellspacing="0">

  1607.   <tr>

  1608.     <td valign="top"><b>Attribute</b></td>

  1609.     <td valign="top"><b>Description</b></td>

  1610.     <td align="center" valign="top"><b>Required</b></td>

  1611.   </tr>

  1612.   <tr>

  1613.     <td valign="top">file</td>

  1614.     <td valign="top">the file or single directory of which the permissions 

  1615.       must be changed.</td>

  1616.     <td valign="top" valign="middle" rowspan="2">exactly one of the two or nested <code>&lt;fileset&gt;</code> elements.</td>

  1617.   </tr>

  1618.   <tr>

  1619.     <td valign="top">dir</td>

  1620.     <td valign="top">the directory which holds the files whose permissions 

  1621.       must be changed.</td>

  1622.   </tr>

  1623.   <tr>

  1624.     <td valign="top">perm</td>

  1625.     <td valign="top">the new permissions.</td>

  1626.     <td valign="top" align="center">Yes</td>

  1627.   </tr>

  1628.   <tr>

  1629.     <td valign="top">includes</td>

  1630.     <td valign="top">comma separated list of patterns of files that must be

  1631.       included. All files are included when omitted.</td>

  1632.     <td valign="top" align="center">No</td>

  1633.   </tr>

  1634.   <tr>

  1635.     <td valign="top">includesfile</td>

  1636.     <td valign="top">the name of a file. Each line of this file is

  1637.       taken to be an include pattern</td>

  1638.     <td valign="top" align="center">No</td>

  1639.   </tr>

  1640.   <tr>

  1641.     <td valign="top">excludes</td>

  1642.     <td valign="top">comma separated list of patterns of files that must be

  1643.       excluded. No files (except default excludes) are excluded when omitted.</td>

  1644.     <td valign="top" align="center">No</td>

  1645.   </tr>

  1646.   <tr>

  1647.     <td valign="top">excludesfile</td>

  1648.     <td valign="top">the name of a file. Each line of this file is

  1649.       taken to be an exclude pattern</td>

  1650.     <td valign="top" align="center">No</td>

  1651.   </tr>

  1652.   <tr>

  1653.     <td valign="top">defaultexcludes</td>

  1654.     <td valign="top">indicates whether default excludes should be used or not

  1655.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  1656.     <td valign="top" align="center">No</td>

  1657.   </tr>

  1658.   <tr>

  1659.     <td valign="top">parallel</td>

  1660.     <td valign="top">process all specified files using a single

  1661.       <code>chmod</code> command. Defaults to true.</td>

  1662.     <td valign="top" align="center">No</td>

  1663.   </tr>

  1664.   <tr>

  1665.     <td valign="top">type</td>

  1666.     <td valign="top">One of <i>file</i>, <i>dir</i> or

  1667.       <i>both</i>. If set to <i>file</i>, only the permissions of

  1668.       plain files are going to be changed. If set to <i>dir</i>, only

  1669.       the directories are considered.</td>

  1670.     <td align="center" valign="top">No, default is <i>file</i></td>

  1671.   </tr>

  1672. </table>

  1673. <h3>Examples</h3>

  1674. <blockquote>

  1675.   <p><code>&lt;chmod file=&quot;${dist}/start.sh&quot; perm=&quot;ugo+rx&quot;

  1676.   /&gt;</code></p>

  1677. </blockquote>

  1678. <p>makes the &quot;start.sh&quot; file readable and executable for anyone on a

  1679. UNIX system.</p>

  1680. <blockquote>

  1681. <pre>

  1682.     &lt;chmod dir=&quot;${dist}/bin&quot; perm=&quot;ugo+rx&quot; includes=&quot;**/*.sh&quot;/&gt;

  1683. </pre>

  1684. </blockquote>

  1685. <p>makes all &quot;.sh&quot; files below <code>${dist}/bin</code>

  1686. readable and executable for anyone on a UNIX system.</p>

  1687. <blockquote>

  1688. <pre>

  1689. &lt;chmod perm=&quot;g+w&quot;/&gt;

  1690.   &lt;fileset dir=&quot;shared/sources1&quot; &gt;

  1691.     &lt;exclude name=&quot;**/trial/**&quot;/&gt;

  1692.   &lt;/fileset&gt;

  1693.   &lt;fileset refid=&quot;other.shared.sources&quot;/&gt;

  1694. &lt;/chmod&gt;

  1695. </pre>

  1696. </blockquote>

  1697. <p>makes all files below <code>shared/sources1</code> (except those

  1698. below any directory named trial) writable for members of the same

  1699. group on a UNIX system. In addition all files belonging to a FileSet

  1700. with <code>id</code> <code>other.shared.sources</code> get the same

  1701. permissions.</p>

  1702. <hr>

  1703. <h2><a name="copy">Copy</a></h2>

  1704. <h3>Description</h3>

  1705. <p>Copies a file or Fileset to a new file or directory.  Files are

  1706. only copied if the source file is newer than the destination file,

  1707. or when the destination file does not exist.  However, you can explicitly 

  1708. overwrite files with the <var>overwrite</var> attribute.</p>

  1709. <p><a href="#fileset">FileSet</a>s are used to select files to copy.  

  1710. To use a fileset, the <var>todir</var> attribute must be set.</p>

  1711. <h3>Parameters</h3>

  1712. <table border="1" cellpadding="2" cellspacing="0">

  1713.   <tr>

  1714.     <td valign="top"><b>Attribute</b></td>

  1715.     <td valign="top"><b>Description</b></td>

  1716.     <td align="center" valign="top"><b>Required</b></td>

  1717.   </tr>

  1718.   <tr>

  1719.     <td valign="top">file</td>

  1720.     <td valign="top">The file to copy.</td>

  1721.     <td valign="top" align="center">One of either <var>file</var> or 

  1722.     at least one nested fileset element.</td>

  1723.   </tr>

  1724.   <tr>

  1725.     <td valign="top">preservelastmodified</td>

  1726.     <td valign="top">Give the copied files the same last modified

  1727.       time as the original files. Defaults to &quot;no&quot;.</td>

  1728.     <td valign="top" align="center">No</td>

  1729.   </tr>

  1730.   <tr>

  1731.     <td valign="top">tofile</td>

  1732.     <td valign="top">The file to copy to.</td>

  1733.     <td valign="top" align="center" rowspan="2">With the <var>file</var> attribute, 

  1734.     either <var>tofile</var> or <var>todir</var> can be used.  With nested filesets, 

  1735.     only <var>todir</var> is allowed.</td>

  1736.   </tr>

  1737.   <tr>

  1738.     <td valign="top">todir</td>

  1739.     <td valign="top">The directory to copy to.</td>

  1740.   </tr>

  1741.   <tr>

  1742.     <td valign="top">overwrite</td>

  1743.     <td valign="top">Overwrite existing files even if the destination

  1744.       files are newer. Defaults to &quot;no&quot;.</td>

  1745.     <td valign="top" align="center">No</td>

  1746.   </tr>

  1747.   <tr>

  1748.     <td valign="top">filtering</td>

  1749.     <td valign="top">Indicates whether token filtering should take place during

  1750.       the copy. Defaults to &quot;no&quot;.</td>

  1751.     <td valign="top" align="center">No</td>

  1752.   </tr>

  1753.   <tr>

  1754.     <td valign="top">flatten</td>

  1755.     <td valign="top">Ignore directory structure of source directory,

  1756.       copy all files into a single directory, specified by the <var>todir</var>

  1757.       attribute. Defaults to &quot;no&quot;. Note that you can achieve the 

  1758.       same effect by using a <a href="#flatten-mapper">flatten mapper</a></td>

  1759.     <td valign="top" align="center">No</td>

  1760.   </tr>

  1761.   <tr>

  1762.     <td valign="top">includeEmptyDirs</td>

  1763. 	 <td valign="top">Copy empty directories included with the nested FileSet(s).

  1764. 	   Defaults to &quot;yes&quot;.</td>

  1765. 	 <td valign="top" align="center">No</td>

  1766.   </tr>

  1767. </table>

  1768. <h3>Parameters specified as nested elements</h3>

  1769. <h4>mapper</h4>

  1770. <p>You can define file name transformations by using a nested <a

  1771. href="#mapper">mapper</a> element. The default mapper used by

  1772. <code>&lt;copy&gt;</code> is the <a

  1773. href="#identity-mapper">identity</a>.</p>

  1774. <h3>Examples</h3>

  1775. <p><b>Copy a single file</b></p>

  1776. <pre>

  1777.   &lt;copy file=&quot;myfile.txt&quot; tofile=&quot;mycopy.txt&quot;/&gt;

  1778. </pre>

  1779. <p><b>Copy a file to a directory</b></p>

  1780. <pre>

  1781.   &lt;copy file=&quot;myfile.txt&quot; todir=&quot;../some/dir/tree&quot;/&gt;

  1782. </pre>

  1783. <p><b>Copy a directory to another directory</b></p>

  1784. <pre>

  1785.   &lt;copy todir=&quot;../new/dir&quot;&gt;

  1786.     &lt;fileset dir=&quot;src_dir&quot;/&gt;

  1787.   &lt;/copy&gt;

  1788. </pre>

  1789. <p><b>Copy a set of files to a directory</b></p>

  1790. <pre>

  1791.   &lt;copy todir=&quot;../dest/dir&quot; &gt;

  1792.     &lt;fileset dir=&quot;src_dir&quot &gt;

  1793.       &lt;exclude name=&quot;**/*.java&quot;/&gt;

  1794.     &lt;/fileset&gt;

  1795.   &lt;/copy&gt;

  1796. 

  1797.   &lt;copy todir=&quot;../dest/dir&quot; &gt;

  1798.     &lt;fileset dir=&quot;src_dir&quot excludes=&quot;**/*.java&quot;/&gt;

  1799.   &lt;/copy&gt;

  1800. </pre>

  1801. <p><b>Copy a set of files to a directory appending

  1802. &quot;<code>.bak</code>&quot; to the file name on the fly</b></p>

  1803. <pre>

  1804.   &lt;copy todir=&quot;../backup/dir&quot; &gt;

  1805.     &lt;fileset dir=&quot;src_dir&quot /&gt;

  1806.     &lt;mapper type=&quot;glob&quot; from=&quot;*&quot; to=&quot;*.bak&quot;/&gt;

  1807.   &lt;/copy&gt;

  1808. </pre>

  1809. <hr>

  1810. <h2><a name="copydir">Copydir</a></h2>

  1811. <h3><i>Deprecated</i></h3>

  1812. <p><i>This task has been deprecated.  Use the Copy task instead.</i></p>

  1813. <h3>Description</h3>

  1814. <p>Copies a directory tree from the source to the destination.</p>

  1815. <p>It is possible to refine the set of files that are being copied. This can be

  1816. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  1817. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  1818. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  1819. the files you want to have excluded. This is also done with patterns. And

  1820. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  1821. want to use default exclusions or not. See the section on <a

  1822. href="#directorybasedtasks">directory based tasks</a>, on how the

  1823. inclusion/exclusion of files works, and how to write patterns.</p>

  1824. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  1825. supports all attributes of <code>&lt;fileset&gt;</code>

  1826. (<code>dir</code> becomes <code>src</code>) as well as the nested

  1827. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  1828. <code>&lt;patternset&gt;</code> elements.</p>

  1829. <h3>Parameters</h3>

  1830. <table border="1" cellpadding="2" cellspacing="0">

  1831.   <tr>

  1832.     <td valign="top"><b>Attribute</b></td>

  1833.     <td valign="top"><b>Description</b></td>

  1834.     <td align="center" valign="top"><b>Required</b></td>

  1835.   </tr>

  1836.   <tr>

  1837.     <td valign="top">src</td>

  1838.     <td valign="top">the directory to copy.</td>

  1839.     <td valign="top" align="center">Yes</td>

  1840.   </tr>

  1841.   <tr>

  1842.     <td valign="top">dest</td>

  1843.     <td valign="top">the directory to copy to.</td>

  1844.     <td valign="top" align="center">Yes</td>

  1845.   </tr>

  1846.   <tr>

  1847.     <td valign="top">includes</td>

  1848.     <td valign="top">comma separated list of patterns of files that must be

  1849.       included. All files are included when omitted.</td>

  1850.     <td valign="top" align="center">No</td>

  1851.   </tr>

  1852.   <tr>

  1853.     <td valign="top">includesfile</td>

  1854.     <td valign="top">the name of a file. Each line of this file is

  1855.       taken to be an include pattern</td>

  1856.     <td valign="top" align="center">No</td>

  1857.   </tr>

  1858.   <tr>

  1859.     <td valign="top">excludes</td>

  1860.     <td valign="top">comma separated list of patterns of files that must be

  1861.       excluded. No files (except default excludes) are excluded when omitted.</td>

  1862.     <td valign="top" align="center">No</td>

  1863.   </tr>

  1864.   <tr>

  1865.     <td valign="top">excludesfile</td>

  1866.     <td valign="top">the name of a file. Each line of this file is

  1867.       taken to be an exclude pattern</td>

  1868.     <td valign="top" align="center">No</td>

  1869.   </tr>

  1870.   <tr>

  1871.     <td valign="top">defaultexcludes</td>

  1872.     <td valign="top">indicates whether default excludes should be used or not

  1873.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  1874.     <td valign="top" align="center">No</td>

  1875.   </tr>

  1876.   <tr>

  1877.     <td valign="top">filtering</td>

  1878.     <td valign="top">indicates whether token filtering should take place during

  1879.       the copy</td>

  1880.     <td valign="top" align="center">No</td>

  1881.   </tr>

  1882.   <tr>

  1883.     <td valign="top">flatten</td>

  1884.     <td valign="top">ignore directory structure of source directory,

  1885.       copy all files into a single directory, specified by the <code>dest</code>

  1886.       attribute (default is <code>false</code>).</td>

  1887.     <td valign="top" align="center">No</td>

  1888.   </tr>

  1889.   <tr>

  1890.     <td valign="top">forceoverwrite</td>

  1891.     <td valign="top">overwrite existing files even if the destination

  1892.       files are newer (default is false).</td>

  1893.     <td valign="top" align="center">No</td>

  1894.   </tr>

  1895. </table>

  1896. <h3>Examples</h3>

  1897. <pre>  &lt;copydir src=&quot;${src}/resources&quot;

  1898.            dest=&quot;${dist}&quot;

  1899.   /&gt;</pre>

  1900. <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>.</p>

  1901. <pre>  &lt;copydir src=&quot;${src}/resources&quot;

  1902.            dest=&quot;${dist}&quot;

  1903.            includes=&quot;**/*.java&quot;

  1904.            excludes=&quot;**/Test.java&quot;

  1905.   /&gt;</pre>

  1906. <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>

  1907. recursively. All java files are copied, except for files with the name <code>Test.java</code>.</p>

  1908. <pre>  &lt;copydir src=&quot;${src}/resources&quot;

  1909.            dest=&quot;${dist}&quot;

  1910.            includes=&quot;**/*.java&quot;

  1911.            excludes=&quot;mypackage/test/**&quot;/&gt;</pre>

  1912. <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>

  1913. recursively. All java files are copied, except for the files under the <code>mypackage/test</code>

  1914. directory.</p>

  1915. <hr>

  1916. <h2><a name="copyfile">Copyfile</a></h2>

  1917. <h3><i>Deprecated</i></h3>

  1918. <p><i>This task has been deprecated.  Use the Copy task instead.</i></p>

  1919. <h3>Description</h3>

  1920. <p>Copies a file from the source to the destination. The file is only copied if

  1921. the source file is newer than the destination file, or when the destination file

  1922. does not exist.</p>

  1923. <h3>Parameters</h3>

  1924. <table border="1" cellpadding="2" cellspacing="0">

  1925.   <tr>

  1926.     <td valign="top"><b>Attribute</b></td>

  1927.     <td valign="top"><b>Description</b></td>

  1928.     <td align="center" valign="top"><b>Required</b></td>

  1929.   </tr>

  1930.   <tr>

  1931.     <td valign="top">src</td>

  1932.     <td valign="top">the filename of the file to copy.</td>

  1933.     <td valign="top" align="center">Yes</td>

  1934.   </tr>

  1935.   <tr>

  1936.     <td valign="top">dest</td>

  1937.     <td valign="top">the filename of the file where to copy to.</td>

  1938.     <td valign="top" align="center">Yes</td>

  1939.   </tr>

  1940.   <tr>

  1941.     <td valign="top">filtering</td>

  1942.     <td valign="top">indicates whether token filtering should take place during

  1943.       the copy</td>

  1944.     <td valign="top" align="center">No</td>

  1945.   </tr>

  1946.   <tr>

  1947.     <td valign="top">forceoverwrite</td>

  1948.     <td valign="top">overwrite existing files even if the destination

  1949.       files are newer (default is false).</td>

  1950.     <td valign="top" align="center">No</td>

  1951.   </tr>

  1952. </table>

  1953. <h3>Examples</h3>

  1954. <blockquote>

  1955.   <p><code>&lt;copyfile src=&quot;test.java&quot; dest=&quot;subdir/test.java&quot;

  1956.   /&gt;</code></p>

  1957.   <p><code>&lt;copyfile src=&quot;${src}/index.html&quot; dest=&quot;${dist}/help/index.html&quot;

  1958.   /&gt;</code></p>

  1959. </blockquote>

  1960. <hr>

  1961. <h2><a name="cvs">Cvs</a></h2>

  1962. <h3>Description</h3>

  1963. <p>Handles packages/modules retrieved from a 

  1964. <a href="http://www.cvshome.org/">CVS</a> repository.</p>

  1965. <p>When doing automated builds, the <a href="#get">get task</a> should be

  1966. preferred over the <i>checkout</i> command, because of speed.</p>

  1967. <h3>Parameters</h3>

  1968. <table border="1" cellpadding="2" cellspacing="0">

  1969.   <tr>

  1970.     <td valign="top"><b>Attribute</b></td>

  1971.     <td valign="top"><b>Description</b></td>

  1972.     <td align="center" valign="top"><b>Required</b></td>

  1973.   </tr>

  1974.   <tr>

  1975.     <td valign="top">command</td>

  1976.     <td valign="top">the CVS command to execute.</td>

  1977.     <td align="center" valign="top">No, default &quot;checkout&quot;</td>

  1978.   </tr>

  1979.   <tr>

  1980.     <td valign="top">cvsRoot</td>

  1981.     <td valign="top">the CVSROOT variable.</td>

  1982.     <td align="center" valign="top">No</td>

  1983.   </tr>

  1984.   <tr>

  1985.     <td valign="top">dest</td>

  1986.     <td valign="top">the directory where the checked out files should be placed.</td>

  1987.     <td align="center" valign="top">No, default is project's basedir.</td>

  1988.   </tr>

  1989.   <tr>

  1990.     <td valign="top">package</td>

  1991.     <td valign="top">the package/module to check out.</td>

  1992.     <td align="center" valign="top">No</td>

  1993.   </tr>

  1994.   <tr>

  1995.     <td valign="top">tag</td>

  1996.     <td valign="top">the tag of the package/module to check out.</td>

  1997.     <td align="center" valign="top">No</td>

  1998.   </tr>

  1999.   <tr>

  2000.     <td valign="top">date</td>

  2001.     <td valign="top">Use the most recent revision no later than the given date</td>

  2002.     <td align="center" valign="top">No</td>

  2003.   </tr>

  2004.   <tr>

  2005.     <td valign="top">quiet</td>

  2006.     <td valign="top">suppress informational messages.</td>

  2007.     <td align="center" valign="top">No, default &quot;false&quot;</td>

  2008.   </tr>

  2009.   <tr>

  2010.     <td valign="top">noexec</td>

  2011.     <td valign="top">report only, don't change any files.</td>

  2012.     <td align="center" valign="top">No, default &quot;false&quot;</td>

  2013.   </tr>

  2014.   <tr>

  2015.     <td valign="top">output</td>

  2016.     <td valign="top">the file to direct standard output from the command.</td>

  2017.     <td align="center" valign="top">No, default output to ANT Log as MSG_INFO.</td>

  2018.   </tr>

  2019.   <tr>

  2020.     <td valign="top">error</td>

  2021.     <td valign="top">the file to direct standard error from the command.</td>

  2022.     <td align="center" valign="top">No, default error to ANT Log as MSG_WARN.</td>

  2023.   </tr>

  2024. </table>

  2025. <h3>Examples</h3>

  2026. <pre>  &lt;cvs cvsRoot=&quot;:pserver:anoncvs@jakarta.apache.org:/home/cvspublic&quot;

  2027.        package=&quot;jakarta-tools&quot;

  2028.        dest=&quot;${ws.dir}&quot;

  2029.   /&gt;</pre>

  2030. <p>checks out the package/module &quot;jakarta-tools&quot; from the CVS

  2031. repository pointed to by the cvsRoot attribute, and stores the files in &quot;${ws.dir}&quot;.</p>

  2032. <pre>  &lt;cvs dest=&quot;${ws.dir}&quot; command=&quot;update&quot;/&gt;</pre>

  2033. <p>updates the package/module that has previously been checked out into

  2034. &quot;${ws.dir}&quot;.</p>

  2035. <pre>  &lt;cvs command=&quot;-q diff -u -N&quot; output="patch.txt"/&gt;</pre>

  2036. <p>silently (-q) creates a file called patch.txt which contains a unified (-u) diff which includes new files added via &quot;cvs add&quot; (-N) and can be used as input to patch.</p>

  2037. <pre>  &lt;cvs command=&quot;update -A -d&quot;/&gt;</pre>

  2038. <p>Updates from the head of repository ignoring sticky bits (-A) and creating any new directories as necessary (-d).</p>

  2039. <p>Note: the text of the command is passed to cvs &quot;as-is&quot; 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>

  2040. <hr>

  2041. <h2><a name="delete">Delete</a></h2>

  2042. <h3>Description</h3>

  2043. <p>Deletes either a single file, all files in a specified directory and its 

  2044. sub-directories, or a set of files specified by one or more <a href="#fileset">FileSet</a>s.

  2045. When specifying a set of files, empty directories are <i>not</i> removed.</p>

  2046. <h3>Parameters</h3>

  2047. <table border="1" cellpadding="2" cellspacing="0">

  2048.   <tr>

  2049.     <td valign="top"><b>Attribute</b></td>

  2050.     <td valign="top"><b>Description</b></td>

  2051.     <td align="center" valign="top"><b>Required</b></td>

  2052.   </tr>

  2053.   <tr>

  2054.     <td valign="top">file</td>

  2055.     <td valign="top">The file to delete.</td>

  2056.     <td align="center" valign="middle" rowspan="2">at least one of the two</td>

  2057.   </tr>

  2058.   <tr>

  2059.     <td valign="top">dir</td>

  2060.     <td valign="top">The directory to delete files from.</td>

  2061.   </tr>

  2062.   <tr>

  2063.     <td valign="top">verbose</td>

  2064.     <td valign="top">Show name of each deleted file (&quot;true&quot;/&quot;false&quot;).

  2065. 	 Default is &quot;false&quot; when omitted.</td>

  2066.     <td align="center" valign="top">No</td>

  2067.   </tr>

  2068.   <tr>

  2069.     <td valign="top">quiet</td>

  2070.     <td valign="top">If the file does not exist, do not display a diagnostic 

  2071.      message or modify the exit status to reflect an error.

  2072.      This means that if a file or directory cannot be deleted,

  2073.      then no error is reported. This setting emulates the 

  2074.      -f option to the Unix &quot;rm&quot; command.

  2075.     (&quot;true&quot;/&quot;false&quot;).

  2076. 	 Default is &quot;false&quot; meaning things are &quot;noisy&quot;.</td>

  2077.     <td align="center" valign="top">No</td>

  2078.   </tr>

  2079.   <tr>

  2080.     <td valign="top">includes</td>

  2081.     <td valign="top"><i>Deprecated.</i>  Comma separated list of patterns of files that must be

  2082.       deleted. All files are in the current directory 

  2083.       and any sub-directories are deleted when omitted.</td>

  2084.     <td valign="top" align="center">No</td>

  2085.   </tr>

  2086.   <tr>

  2087.     <td valign="top">includesfile</td>

  2088.     <td valign="top"><i>Deprecated.</i>  The name of a file. Each line of this file is

  2089.       taken to be an include pattern</td>

  2090.     <td valign="top" align="center">No</td>

  2091.   </tr>

  2092.   <tr>

  2093.     <td valign="top">excludes</td>

  2094.     <td valign="top"><i>Deprecated.</i>  Comma separated list of patterns of files that must be

  2095.       excluded from the deletion list. No files (except default excludes) are excluded when omitted.</td>

  2096.     <td valign="top" align="center">No</td>

  2097.   </tr>

  2098.   <tr>

  2099.     <td valign="top">excludesfile</td>

  2100.     <td valign="top"><i>Deprecated.</i>  The name of a file. Each line of this file is

  2101.       taken to be an exclude pattern</td>

  2102.     <td valign="top" align="center">No</td>

  2103.   </tr>

  2104.   <tr>

  2105.     <td valign="top">defaultexcludes</td>

  2106.     <td valign="top"><i>Deprecated.</i>  Indicates whether default excludes should be used or not

  2107.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  2108.     <td valign="top" align="center">No</td>

  2109.   </tr>

  2110. </table>

  2111. <h3>Examples</h3>

  2112. <pre>  &lt;delete file=&quot;/lib/ant.jar&quot;/&gt;</pre>

  2113. <p>deletes the file <code>/lib/ant.jar</code>.</p>

  2114. <pre>  &lt;delete dir=&quot;lib&quot;/&gt;</pre>

  2115. <p>deletes all files in the <code>/lib</code> directory.</p>

  2116. <pre>  &lt;delete&gt;

  2117.     &lt;fileset dir=&quot;.&quot; includes=&quot;**/*.bak&quot;/&gt;

  2118.   &lt;/delete&gt;

  2119. </pre>

  2120. <p>deletes all files with the extension &quot;<code>.bak</code>&quot from the current directory 

  2121. and any sub-directories.</p>

  2122. <hr>

  2123. <h2><a name="deltree">Deltree</a></h2>

  2124. <h3><i>Deprecated</i></h3>

  2125. <p><i>This task has been deprecated.  Use the Delete task instead.</i></p>

  2126. <h3>Description</h3>

  2127. <p>Deletes a directory with all its files and subdirectories.</p>

  2128. <h3>Parameters</h3>

  2129. <table border="1" cellpadding="2" cellspacing="0">

  2130.   <tr>

  2131.     <td valign="top"><b>Attribute</b></td>

  2132.     <td valign="top"><b>Description</b></td>

  2133.     <td align="center" valign="top"><b>Required</b></td>

  2134.   </tr>

  2135.   <tr>

  2136.     <td valign="top">dir</td>

  2137.     <td valign="top">the directory to delete.</td>

  2138.     <td valign="top" align="center">Yes</td>

  2139.   </tr>

  2140. </table>

  2141. <h3>Examples</h3>

  2142. <pre>  &lt;deltree dir=&quot;dist&quot;/&gt;</pre>

  2143. <p>deletes the directory <code>dist</code>, including its files and

  2144. subdirectories.</p>

  2145. <pre>  &lt;deltree dir=&quot;${dist}&quot;/&gt;</pre>

  2146. <p>deletes the directory <code>${dist}</code>, including its files and

  2147. subdirectories.</p>

  2148. <hr>

  2149. <h2><a name="echo">Echo</a></h2>

  2150. <h3>Description</h3>

  2151. <p>Echoes a message to System.out or a file.</p>

  2152. <h3>Parameters</h3>

  2153. <table border="1" cellpadding="2" cellspacing="0">

  2154.   <tr>

  2155.     <td valign="top"><b>Attribute</b></td>

  2156.     <td valign="top"><b>Description</b></td>

  2157.     <td align="center" valign="top"><b>Required</b></td>

  2158.   </tr>

  2159.   <tr>

  2160.     <td valign="top">message</td>

  2161.     <td valign="top">the message to echo.</td>

  2162.     <td valign="top" align="center">Yes, unless data is included in a

  2163.       character section within this element.</td>

  2164.   </tr>

  2165.   <tr>

  2166.     <td valign="top">file</td>

  2167.     <td valign="top">the file to write the message to.</td>

  2168.     <td valign="top" align="center">No</td>

  2169.   </tr>

  2170.   <tr>

  2171.     <td valign="top">append</td>

  2172.     <td valign="top">Append to an existing file?</td>

  2173.     <td valign="top" align="center">No &#150; default is false.</td>

  2174.   </tr>

  2175. </table>

  2176. <h3>Examples</h3>

  2177. <pre>  &lt;echo message=&quot;Hello world&quot;/&gt;</pre>

  2178. <pre>  

  2179. &lt;echo&gt;

  2180. This is a longer message stretching over

  2181. two lines.

  2182. &lt;/echo&gt;

  2183. </pre>

  2184. <hr>

  2185. <h2><a name="exec">Exec</a></h2>

  2186. <h3>Description</h3>

  2187. <p>Executes a system command. When the <i>os</i> attribute is specified, then

  2188. the command is only executed when Ant is run on one of the specified operating

  2189. systems.</p>

  2190. <h3>Parameters</h3>

  2191. <table border="1" cellpadding="2" cellspacing="0">

  2192.   <tr>

  2193.     <td valign="top"><b>Attribute</b></td>

  2194.     <td valign="top"><b>Description</b></td>

  2195.     <td align="center" valign="top"><b>Required</b></td>

  2196.   </tr>

  2197.   <tr>

  2198.     <td valign="top">command</td>

  2199.     <td valign="top">the command to execute with all command line

  2200.       arguments. <b>deprecated, use executable and nested

  2201.       <code>&lt;arg&gt;</code> elements instead</b>.</td>

  2202.     <td align="center" rowspan="2">Exactly one of the two.</td>

  2203.   </tr>

  2204.   <tr>

  2205.     <td valign="top">executable</td>

  2206.     <td valign="top">the command to execute without any command line

  2207.       arguments.</td>

  2208.   </tr>

  2209.   <tr>

  2210.     <td valign="top">dir</td>

  2211.     <td valign="top">the directory in which the command should be executed.</td>

  2212.     <td align="center" valign="top">No</td>

  2213.   </tr>

  2214.   <tr>

  2215.     <td valign="top">os</td>

  2216.     <td valign="top">list of Operating Systems on which the command may be

  2217.       executed.</td>

  2218.     <td align="center" valign="top">No</td>

  2219.   </tr>

  2220.   <tr>

  2221.     <td valign="top">output</td>

  2222.     <td valign="top">the file to which the output of the command should be

  2223.       redirected.</td>

  2224.     <td align="center" valign="top">No</td>

  2225.   </tr>

  2226.   <tr>

  2227.     <td valign="top">timeout</td>

  2228.     <td valign="top">Stop the command if it doesn't finish within the

  2229.       specified time (given in milliseconds).</td>

  2230.     <td align="center" valign="top">No</td>

  2231.   </tr>

  2232.   <tr>

  2233.     <td valign="top">failonerror</td>

  2234.     <td valign="top">Stop the buildprocess if the command exits with a

  2235.       returncode other than 0.</td>

  2236.     <td align="center" valign="top">No</td>

  2237.   </tr>

  2238.   <tr>

  2239.     <td valign="top">newenvironment</td>

  2240.     <td valign="top">Do not propagate old environment when new environment

  2241.       variables are specified.</td>

  2242.     <td align="center" valign="top">No, default is <i>false</i></td>

  2243.   </tr>

  2244. </table>

  2245. <h3>Examples</h3>

  2246. <blockquote>

  2247.   <p><code>&lt;exec dir=&quot;${src}&quot; executable=&quot;dir&quot; os=&quot;windows&quot;

  2248.   output=&quot;dir.txt&quot;/&gt;</code></p>

  2249. </blockquote>

  2250. <h3>Parameters specified as nested elements</h3>

  2251. <h4>arg</h4>

  2252. <p>Command line arguments should be specified as nested

  2253. <code>&lt;arg&gt;</code> elements. See <a

  2254. href="index.html#arg">Command line arguments</a>.</p>

  2255. <h4><a name="env">env</a></h4>

  2256. <p>It is possible to specify environment variables to pass to the

  2257. system command via nested <code>&lt;env&gt;</code> elements.</p>

  2258. <p>Please note that the environment of the current Ant process is

  2259. <b>not</b> passed to the system command if you specify variables using

  2260. <code>&lt;env&gt;</code>.</p>

  2261. <table border="1" cellpadding="2" cellspacing="0">

  2262.   <tr>

  2263.     <td valign="top"><b>Attribute</b></td>

  2264.     <td valign="top"><b>Description</b></td>

  2265.     <td align="center" valign="top"><b>Required</b></td>

  2266.   </tr>

  2267.   <tr>

  2268.     <td valign="top">key</td>

  2269.     <td valign="top">The name of the environment variable.</td>

  2270.     <td align="center" valign="top">Yes</td>

  2271.   </tr>

  2272.   <tr>

  2273.     <td valign="top">value</td>

  2274.     <td valign="top">The literal value for the environment variable.</td>

  2275.     <td align="center" rowspan="3">Exactly one of these.</td>

  2276.   </tr>

  2277.   <tr>

  2278.     <td valign="top">path</td>

  2279.     <td valign="top">The value for a PATH like environment

  2280.       variable. You can use ; or : as path separators and Ant will

  2281.       convert it to the platform's local conventions.</td>

  2282.   </tr>

  2283.   <tr>

  2284.     <td valign="top">file</td>

  2285.     <td valign="top">The value for the environment variable. Will be

  2286.       replaced by the absolute filename of the file by Ant.</td>

  2287.   </tr>

  2288. </table>

  2289. <h5>Examples</h5>

  2290. <blockquote><pre>

  2291. &lt;exec executable=&quot;emacs&quot; &gt;

  2292.   &lt;env key=&quot;DISPLAY&quot; value=&quot;:1.0&quot;/&gt;

  2293. &lt;/exec&gt;

  2294. </pre></blockquote>

  2295. <p>starts <code>emacs</code> on display 1 of the X Window System.</p>

  2296. <blockquote><pre>

  2297. &lt;exec ... &gt;

  2298.   &lt;env key=&quot;PATH&quot; path=&quot;${java.library.path}:${basedir}/bin&quot;/&gt;

  2299. &lt;/exec&gt;

  2300. </pre></blockquote>

  2301. <p>adds <code>${basedir}/bin</code> to the <code>PATH</code> of the

  2302. system command.</p>

  2303. <p><b>Note:</b> Although it may work for you to specify arguments using 

  2304. a simple arg-element and seperate them by spaces it may fail if you switch to

  2305. a newer version of the JDK. JDK &lt; 1.2 will pass these as separate arguments

  2306. to the program you are calling, JDK &gt;= 1.2 will pass them as a single 

  2307. argument and cause most calls to fail.</p>

  2308. <p><b>Note2:</b> If you are using Ant on Windows and a new DOS-Window pops up

  2309. for every command which is excuted this may be a problem of the JDK you are using.

  2310. This problem may occur with all JDK's &lt; 1.2.</p>

  2311. <hr>

  2312. <h2><a name="execon">ExecOn</a></h2>

  2313. <h3>Description</h3>

  2314. <p>Executes a system command. When the <i>os</i> attribute is specified, then

  2315. the command is only executed when Ant is run on one of the specified operating

  2316. systems.</p>

  2317. <p>The files and/or directories of a number of <a

  2318. href="#fileset">FileSet</a>s are passed as arguments to the system

  2319. command. At least one nested <code>&lt;fileset&gt;</code> is required.</p>

  2320. <h3>Parameters</h3>

  2321. <table border="1" cellpadding="2" cellspacing="0">

  2322.   <tr>

  2323.     <td valign="top"><b>Attribute</b></td>

  2324.     <td valign="top"><b>Description</b></td>

  2325.     <td align="center" valign="top"><b>Required</b></td>

  2326.   </tr>

  2327.   <tr>

  2328.     <td valign="top">executable</td>

  2329.     <td valign="top">the command to execute without any command line

  2330.       arguments.</td>

  2331.     <td align="center" valign="top">Yes</td>

  2332.   </tr>

  2333.   <tr>

  2334.     <td valign="top">dir</td>

  2335.     <td valign="top">the directory in which the command should be executed.</td>

  2336.     <td align="center" valign="top">No</td>

  2337.   </tr>

  2338.   <tr>

  2339.     <td valign="top">os</td>

  2340.     <td valign="top">list of Operating Systems on which the command may be

  2341.       executed.</td>

  2342.     <td align="center" valign="top">No</td>

  2343.   </tr>

  2344.   <tr>

  2345.     <td valign="top">output</td>

  2346.     <td valign="top">the file to which the output of the command should be

  2347.       redirected.</td>

  2348.     <td align="center" valign="top">No</td>

  2349.   </tr>

  2350.   <tr>

  2351.     <td valign="top">timeout</td>

  2352.     <td valign="top">Stop the command if it doesn't finish within the

  2353.       specified time (given in milliseconds).</td>

  2354.     <td align="center" valign="top">No</td>

  2355.   </tr>

  2356.   <tr>

  2357.     <td valign="top">failonerror</td>

  2358.     <td valign="top">Stop the buildprocess if the command exits with a

  2359.       returncode other than 0.</td>

  2360.     <td align="center" valign="top">No</td>

  2361.   </tr>

  2362.   <tr>

  2363.     <td valign="top">newenvironment</td>

  2364.     <td valign="top">Do not propagate old environment when new environment

  2365.       variables are specified.</td>

  2366.     <td align="center" valign="top">No, default is <i>false</i></td>

  2367.   </tr>

  2368.   <tr>

  2369.     <td valign="top">parallel</td>

  2370.     <td valign="top">Run the command only once, appending all files as

  2371.       arguments. Defaults to true. If false, command will be executed

  2372.       once for every file.</td>

  2373.     <td align="center" valign="top">No</td>

  2374.   </tr>

  2375.   <tr>

  2376.     <td valign="top">type</td>

  2377.     <td valign="top">One of <i>file</i>, <i>dir</i> or

  2378.       <i>both</i>. If set to <i>file</i>, only the names of plain

  2379.       files will be sent to the command. If set to <i>dir</i>, only

  2380.       the names of directories are considered.</td>

  2381.     <td align="center" valign="top">No, default is <i>file</i></td>

  2382.   </tr>

  2383. </table>

  2384. <h3>Parameters specified as nested elements</h3>

  2385. <h4>fileset</h4>

  2386. <p>You can use any number of nested <code>&lt;fileset&gt;</code>

  2387. elements to define the files for this task and refer to

  2388. <code>&lt;fileset&gt;</code>s defined elsewhere.</p>

  2389. <h4>arg</h4>

  2390. <p>Command line arguments should be specified as nested

  2391. <code>&lt;arg&gt;</code> elements. See <a

  2392. href="index.html#arg">Command line arguments</a>.</p>

  2393. <h4>srcfile</h4>

  2394. <p>By default the file names of the source files will be added to the

  2395. end of the command line. If you need to place it somewhere different,

  2396. use a nested <code>&lt;srcfile&gt;</code> element between your

  2397. <code>&lt;arg&gt;</code> elements to mark the insertion point.</code>

  2398. <h4>env</h4>

  2399. <p>It is possible to specify environment variables to pass to the

  2400. system command via nested <code>&lt;env&gt;</code> elements. See the

  2401. description in the section about <a href="#env">exec</a></p>

  2402. <p>Please note that the environment of the current Ant process is

  2403. <b>not</b> passed to the system command if you specify variables using

  2404. <code>&lt;env&gt;</code>.</p>

  2405. <h3>Examples</h3>

  2406. <blockquote><pre>

  2407. &lt;execon executable=&quot;ls&quot; &gt;

  2408.   &lt;arg value=&quot;-l&quot;/&gt;

  2409.   &lt;fileset dir=&quot;/tmp&quot;&gt;

  2410.     &lt;patternset&gt;

  2411.       &lt;exclude name=&quot;**/*.txt&quot;/&gt;

  2412.     &lt;/patternset&gt;

  2413.   &lt;/fileset&gt;

  2414.   &lt;fileset refid=&quot;other.files&quot;/&gt;

  2415. &lt;/execon&gt;

  2416. </pre></blockquote>

  2417. <p>invokes <code>ls -l</code>, adding the absolute filenames of all

  2418. files below <code>/tmp</code> not ending in <code>.txt</code> and all

  2419. files of the FileSet with <code>id</code> <code>other.files</code> to

  2420. the command line.</p>

  2421. <blockquote><pre>

  2422. &lt;execon executable=&quot;somecommand&quot; parallel=&quot;false&quot; &gt;

  2423.   &lt;arg value=&quot;arg1&quot;/&gt;

  2424.   &lt;srfile/&gt;

  2425.   &lt;arg value=&quot;arg2&quot;/&gt;

  2426.   &lt;fileset dir=&quot;/tmp&quot;/&gt;

  2427. &lt;/execon&gt;

  2428. </pre></blockquote>

  2429. <p>invokes <code>somecommand arg1 SOURCEFILENAME arg2</code> for each

  2430. file in <code>/tmp</code> replacing SOURCEFILENAME with the absolute

  2431. filename of each file in turn. If <code>parallel</code> had been set

  2432. to true, SOURCEFILENAME would be replaced with the absolute filenames

  2433. of all files separated by spaces.</p>

  2434. <hr>

  2435. <h2><a name="fail">Fail</a></h2>

  2436. <h3>Description</h3>

  2437. <p>Exits the current build (just throwing a BuildException), optionally printing additional information.</p>

  2438. <h3>Parameters</h3>

  2439. <table border="1" cellpadding="2" cellspacing="0">

  2440.   <tr>

  2441.     <td valign="top"><b>Attribute</b></td>

  2442.     <td valign="top"><b>Description</b></td>

  2443.     <td align="center" valign="top"><b>Required</b></td>

  2444.   </tr>

  2445.   <tr>

  2446.     <td valign="top">message</td>

  2447.     <td valign="top">A message giving further information on why the build exited</td>

  2448.     <td align="center" valign="top">No</td>

  2449.   </tr>

  2450. </table>

  2451. <h3>Examples</h3>

  2452. <pre>  &lt;fail/&gt;</pre>

  2453. <p>will exit the current build with no further information given.

  2454. <pre>

  2455. BUILD FAILED

  2456. 

  2457. build.xml:4: No message

  2458. </pre>

  2459. 

  2460. <pre>  &lt;fail message=&quot;Something wrong here.&quot;/&gt;</pre>

  2461. <p>will exit the current build and print something like the following to whereever

  2462. your output goes:

  2463. <pre>

  2464. BUILD FAILED

  2465. 

  2466. build.xml:4: Something wrong here.

  2467. </pre>

  2468. 

  2469. <hr>

  2470. <h2><a name="filter">Filter</a></h2>

  2471. <h3>Description</h3>

  2472. <p>Sets a token filter for this project or read multiple token filter from

  2473. an input file and sets these as filters.

  2474. Token filters are used by all tasks that perform file copying operations

  2475. through the Project commodity methods.</p>

  2476. <p>Note 1: the token string must not contain the separators chars (@).<br>

  2477. Note 2: Either token and value attributes must be provided, or only the

  2478. filterfile attribute.</p>

  2479. 

  2480. <h3>Parameters</h3>

  2481. <table border="1" cellpadding="2" cellspacing="0">

  2482.   <tr>

  2483.     <td valign="top"><b>Attribute</b></td>

  2484.     <td valign="top"><b>Description</b></td>

  2485.     <td align="center" valign="top"><b>Required</b></td>

  2486.   </tr>

  2487.   <tr>

  2488.     <td valign="top">token</td>

  2489.     <td valign="top">the token string without @</td>

  2490.     <td align="center" valign="top">Yes*</td>

  2491.   </tr>

  2492.   <tr>

  2493.     <td valign="top">value</td>

  2494.     <td valign="top">the string that should be put to replace the token when the 

  2495.       file is copied</td>

  2496.     <td align="center" valign="top">Yes*</td>

  2497.   </tr>

  2498.   <tr>

  2499.     <td valign="top">filtersfile</td>

  2500.     <td valign="top">The file from which the filters must be read. This file must be a formatted as a property file. </td>

  2501.     <td align="center" valign="top">Yes*</td>

  2502.   </tr>

  2503. </table>

  2504. <p>* see notes 1 and 2 above parameters table.</p>

  2505. <h3>Examples</h3>

  2506. <pre>  &lt;filter token=&quot;year&quot; value=&quot;2000&quot;/&gt;

  2507.   &lt;copy todir=&quot;${dest.dir}&quot;&gt;

  2508.     &lt;fileset dir=&quot;${src.dir}&quot;/&gt;

  2509.   &lt;/copy&gt;</pre> 

  2510. <p>will copy recursively all the files from the <i>src.dir</i> directory into

  2511. the <i>dest.dir</i> directory replacing all the occurencies of the string <i>@year@</i>

  2512. with <i>2000.</i></p>

  2513. <pre>  &lt;filter filterfile=&quot;deploy_env.properties&quot;/&gt;</pre>

  2514. will read all property entries from the <i>deploy_env.properties</i> file

  2515. and set these as filters.

  2516. 

  2517. <hr>

  2518. <h2><a name="fixcrlf">FixCRLF</a></h2>

  2519. <h3>Description</h3>

  2520. <p>Adjusts a text file to local.</p>

  2521. <p>It is possible to refine the set of files that are being adjusted. This can be

  2522. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  2523. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  2524. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  2525. the files you want to have excluded. This is also done with patterns. And

  2526. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  2527. want to use default exclusions or not. See the section on <a

  2528. href="#directorybasedtasks">directory based tasks</a>, on how the

  2529. inclusion/exclusion of files works, and how to write patterns.</p>

  2530. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  2531. supports all attributes of <code>&lt;fileset&gt;</code>

  2532. (<code>dir</code> becomes <code>srcdir</code>) as well as the nested

  2533. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  2534. <code>&lt;patternset&gt;</code> elements.</p>

  2535. <h3>Parameters</h3>

  2536. <table border="1" cellpadding="2" cellspacing="0">

  2537.   <tr>

  2538.     <td valign="top"><b>Attribute</b></td>

  2539.     <td valign="top"><b>Description</b></td>

  2540.     <td align="center" valign="top"><b>Required</b></td>

  2541.   </tr>

  2542.   <tr>

  2543.     <td valign="top">srcDir</td>

  2544.     <td valign="top">Where to find the files to be fixed up.</td>

  2545.     <td valign="top" align="center">Yes</td>

  2546.   </tr>

  2547.   <tr>

  2548.     <td valign="top">destDir</td>

  2549.     <td valign="top">Where to place the corrected files.  Defaults to

  2550.       srcDir (replacing the original file)</td>

  2551.     <td valign="top" align="center">No</td>

  2552.   </tr>

  2553.   <tr>

  2554.     <td valign="top">includes</td>

  2555.     <td valign="top">comma separated list of patterns of files that must be

  2556.       included. All files are included when omitted.</td>

  2557.     <td valign="top" align="center">No</td>

  2558.   </tr>

  2559.   <tr>

  2560.     <td valign="top">includesfile</td>

  2561.     <td valign="top">the name of a file. Each line of this file is

  2562.       taken to be an include pattern</td>

  2563.     <td valign="top" align="center">No</td>

  2564.   </tr>

  2565.   <tr>

  2566.     <td valign="top">excludes</td>

  2567.     <td valign="top">comma separated list of patterns of files that must be

  2568.       excluded. No files (except default excludes) are excluded when omitted.</td>

  2569.     <td valign="top" align="center">No</td>

  2570.   </tr>

  2571.   <tr>

  2572.     <td valign="top">excludesfile</td>

  2573.     <td valign="top">the name of a file. Each line of this file is

  2574.       taken to be an exclude pattern</td>

  2575.     <td valign="top" align="center">No</td>

  2576.   </tr>

  2577.   <tr>

  2578.     <td valign="top">defaultexcludes</td>

  2579.     <td valign="top">indicates whether default excludes should be used or not

  2580.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  2581.     <td valign="top" align="center">No</td>

  2582.   </tr>

  2583.   <tr>

  2584.     <td valign="top">cr</td>

  2585.     <td valign="top">Specifies how carriage return (CR) characters are to

  2586.       be handled.  Valid values for this property are:

  2587.       <ul>

  2588.       <li>add: ensure that there is a CR before every LF

  2589.       <li>asis: leave CR characters alone

  2590.       <li>remove: remove all CR characters

  2591.       </ul>

  2592.       Default is based on the platform on which you are running this task.

  2593.       For Unix platforms, the default is remove.  For DOS based systems

  2594.       (including Windows), the default is add.

  2595.       <p>

  2596.       Note: Unless this property is specified as &quot;asis&quot;, extra CR characters

  2597.       which do not precede a LF will be removed.

  2598.       </td>

  2599.     <td valign="top" align="center">No</td>

  2600.   </tr>

  2601.   <tr>

  2602.     <td valign="top">tab</td>

  2603.     <td valign="top">Specifies how tab characters are to be handled.  Valid

  2604.       values for this property are:

  2605.       <ul>

  2606.       <li>add: convert sequences of spaces which span a tab stop to tabs

  2607.       <li>asis: leave tab and space characters alone

  2608.       <li>remove: convert tabs to spaces

  2609.       </ul>

  2610.       Default for this parameter is &quot;asis&quot;.

  2611.       <p>

  2612.       Note: Unless this property is specified as &quot;asis&quot;, extra spaces and

  2613.       tabs after the last non-whitespace character on the line will be removed.

  2614.       </td>

  2615.     <td valign="top" align="center">No</td>

  2616.   </tr>

  2617.   <tr>

  2618.     <td valign="top">tablength</td>

  2619.     <td valign="top">The number of characters a TAB stop corresponds to. 

  2620.       Must be a positive power of 2, default for this parameter is 8.</td>

  2621.     <td valign="top" align="center">No</td>

  2622.   </tr>

  2623.   <tr>

  2624.     <td valign="top">eof</td>

  2625.     <td valign="top">Specifies how DOS end of file (control-Z) characters are

  2626.       to be handled.  Valid values for this property are:

  2627.       <ul>

  2628.       <li>add: ensure that there is an EOF character at the end of the file

  2629.       <li>asis: leave EOF characters alone

  2630.       <li>remove: remove any EOF character found at the end

  2631.       </ul>

  2632.       Default is based on the platform on which you are running this task.

  2633.       For Unix platforms, the default is remove.  For DOS based systems

  2634.       (including Windows), the default is asis.

  2635.       </td>

  2636.     <td valign="top" align="center">No</td>

  2637.   </tr>

  2638. </table>

  2639. <h3>Examples</h3>

  2640. <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;

  2641.        cr=&quot;remove&quot; eof=&quot;remove&quot;

  2642.        includes=&quot;**/*.sh&quot;

  2643.   /&gt;</pre>

  2644. <p>Removes carriage return and eof characters from the shell scripts.  Tabs and

  2645. spaces are left as is.

  2646. <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;

  2647.        cr=&quot;add&quot;

  2648.        includes=&quot;**/*.bat&quot;

  2649.   /&gt;</pre>

  2650. <p>Ensures that there are carriage return characters prior to evey line feed.

  2651. Tabs and spaces are left as is.

  2652. EOF characters are left alone if run on

  2653. DOS systems, and are removed if run on Unix systems.</p>

  2654. <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;

  2655.        tabs=&quot;add&quot;

  2656.        includes=&quot;**/Makefile&quot;

  2657.   /&gt;</pre>

  2658. <p>Adds or removes CR characters to match local OS conventions, and

  2659. converts spaces to tabs when appropriate.  EOF characters are left alone if

  2660. run on DOS systems, and are removed if run on Unix systems.

  2661. Many versions of make require tabs prior to commands.</p>

  2662. <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;

  2663.        tabs=&quot;remove&quot;

  2664.        includes=&quot;**/README*&quot;

  2665.   /&gt;</pre>

  2666. <p>Adds or removes CR characters to match local OS conventions, and

  2667. converts all tabs to spaces.  EOF characters are left alone if run on

  2668. DOS systems, and are removed if run on Unix systems.

  2669. You never know what editor a user will use to browse README's.</p>

  2670. <hr>

  2671. <h2><a name="genkey">GenKey</a></h2>

  2672. <h3>Description</h3>

  2673. <p>Generates a key in keystore.</p>

  2674. 

  2675. <h3>Parameters</h3>

  2676. <table border="1" cellpadding="2" cellspacing="0">

  2677.   <tr>

  2678.     <td valign="top"><b>Attribute</b></td>

  2679.     <td valign="top"><b>Description</b></td>

  2680.     <td align="center" valign="top"><b>Required</b></td>

  2681.   </tr>

  2682.   <tr>

  2683.     <td valign="top">alias</td>

  2684.     <td valign="top">the alias to add under</td>

  2685.     <td valign="top" align="center">Yes.</td>

  2686.   </tr>

  2687.   <tr>

  2688.     <td valign="top">storepass</td>

  2689.     <td valign="top">password for keystore integrity.</td>

  2690.     <td valign="top" align="center">Yes.</td>

  2691.   </tr>

  2692.   <tr>

  2693.     <td valign="top">keystore</td>

  2694.     <td valign="top">keystore location</td>

  2695.     <td valign="top" align="center">No</td>

  2696.   </tr>

  2697.   <tr>

  2698.     <td valign="top">storetype</td>

  2699.     <td valign="top">keystore type</td>

  2700.     <td valign="top" align="center">No</td>

  2701.   </tr>

  2702.   <tr>

  2703.     <td valign="top">keypass</td>

  2704.     <td valign="top">password for private key (if different)</td>

  2705.     <td valign="top" align="center">No</td>

  2706.   </tr>

  2707.   <tr>

  2708.     <td valign="top">sigalg</td>

  2709.     <td valign="top">the algorithm to use in signing</td>

  2710.     <td valign="top" align="center">No</td>

  2711.   </tr>

  2712.   <tr>

  2713.     <td valign="top">keyalg</td>

  2714.     <td valign="top">the method to use when generating name-value pair</td>

  2715.     <td valign="top" align="center">No</td>

  2716.   </tr>

  2717.   <tr>

  2718.     <td valign="top">verbose</td>

  2719.     <td valign="top">(true | false) verbose output when signing</td>

  2720.     <td valign="top" align="center">No</td>

  2721.   </tr>

  2722.   <tr>

  2723.     <td valign="top">dname</td>

  2724.     <td valign="top">The distinguished name for entity</td>

  2725.     <td valign="top" align="center">Yes if dname element unspecified</td>

  2726.   </tr>

  2727.   <tr>

  2728.     <td valign="top">validity</td>

  2729.     <td valign="top">(integer) indicates how many days certificate is valid</td>

  2730.     <td valign="top" align="center">No</td>

  2731.   </tr>

  2732.   <tr>

  2733.     <td valign="top">keysize</td>

  2734.     <td valign="top">(integer) indicates the size of key generated</td>

  2735.     <td valign="top" align="center">No</td>

  2736.   </tr>

  2737. </table>

  2738. 

  2739. <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

  2740. <p>The following two examples are identical: </p>

  2741. 

  2742. <h3>Examples</h3>

  2743. <blockquote>

  2744.   <p><code>&lt;genkey alias=&quot;apache-group&quot; storepass=&quot;secret&quot; 

  2745.   dname=&quot;CN=Ant Group, OU=Jakarta Division, O=Apache.org, C=US&quot;/&gt;</code></p>

  2746. </blockquote>

  2747. 

  2748. <blockquote>

  2749.   <pre><code>&lt;genkey alias=&quot;apache-group&quot; storepass=&quot;secret&quot; &gt;

  2750.   &lt;dname&gt;

  2751.     &lt;param name=&quot;CN&quot; value=&quot;Ant Group&quot;/&gt;

  2752.     &lt;param name=&quot;OU&quot; value=&quot;Jakarta Division&quot;/&gt;

  2753.     &lt;param name=&quot;O&quot;  value=&quot;Apache.Org&quot;/&gt;

  2754.     &lt;param name=&quot;C&quot;  value=&quot;US&quot;/&gt;

  2755.   &lt;/dname&gt;

  2756. &lt;/genkey&gt;</code></pre>

  2757. </blockquote>

  2758. <hr>

  2759. <h2><a name="get">Get</a></h2>

  2760. <h3>Description</h3>

  2761. <p>Gets a file from a URL. When the verbose option is &quot;on&quot;, this task

  2762. displays a '.' for every 100 Kb retrieved.</p>

  2763. <p>This task should be preferred above the <a href="#cvs">CVS task</a> when

  2764. doing automated builds. CVS is significantly slower than loading a compressed

  2765. archive with http/ftp.</p>

  2766. 

  2767. The <i>usetimestamps</i> option enables you to control downloads so that the remote file is

  2768. only fetched if newer than the local copy. If there is no local copy, the download always takes 

  2769. place. When a file is downloaded, the timestamp of the downloaded file is set to the remote timestamp,

  2770. if  the JVM is Java1.2 or later. 

  2771. NB: This timestamp facility only works on downloads using the HTTP protocol. 

  2772. <h3>Parameters</h3>

  2773. <table border="1" cellpadding="2" cellspacing="0">

  2774.   <tr>

  2775.     <td valign="top"><b>Attribute</b></td>

  2776.     <td valign="top"><b>Description</b></td>

  2777.     <td align="center" valign="top"><b>Required</b></td>

  2778.   </tr>

  2779.   <tr>

  2780.     <td valign="top">src</td>

  2781.     <td valign="top">the URL from which to retrieve a file.</td>

  2782.     <td align="center" valign="top">Yes</td>

  2783.   </tr>

  2784.   <tr>

  2785.     <td valign="top">dest</td>

  2786.     <td valign="top">the file where to store the retrieved file.</td>

  2787.     <td align="center" valign="top">Yes</td>

  2788.   </tr>

  2789.   <tr>

  2790.     <td valign="top">verbose</td>

  2791.     <td valign="top">show verbose progress information (&quot;on&quot;/&quot;off&quot;).</td>

  2792.     <td align="center" valign="top">No</td>

  2793.   </tr>

  2794.   <tr>

  2795.     <td valign="top">ignoreerrors</td>

  2796.     <td valign="top">Log errors but don't treat as fatal.</td>

  2797.     <td align="center" valign="top">No</td>

  2798.   </tr>

  2799.   <tr>

  2800.     <td valign="top">usetimestamps</td>

  2801.     <td valign="top">conditionally download a file based on the timestamp of the local copy.

  2802. 	HTTP only</td>

  2803.     <td align="center" valign="top">No</td>

  2804.   </tr>

  2805. </table>

  2806. <h3>Examples</h3>

  2807. <pre>  &lt;get src=&quot;http://jakarta.apache.org/&quot; dest=&quot;help/index.html&quot;/&gt;</pre>

  2808. <p>Gets the index page of http://jakarta.apache.org/, and stores it in the file <code>help/index.html</code>.</p>

  2809. 

  2810. <pre>  &lt;get src=&quot;http://jakarta.apache.org/builds/tomcat/nightly/ant.zip&quot; 

  2811. 	dest=&quot;optional.jar&quot; 

  2812. 	verbose=&quot;true&quot;

  2813. 	usetimestamps=&quot;true&quot;/&gt;</pre>

  2814. <p>

  2815. Gets the nightly ant build from the tomcat distribution, if the local copy

  2816. is missing or out of date. Uses the verbose option 

  2817. for progress information.

  2818. </p>

  2819. 

  2820. <hr>

  2821. <h2><a name="gunzip">GUnzip</a></h2>

  2822. <h3>Description</h3>

  2823. <p>Expands a GZip file.</p>

  2824. 

  2825. <p>If <i>dest</i> is a directory the name of the destination file is

  2826. the same as <i>src</i> (with the &quot;.gz&quot; extension removed if

  2827. present). If <i>dest</i> is omitted, the parent dir of <i>src</i> is

  2828. taken. The file is only expanded if the source file is newer than the

  2829. destination file, or when the destination file does not exist.</p>

  2830. 

  2831. <h3>Parameters</h3>

  2832. <table border="1" cellpadding="2" cellspacing="0">

  2833.   <tr>

  2834.     <td valign="top"><b>Attribute</b></td>

  2835.     <td valign="top"><b>Description</b></td>

  2836.     <td align="center" valign="top"><b>Required</b></td>

  2837.   </tr>

  2838.   <tr>

  2839.     <td valign="top">src</td>

  2840.     <td valign="top">the file to expand.</td>

  2841.     <td align="center" valign="top">Yes</td>

  2842.   </tr>

  2843.   <tr>

  2844.     <td valign="top">dest</td>

  2845.     <td valign="top">the destination file or directory.</td>

  2846.     <td align="center" valign="top">No</td>

  2847.   </tr>

  2848. </table>

  2849. <h3>Examples</h3>

  2850. <blockquote>

  2851.   <p><code>&lt;gunzip src=&quot;test.tar.gz&quot;/&gt;</code></p>

  2852. </blockquote>

  2853. <p>expands <i>test.tar.gz</i> to <i>test.tar</i></p>

  2854. <blockquote>

  2855.   <p><code>&lt;gunzip src=&quot;test.tar.gz&quot; dest=&quot;test2.tar&quot;/&gt;</code></p>

  2856. </blockquote>

  2857. <p>expands <i>test.tar.gz</i> to <i>test2.tar</i></p>

  2858. <blockquote>

  2859.   <p><code>&lt;gunzip src=&quot;test.tar.gz&quot; dest=&quot;subdir&quot;/&gt;</code></p>

  2860. </blockquote>

  2861. <p>expands <i>test.tar.gz</i> to <i>subdir/test.tar</i> (assuming

  2862. subdir is a directory).</p>

  2863. 

  2864. <hr>

  2865. <h2><a name="gzip">GZip</a></h2>

  2866. <h3>Description</h3>

  2867. <p>GZips a file.</p>

  2868. <h3>Parameters</h3>

  2869. <table border="1" cellpadding="2" cellspacing="0">

  2870.   <tr>

  2871.     <td valign="top"><b>Attribute</b></td>

  2872.     <td valign="top"><b>Description</b></td>

  2873.     <td align="center" valign="top"><b>Required</b></td>

  2874.   </tr>

  2875.   <tr>

  2876.     <td valign="top">src</td>

  2877.     <td valign="top">the file to gzip.</td>

  2878.     <td align="center" valign="top">Yes</td>

  2879.   </tr>

  2880.   <tr>

  2881.     <td valign="top">zipfile</td>

  2882.     <td valign="top">the destination file.</td>

  2883.     <td align="center" valign="top">Yes</td>

  2884.   </tr>

  2885. </table>

  2886. <h3>Examples</h3>

  2887. <blockquote>

  2888.   <p><code>&lt;gzip src=&quot;test.tar&quot; zipfile=&quot;test.tar.gz&quot;

  2889.   /&gt;</code></p>

  2890. </blockquote>

  2891. <hr>

  2892. <h2><a name="jar">Jar</a></h2>

  2893. <h3>Description</h3>

  2894. <p>Jars a set of files.</p>

  2895. <p>The <i>basedir</i> attribute is the reference directory from where to jar.</p>

  2896. <p>Note that file permissions will not be stored in the resulting jarfile.</p>

  2897. <p>It is possible to refine the set of files that are being jarred. This can be

  2898. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  2899. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  2900. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  2901. the files you want to have excluded. This is also done with patterns. And

  2902. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  2903. want to use default exclusions or not. See the section on <a

  2904. href="#directorybasedtasks">directory based tasks</a>, on how the

  2905. inclusion/exclusion of files works, and how to write patterns.</p>

  2906. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  2907. supports all attributes of <code>&lt;fileset&gt;</code>

  2908. (<code>dir</code> becomes <code>basedir</code>) as well as the nested

  2909. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  2910. <code>&lt;patternset&gt;</code> elements.</p>

  2911. <p>You can also use nested file sets for more flexibility, and specify

  2912. multiple ones to merge together different trees of files into one JAR.

  2913. See the <a href="#zip">Zip</a> task for more details and examples.</p>

  2914. <p>If the manifest is omitted, a simple one will be supplied by Ant.

  2915. You should not include <samp>META-INF/MANIFEST.MF</samp> in your set of files.

  2916. <p>The <code>whenempty</code> parameter controls what happens when no files match.

  2917. If <code>create</code> (the default), the JAR is created anyway with only a manifest.

  2918. If <code>skip</code>, the JAR is not created and a warning is issued.

  2919. If <code>fail</code>, the JAR is not created and the build is halted with an error.

  2920. <p>(The Jar task is a shortcut for specifying the manifest file of a JAR file. 

  2921. The same thing can be accomplished by using the <i>fullpath</i>

  2922. attribute of a prefixedfileset in a Zip task. The one difference is that if the

  2923. <i>manifest</i> attribute is not specified, the Jar task will 

  2924. include an empty one for you.)</p>

  2925. </p>

  2926. <h3>Parameters</h3>

  2927. <table border="1" cellpadding="2" cellspacing="0">

  2928.   <tr>

  2929.     <td valign="top"><b>Attribute</b></td>

  2930.     <td valign="top"><b>Description</b></td>

  2931.     <td align="center" valign="top"><b>Required</b></td>

  2932.   </tr>

  2933.   <tr>

  2934.     <td valign="top">jarfile</td>

  2935.     <td valign="top">the jar-file to create.</td>

  2936.     <td valign="top" align="center">Yes</td>

  2937.   </tr>

  2938.   <tr>

  2939.     <td valign="top">basedir</td>

  2940.     <td valign="top">the directory from which to jar the files.</td>

  2941.     <td valign="top" align="center">No</td>

  2942.   </tr>

  2943.   <tr>

  2944.     <td valign="top">compress</td>

  2945.     <td valign="top">Not only store data but also compress them, defaults to true</td>

  2946.     <td align="center" valign="top">No</td>

  2947.   </tr>

  2948.   <tr>

  2949.     <td valign="top">includes</td>

  2950.     <td valign="top">comma separated list of patterns of files that must be

  2951.       included. All files are included when omitted.</td>

  2952.     <td valign="top" align="center">No</td>

  2953.   </tr>

  2954.   <tr>

  2955.     <td valign="top">includesfile</td>

  2956.     <td valign="top">the name of a file. Each line of this file is

  2957.       taken to be an include pattern</td>

  2958.     <td valign="top" align="center">No</td>

  2959.   </tr>

  2960.   <tr>

  2961.     <td valign="top">excludes</td>

  2962.     <td valign="top">comma separated list of patterns of files that must be

  2963.       excluded. No files (except default excludes) are excluded when omitted.</td>

  2964.     <td valign="top" align="center">No</td>

  2965.   </tr>

  2966.   <tr>

  2967.     <td valign="top">excludesfile</td>

  2968.     <td valign="top">the name of a file. Each line of this file is

  2969.       taken to be an exclude pattern</td>

  2970.     <td valign="top" align="center">No</td>

  2971.   </tr>

  2972.   <tr>

  2973.     <td valign="top">defaultexcludes</td>

  2974.     <td valign="top">indicates whether default excludes should be used or not

  2975.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  2976.     <td valign="top" align="center">No</td>

  2977.   </tr>

  2978.   <tr>

  2979.     <td valign="top">manifest</td>

  2980.     <td valign="top">the manifest file to use.</td>

  2981.     <td valign="top" align="center">No</td>

  2982.   </tr>

  2983.   <tr>

  2984.     <td valign="top">whenempty</td>

  2985.     <td valign="top">Behavior to use if no files match.</td>

  2986.     <td valign="top" align="center">No</td>

  2987.   </tr>

  2988. </table>

  2989. <h3>Examples</h3>

  2990. <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot;/&gt;</pre>

  2991. <p>jars all files in the <code>${build}/classes</code> directory into a file

  2992. called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>

  2993. <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;

  2994.        basedir=&quot;${build}/classes&quot;

  2995.        excludes=&quot;**/Test.class&quot;

  2996.   /&gt;</pre>

  2997. <p>jars all files in the <code>${build}/classes</code> directory into a file

  2998. called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Files

  2999. with the name <code>Test.class</code> are excluded.</p>

  3000. <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;

  3001.        basedir=&quot;${build}/classes&quot;

  3002.        includes=&quot;mypackage/test/**&quot;

  3003.        excludes=&quot;**/Test.class&quot;

  3004.   /&gt;</pre>

  3005. <p>jars all files in the <code>${build}/classes</code> directory into a file

  3006. called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Only

  3007. files under the directory <code>mypackage/test</code> are used, and files with

  3008. the name <code>Test.class</code> are excluded.</p>

  3009. <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;&gt;

  3010.     &lt;fileset dir=&quot;${build}/classes&quot;

  3011.              excludes=&quot;**/Test.class&quot;

  3012.     /&gt;

  3013.     &lt;fileset dir=&quot;${src}/resources&quot;/&gt;

  3014.   &lt;/jar&gt;</pre>

  3015. <p>jars all files in the <code>${build}/classes</code> directory and also

  3016. in the <code>${src}/resources</code> directory together into a file

  3017. called <code>app.jar</code> in the <code>${dist}/lib</code> directory.

  3018. Files with the name <code>Test.class</code> are excluded.

  3019. If there are files such as <code>${build}/classes/mypackage/MyClass.class</code>

  3020. and <code>${src}/resources/mypackage/image.gif</code>, they will appear

  3021. in the same directory in the JAR (and thus be considered in the same package

  3022. by Java).</p>

  3023. 

  3024. <hr>

  3025. <h2><a name="java">Java</a></h2>

  3026. <h3>Description</h3>

  3027. <p>Executes a Java class within the running (Ant) VM or forks another VM if

  3028. specified.</p>

  3029. <p>Be careful that the executed class doesn't call System.exit(), because it

  3030. will terminate the VM and thus Ant. In case this happens, it's highly suggested

  3031. that you set the fork attribute so that System.exit() stops the other VM and not

  3032. the one that is currently running Ant.</p>

  3033. <h3>Parameters</h3>

  3034. <table border="1" cellpadding="2" cellspacing="0">

  3035.   <tr>

  3036.     <td valign="top"><b>Attribute</b></td>

  3037.     <td valign="top"><b>Description</b></td>

  3038.     <td align="center" valign="top"><b>Required</b></td>

  3039.   </tr>

  3040.   <tr>

  3041.     <td valign="top">classname</td>

  3042.     <td valign="top">the Java class to execute.</td>

  3043.     <td align="center" valign="top">Yes</td>

  3044.   </tr>

  3045.   <tr>

  3046.     <td valign="top">args</td>

  3047.     <td valign="top">the arguments for the class that is

  3048.       executed. <b>deprecated, use nested <code>&lt;arg&gt;</code>

  3049.       elements instead.</b></td>

  3050.     <td align="center" valign="top">No</td>

  3051.   </tr>

  3052.   <tr>

  3053.     <td valign="top">classpath</td>

  3054.     <td valign="top">the classpath to use.</td>

  3055.     <td align="center" valign="top">No</td>

  3056.   </tr>

  3057.   <tr>

  3058.     <td valign="top">classpathref</td>

  3059.     <td valign="top">the classpath to use, given as <a

  3060.       href="#references">reference</a> to a PATH defined elsewhere.</td>

  3061.     <td align="center" valign="top">No</td>

  3062.   </tr>

  3063.   <tr>

  3064.     <td valign="top">fork</td>

  3065.     <td valign="top">if enabled triggers the class execution in another VM

  3066.       (disabled by default)</td>

  3067.     <td align="center" valign="top">No</td>

  3068.   </tr>

  3069.   <tr>

  3070.     <td valign="top">jvm</td>

  3071.     <td valign="top">the command used to invoke the Java Virtual Machine,

  3072.       default is 'java'.  The command is resolved by java.lang.Runtime.exec().

  3073.       Ignored if fork is disabled.

  3074.     </td>

  3075.     <td align="center" valign="top">No</td>

  3076.   </tr>

  3077.   <tr>

  3078.     <td valign="top">jvmargs</td>

  3079.     <td valign="top">the arguments to pass to the forked VM (ignored

  3080.       if fork is disabled). <b>deprecated, use nested

  3081.       <code>&lt;jvmarg&gt;</code> elements instead.</b></td>

  3082.     <td align="center" valign="top">No</td>

  3083.   </tr>

  3084.   <tr>

  3085.     <td valign="top">maxmemory</td>

  3086.     <td valign="top">Max amount of memory to allocate to the forked VM

  3087.       (ignored if fork is disabled)</td>

  3088.     <td align="center" valign="top">No</td>

  3089.   </tr>

  3090.   <tr>

  3091.     <td valign="top">failonerror</td>

  3092.     <td valign="top">Stop the buildprocess if the command exits with a

  3093.       returncode other than 0. Only available if fork is true.</td>

  3094.     <td align="center" valign="top">No</td>

  3095.   </tr>

  3096.   <tr>

  3097.     <td valign="top">dir</td>

  3098.     <td valign="top">The directory to invoke the VM in.  (ignored if

  3099.       fork is disabled)</td>

  3100.     <td align="center" valign="top">No</td>

  3101.   </tr>

  3102.   <tr>

  3103.     <td valign="top">output</td>

  3104.     <td valign="top">Name of a file to write the output to.</td>

  3105.     <td align="center" valign="top">No</td>

  3106.   </tr>

  3107. </table>

  3108. <h3>Parameters specified as nested elements</h3>

  3109. <h4>arg and jvmarg</h4>

  3110. <p>Use nested <code>&lt;arg&gt;</code> and <code>&lt;jvmarg&gt;</code>

  3111. elements to specify arguments for the or the forked VM. See <a

  3112. href="index.html#arg">Command line arguments</a>.</p>

  3113. <h4>sysproperty</h4>

  3114. <p>Use nested <code>&lt;sysproperty&gt;</code>

  3115. elements to specify system properties required by the class. 

  3116. These properties will be made available to the VM during the execution

  3117. of the class (either ANT's VM or the forked VM). The attributes

  3118. for this element are the same as for <a href="index.html#env">environment

  3119. variables</a>.</p>

  3120. <h4>classpath</h4>

  3121. <p><code>Java</code>'s <i>classpath</i> attribute is a <a

  3122. href="#path">PATH like structure</a> and can also be set via a nested

  3123. <i>classpath</i> element.</p>

  3124. <h5>Example</h5>

  3125. <pre>  

  3126.        &lt;java classname=&quot;test.Main&quot; &gt;

  3127.          &lt;arg value=&quot;-h&quot;/&gt; 

  3128.          &lt;classpath&gt;

  3129.            &lt;pathelement location=&quot;\test.jar&quot;/&gt;

  3130.            &lt;pathelement path=&quot;${java.class.path}&quot;/&gt;

  3131.          &lt;/classpath&gt;

  3132.        &lt;/java&gt;

  3133. </pre>

  3134. <h3>Examples</h3>

  3135. <pre>  &lt;java classname=&quot;test.Main&quot;/&gt;</pre>

  3136. <pre>  &lt;java classname=&quot;test.Main&quot;

  3137.         fork=&quot;yes&quot; &gt;

  3138.     &lt;sysproperty key=&quot;DEBUG&quot; value=&quot;true&quot;/&gt; 

  3139.     &lt;arg value=&quot;-h&quot;/&gt; 

  3140.     &lt;jvmarg value=&quot;-Xrunhprof:cpu=samples,file=log.txt,depth=3&quot;/&gt; 

  3141.   &lt;/java&gt;

  3142. </pre>

  3143. 

  3144. <hr>

  3145. <h2><a name="javac">Javac</a></h2>

  3146. <h3>Description</h3>

  3147. <p>Compiles a source tree within the running (Ant) VM.</p>

  3148. <p>The source and destination directory will be recursively scanned for Java

  3149. source files to compile. Only Java files that have no corresponding class file

  3150. or where the class file is older than the java file will be compiled.</p>

  3151. <p>The directory structure of the source tree should follow the package

  3152. hierarchy.</p>

  3153. <p>It is possible to refine the set of files that are being compiled/copied.

  3154. This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  3155. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  3156. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  3157. the files you want to have excluded. This is also done with patterns. And

  3158. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  3159. want to use default exclusions or not. See the section on <a

  3160. href="#directorybasedtasks">directory based tasks</a>, on how the

  3161. inclusion/exclusion of files works, and how to write patterns.</p>

  3162. <p>It is possible to use different compilers. This can be selected with the

  3163. &quot;build.compiler&quot; property. There are four choices:</p>

  3164. <ul>

  3165.   <li>classic (the standard compiler of JDK 1.1/1.2)</li>

  3166.   <li>modern (the new compiler of JDK 1.3)</li>

  3167.   <li>jikes (the <a

  3168.     href="http://oss.software.ibm.com/developerworks/opensource/jikes/project">Jikes</a>

  3169.     compiler)</li>

  3170.   <li>jvc (the Command-Line Compiler from Microsoft's SDK for Java /

  3171.     Visual J++)</li>

  3172. </ul>

  3173. <p>For JDK 1.1/1.2 is classic the default. For JDK 1.3 is modern the default.

  3174. If you whish to use a different compiler interface then one of the four

  3175. supplied, then write a class that implements the CompilerAdapter interface

  3176. (package org.apache.tools.ant.taskdefs.compilers). Supply the full

  3177. classname in the &quot;build.compiler&quot; property.

  3178. </p>

  3179. <h3>Parameters</h3>

  3180. <table border="1" cellpadding="2" cellspacing="0">

  3181.   <tr>

  3182.     <td valign="top"><b>Attribute</b></td>

  3183.     <td valign="top"><b>Description</b></td>

  3184.     <td align="center" valign="top"><b>Required</b></td>

  3185.   </tr>

  3186.   <tr>

  3187.     <td valign="top">srcdir</td>

  3188.     <td valign="top">location of the java files.</td>

  3189.     <td align="center" valign="top">Yes, unless nested <code>&lt;src&gt;</code> elements are present.</td>

  3190.   </tr>

  3191.   <tr>

  3192.     <td valign="top">destdir</td>

  3193.     <td valign="top">location where to store the class files.</td>

  3194.     <td align="center" valign="top">No</td>

  3195.   </tr>

  3196.   <tr>

  3197.     <td valign="top">includes</td>

  3198.     <td valign="top">comma separated list of patterns of files that must be

  3199.       included. All files are included when omitted.</td>

  3200.     <td valign="top" align="center">No</td>

  3201.   </tr>

  3202.   <tr>

  3203.     <td valign="top">includesfile</td>

  3204.     <td valign="top">the name of a file. Each line of this file is

  3205.       taken to be an include pattern</td>

  3206.     <td valign="top" align="center">No</td>

  3207.   </tr>

  3208.   <tr>

  3209.     <td valign="top">excludes</td>

  3210.     <td valign="top">comma separated list of patterns of files that must be

  3211.       excluded. No files (except default excludes) are excluded when omitted.</td>

  3212.     <td valign="top" align="center">No</td>

  3213.   </tr>

  3214.   <tr>

  3215.     <td valign="top">excludesfile</td>

  3216.     <td valign="top">the name of a file. Each line of this file is

  3217.       taken to be an exclude pattern</td>

  3218.     <td valign="top" align="center">No</td>

  3219.   </tr>

  3220.   <tr>

  3221.     <td valign="top">defaultexcludes</td>

  3222.     <td valign="top">indicates whether default excludes should be used or not

  3223.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  3224.     <td valign="top" align="center">No</td>

  3225.   </tr>

  3226.   <tr>

  3227.     <td valign="top">classpath</td>

  3228.     <td valign="top">the classpath to use.</td>

  3229.     <td align="center" valign="top">No</td>

  3230.   </tr>

  3231.   <tr>

  3232.     <td valign="top">bootclasspath</td>

  3233.     <td valign="top">location of bootstrap class files.</td>

  3234.     <td align="center" valign="top">No</td>

  3235.   </tr>

  3236.   <tr>

  3237.     <td valign="top">classpathref</td>

  3238.     <td valign="top">the classpath to use, given as <a

  3239.       href="#references">reference</a> to a PATH defined elsewhere.</td>

  3240.     <td align="center" valign="top">No</td>

  3241.   </tr>

  3242.   <tr>

  3243.     <td valign="top">bootclasspathref</td>

  3244.     <td valign="top">location of bootstrap class files, given as by <a

  3245.       href="#references">reference</a> to a PATH defined elsewhere.</td>

  3246.     <td align="center" valign="top">No</td>

  3247.   </tr>

  3248.   <tr>

  3249.     <td valign="top">extdirs</td>

  3250.     <td valign="top">location of installed extensions.</td>

  3251.     <td align="center" valign="top">No</td>

  3252.   </tr>

  3253.   <tr>

  3254.     <td valign="top">encoding</td>

  3255.     <td valign="top">encoding of source files.</td>

  3256.     <td align="center" valign="top">No</td>

  3257.   </tr>

  3258.   <tr>

  3259.     <td valign="top">debug</td>

  3260.     <td valign="top">indicates whether there should be compiled with debug

  3261.       information (&quot;off&quot;).</td>

  3262.     <td align="center" valign="top">No</td>

  3263.   </tr>

  3264.   <tr>

  3265.     <td valign="top">optimize</td>

  3266.     <td valign="top">indicates whether there should be compiled with

  3267.       optimization (&quot;off&quot;).</td>

  3268.     <td align="center" valign="top">No</td>

  3269.   </tr>

  3270.   <tr>

  3271.     <td valign="top">deprecation</td>

  3272.     <td valign="top">indicates whether there should be compiled with deprecation

  3273.       information (&quot;off&quot;).</td>

  3274.     <td align="center" valign="top">No</td>

  3275.   </tr>

  3276.   <tr>

  3277.     <td valign="top">target</td>

  3278.     <td valign="top">Generate class files for specific VM version, e.g.

  3279. 	 &quot;1.1&quot; or &quot;1.2&quot;.</td>

  3280.     <td align="center" valign="top">No</td>

  3281.   </tr>

  3282.   <tr>

  3283.     <td valign="top">verbose</td>

  3284.     <td valign="top">asks the compiler for verbose output.</td>

  3285.     <td align="center" valign="top">No</td>

  3286.   </tr>

  3287.   <tr>

  3288.     <td valign="top">depend</td> <td valign="top">enables dependency

  3289.       tracking for compilers that support this (jikes and classic)</td>

  3290.     <td align="center" valign="top">No</td>

  3291.   </tr>

  3292.   <tr>

  3293.     <td valign="top">includeAntRuntime</td> 

  3294.     <td valign="top">whether or not to include the ant runtime libraries.

  3295.       Default is no.</td>

  3296.     <td align="center" valign="top">No</td>

  3297.   </tr>

  3298.   <tr>

  3299.     <td valign="top">includeJavaRuntim</td> 

  3300.     <td valign="top">whether or not to include the default runtime

  3301.       libraries from the executing virtual machine. Default is no.</td>

  3302.     <td align="center" valign="top">No</td>

  3303.   </tr>

  3304.   <tr>

  3305.     <td valign="top">failonerror</td> <td valign="top">

  3306.         If set to false, the build will continue even if there are compilation errors. 

  3307.         Defaults to true.

  3308.     </td>

  3309.     <td align="center" valign="top">No</td>

  3310.   </tr>

  3311. </table>

  3312. 

  3313. <h3>Parameters specified as nested elements</h3>

  3314. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  3315. supports all attributes of <code>&lt;fileset&gt;</code>

  3316. (<code>dir</code> becomes <code>srcdir</code>) as well as the nested

  3317. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  3318. <code>&lt;patternset&gt;</code> elements.</p>

  3319. <h4>src, classpath, bootclasspath and extdirs</h4>

  3320. <p><code>Javac</code>'s <i>srcdir</i>, <i>classpath</i>,

  3321. <i>bootclasspath</i> and <i>extdirs</i> attributes are <a

  3322. href="#path">PATH like structure</a> and can also be set via nested

  3323. <i>src</i>, <i>classpath</i>, <i>bootclasspath</i> and

  3324. <i>extdirs</i> elements respectively.</p>

  3325. 

  3326. <h3>Examples</h3>

  3327. <pre>  &lt;javac srcdir=&quot;${src}&quot;

  3328.          destdir=&quot;${build}&quot;

  3329.          classpath=&quot;xyz.jar&quot;

  3330.          debug=&quot;on&quot;

  3331.   /&gt;</pre>

  3332. <p>compiles all .java files under the directory <code>${src}</code>, and stores

  3333. the .class files in the directory <code>${build}</code>. 

  3334. The classpath used contains <code>xyz.jar</code>, and debug information is on.</p>

  3335. <pre>  &lt;javac srcdir=&quot;${src}&quot;

  3336.          destdir=&quot;${build}&quot;

  3337.          includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;

  3338.          excludes=&quot;mypackage/p1/testpackage/**&quot;

  3339.          classpath=&quot;xyz.jar&quot;

  3340.          debug=&quot;on&quot;

  3341.   /&gt;</pre>

  3342. <p>compiles .java files under the directory <code>${src}</code>, and stores the

  3343. .class files in the directory <code>${build}</code>. 

  3344. The classpath used contains <code>xyz.jar</code>, and debug information is on.

  3345. Only files under <code>mypackage/p1</code> and <code>mypackage/p2</code> are

  3346. used. Files in the <code>mypackage/p1/testpackage</code> directory are excluded

  3347. form compilation and copy.</p>

  3348. 

  3349. <pre>  &lt;javac srcdir=&quot;${src}:${src2}&quot;

  3350.          destdir=&quot;${build}&quot;

  3351.          includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;

  3352.          excludes=&quot;mypackage/p1/testpackage/**&quot;

  3353.          classpath=&quot;xyz.jar&quot;

  3354.          debug=&quot;on&quot;

  3355.   /&gt;</pre>

  3356. 

  3357. <p>is the same as the previous example with the addition of a second source path, defined by

  3358. the propery <code>src2</code>. This can also be represented using nested elements as follows

  3359. 

  3360. <pre>  &lt;javac destdir=&quot;${build}&quot;

  3361.          classpath=&quot;xyz.jar&quot;

  3362.          debug=&quot;on&quot;&gt;

  3363.     &lt;src path=&quot;${src}&quot;/&gt;

  3364.     &lt;src path=&quot;${src2}&quot;/&gt;

  3365.     &lt;include name=&quot;mypackage/p1/**&quot;/&gt;

  3366.     &lt;include name=&quot;mypackage/p2/**&quot;/&gt;

  3367.     &lt;exclude name=&quot;mypackage/p1/testpackage/**&quot;/&gt;

  3368.   &lt;/javac&gt;</pre>

  3369. 

  3370. <p><b>Note:</b> If you are using Ant on Windows and a new DOS-Window pops up

  3371. for every use of an external compiler this may be a problem of the JDK you are using.

  3372. This problem may occur with all JDK's &lt; 1.2.</p>

  3373. 

  3374. <hr>

  3375. <h2><a name="javadoc">Javadoc/Javadoc2</a></h2>

  3376. <h3>Description</h3>

  3377. <p>Generates code documentation using the javadoc tool.</p>

  3378. <p>The source directory will be recursively scanned for Java source files to process

  3379. but only those matching the inclusion rules will be passed to the javadoc tool. This

  3380. allows wildcards to be used to choose between package names, reducing verbosity

  3381. and management costs over time. This task, however, has no notion of

  3382. &quot;changed&quot; files, unlike the <a href="#javac">javac</a> task. This means

  3383. all packages will be processed each time this task is run. In general, however,

  3384. this task is used much less frequently.</p>

  3385. <p>This task works seamlessly between different javadoc versions (1.1 and 1.2),

  3386. with the obvious restriction that the 1.2 attributes will be ignored if run in a

  3387. 1.1 VM.</p>

  3388. <p>NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the

  3389. same VM as ant without breaking functionality. For this reason, this task 

  3390. always forks the VM. This overhead is not significant since javadoc is normally a heavy

  3391. application and will be called infrequently.</p>

  3392. <p>NOTE: the packagelist attribute allows you to specify the list of packages to 

  3393. document outside of the Ant file. It's a much better practice to include everything 

  3394. inside the build.xml file. This option was added in order to make it easier to 

  3395. migrate from regular makefiles, where you would use this option of javadoc. 

  3396. The packages listed in packagelist are not checked, so the task performs even 

  3397. if some packages are missing or broken. Use this option if you wish to convert from 

  3398. an existing makefile. Once things are running you should then switch to the regular 

  3399. notation. 

  3400. 

  3401. <p>DEPRECATION: the javadoc2 task simply points to the javadoc task and it's

  3402. there for back compatibility reasons. Since this task will be removed in future

  3403. versions, you are strongly encouraged to use <a href="#javadoc">javadoc</a>

  3404. instead.</p>

  3405. <h3>Parameters</h3>

  3406. <table border="1" cellpadding="2" cellspacing="0">

  3407.   <tr>

  3408.     <td valign="top"><b>Attribute</b></td>

  3409.     <td valign="top"><b>Description</b></td>

  3410.     <td align="center" valign="top"><b>Availability</b></td>

  3411.     <td align="center" valign="top"><b>Required</b></td>

  3412.   </tr>

  3413.   <tr>

  3414.     <td valign="top">sourcepath</td>

  3415.     <td valign="top">Specify where to find source files</td>

  3416.     <td align="center" valign="top">all</td>

  3417.     <td align="center" rowspan="2">At least one of the two or nested

  3418.       <code>&lt;sourcepath&gt;</code></td>

  3419.   </tr>

  3420.   <tr>

  3421.     <td valign="top">sourcepathref</td>

  3422.     <td valign="top">Specify where to find source files by <a

  3423.       href="#references">reference</a> to a PATH defined elsewhere.</td>

  3424.     <td align="center" valign="top">all</td>

  3425.   </tr>

  3426.   <tr>

  3427.     <td valign="top">destdir</td>

  3428.     <td valign="top">Destination directory for output files</td>

  3429.     <td align="center" valign="top">all</td>

  3430.     <td align="center" valign="top">Yes</td>

  3431.   </tr>

  3432.   <tr>

  3433.     <td valign="top">maxmemory</td>

  3434.     <td valign="top">Max amount of memory to allocate to the javadoc VM</td>

  3435.     <td align="center" valign="top">all</td>

  3436.     <td align="center" valign="top">No</td>

  3437.   </tr>

  3438.   <tr>

  3439.     <td valign="top">sourcefiles</td>

  3440.     <td valign="top">Space separated list of source files</td>

  3441.     <td align="center" valign="top">all</td>

  3442.     <td align="center" valign="middle" rowspan="2">at least one of the two</td>

  3443.   </tr>

  3444.   <tr>

  3445.     <td valign="top">packagenames</td>

  3446.     <td valign="top">Comma separated list of package files (with terminating

  3447.       wildcard)</td>

  3448.     <td align="center" valign="top">all</td>

  3449.   </tr>

  3450.   <tr>

  3451.     <td valign="top">packageList</td>

  3452.     <td valign="top">The name of a file containing the packages to process</td>

  3453.     <td align="center" valign="top">all</td>

  3454.     <td align="center" valign="top">No</td>

  3455.   </tr>

  3456.   <tr>

  3457.     <td valign="top">classpath</td>

  3458.     <td valign="top">Specify where to find user class files</td>

  3459.     <td align="center" valign="top">all</td>

  3460.     <td align="center" valign="top">No</td>

  3461.   </tr>

  3462.   <tr>

  3463.     <td valign="top">Bootclasspath</td>

  3464.     <td valign="top">Override location of class files loaded by the bootstrap

  3465.       class loader</td>

  3466.     <td align="center" valign="top">1.2</td>

  3467.     <td align="center" valign="top">No</td>

  3468.   </tr>

  3469.   <tr>

  3470.     <td valign="top">classpathref</td>

  3471.     <td valign="top">Specify where to find user class files by <a

  3472.       href="#references">reference</a> to a PATH defined elsewhere.</td>

  3473.     <td align="center" valign="top">all</td>

  3474.     <td align="center" valign="top">No</td>

  3475.   </tr>

  3476.   <tr>

  3477.     <td valign="top">bootclasspathref</td>

  3478.     <td valign="top">Override location of class files loaded by the

  3479.       bootstrap class loader by <a href="#references">reference</a> to a

  3480.       PATH defined elsewhere.</td>

  3481.     <td align="center" valign="top">1.2</td>

  3482.     <td align="center" valign="top">No</td>

  3483.   </tr>

  3484.   <tr>

  3485.     <td valign="top">Extdirs</td>

  3486.     <td valign="top">Override location of installed extensions</td>

  3487.     <td align="center" valign="top">1.2</td>

  3488.     <td align="center" valign="top">No</td>

  3489.   </tr>

  3490.   <tr>

  3491.     <td valign="top">Overview</td>

  3492.     <td valign="top">Read overview documentation from HTML file</td>

  3493.     <td align="center" valign="top">1.2</td>

  3494.     <td align="center" valign="top">No</td>

  3495.   </tr>

  3496.   <tr>

  3497.     <td valign="top">Public</td>

  3498.     <td valign="top">Show only public classes and members</td>

  3499.     <td align="center" valign="top">all</td>

  3500.     <td align="center" valign="top">No</td>

  3501.   </tr>

  3502.   <tr>

  3503.     <td valign="top">Protected</td>

  3504.     <td valign="top">Show protected/public classes and members (default)</td>

  3505.     <td align="center" valign="top">all</td>

  3506.     <td align="center" valign="top">No</td>

  3507.   </tr>

  3508.   <tr>

  3509.     <td valign="top">Package</td>

  3510.     <td valign="top">Show package/protected/public classes and members</td>

  3511.     <td align="center" valign="top">all</td>

  3512.     <td align="center" valign="top">No</td>

  3513.   </tr>

  3514.   <tr>

  3515.     <td valign="top">Private</td>

  3516.     <td valign="top">Show all classes and members</td>

  3517.     <td align="center" valign="top">all</td>

  3518.     <td align="center" valign="top">No</td>

  3519.   </tr>

  3520.   <tr>

  3521.     <td valign="top">Old</td>

  3522.     <td valign="top">Generate output using JDK 1.1 emulating doclet</td>

  3523.     <td align="center" valign="top">1.2</td>

  3524.     <td align="center" valign="top">No</td>

  3525.   </tr>

  3526.   <tr>

  3527.     <td valign="top">Verbose</td>

  3528.     <td valign="top">Output messages about what Javadoc is doing</td>

  3529.     <td align="center" valign="top">1.2</td>

  3530.     <td align="center" valign="top">No</td>

  3531.   </tr>

  3532.   <tr>

  3533.     <td valign="top">Locale</td>

  3534.     <td valign="top">Locale to be used, e.g. en_US or en_US_WIN</td>

  3535.     <td align="center" valign="top">1.2</td>

  3536.     <td align="center" valign="top">No</td>

  3537.   </tr>

  3538.   <tr>

  3539.     <td valign="top">Encoding</td>

  3540.     <td valign="top">Source file encoding name</td>

  3541.     <td align="center" valign="top">all</td>

  3542.     <td align="center" valign="top">No</td>

  3543.   </tr>

  3544.   <tr>

  3545.     <td valign="top">Version</td>

  3546.     <td valign="top">Include @version paragraphs</td>

  3547.     <td align="center" valign="top">all</td>

  3548.     <td align="center" valign="top">No</td>

  3549.   </tr>

  3550.   <tr>

  3551.     <td valign="top">Use</td>

  3552.     <td valign="top">Create class and package usage pages</td>

  3553.     <td align="center" valign="top">1.2</td>

  3554.     <td align="center" valign="top">No</td>

  3555.   </tr>

  3556.   <tr>

  3557.     <td valign="top">Author</td>

  3558.     <td valign="top">Include @author paragraphs</td>

  3559.     <td align="center" valign="top">all</td>

  3560.     <td align="center" valign="top">No</td>

  3561.   </tr>

  3562.   <tr>

  3563.     <td valign="top">Splitindex</td>

  3564.     <td valign="top">Split index into one file per letter</td>

  3565.     <td align="center" valign="top">1.2</td>

  3566.     <td align="center" valign="top">No</td>

  3567.   </tr>

  3568.   <tr>

  3569.     <td valign="top">Windowtitle</td>

  3570.     <td valign="top">Browser window title for the documentation (text)</td>

  3571.     <td align="center" valign="top">1.2</td>

  3572.     <td align="center" valign="top">No</td>

  3573.   </tr>

  3574.   <tr>

  3575.     <td valign="top">Doctitle</td>

  3576.     <td valign="top">Include title for the package index(first) page (html-code)</td>

  3577.     <td align="center" valign="top">1.2</td>

  3578.     <td align="center" valign="top">No</td>

  3579.   </tr>

  3580.   <tr>

  3581.     <td valign="top">Header</td>

  3582.     <td valign="top">Include header text for each page (html-code)</td>

  3583.     <td align="center" valign="top">1.2</td>

  3584.     <td align="center" valign="top">No</td>

  3585.   </tr>

  3586.   <tr>

  3587.     <td valign="top">Footer</td>

  3588.     <td valign="top">Include footer text for each page (html-code)</td>

  3589.     <td align="center" valign="top">1.2</td>

  3590.     <td align="center" valign="top">No</td>

  3591.   </tr>

  3592.   <tr>

  3593.     <td valign="top">bottom</td>

  3594.     <td valign="top">Include bottom text for each page (html-code)</td>

  3595.     <td align="center" valign="top">1.2</td>

  3596.     <td align="center" valign="top">No</td>

  3597.   </tr>

  3598.   <tr>

  3599.     <td valign="top">link</td>

  3600.     <td valign="top">Create links to javadoc output at the given URL</td>

  3601.     <td align="center" valign="top">1.2</td>

  3602.     <td align="center" valign="top">No</td>

  3603.   </tr>

  3604.   <tr>

  3605.     <td valign="top">linkoffline</td>

  3606.     <td valign="top">Link to docs at &lt;url&gt; using package list at

  3607.       &lt;url2&gt;</td>

  3608.     <td align="center" valign="top">1.2</td>

  3609.     <td align="center" valign="top">No</td>

  3610.   </tr>

  3611.   <tr>

  3612.     <td valign="top">group</td>

  3613.     <td valign="top">Group specified packages together in overview page</td>

  3614.     <td align="center" valign="top">1.2</td>

  3615.     <td align="center" valign="top">No</td>

  3616.   </tr>

  3617.   <tr>

  3618.     <td valign="top">nodeprecated</td>

  3619.     <td valign="top">Do not include @deprecated information</td>

  3620.     <td align="center" valign="top">all</td>

  3621.     <td align="center" valign="top">No</td>

  3622.   </tr>

  3623.   <tr>

  3624.     <td valign="top">nodeprecatedlist</td>

  3625.     <td valign="top">Do not generate deprecated list</td>

  3626.     <td align="center" valign="top">1.2</td>

  3627.     <td align="center" valign="top">No</td>

  3628.   </tr>

  3629.   <tr>

  3630.     <td valign="top">notree</td>

  3631.     <td valign="top">Do not generate class hierarchy</td>

  3632.     <td align="center" valign="top">all</td>

  3633.     <td align="center" valign="top">No</td>

  3634.   </tr>

  3635.   <tr>

  3636.     <td valign="top">noindex</td>

  3637.     <td valign="top">Do not generate index</td>

  3638.     <td align="center" valign="top">all</td>

  3639.     <td align="center" valign="top">No</td>

  3640.   </tr>

  3641.   <tr>

  3642.     <td valign="top">nohelp</td>

  3643.     <td valign="top">Do not generate help link</td>

  3644.     <td align="center" valign="top">1.2</td>

  3645.     <td align="center" valign="top">No</td>

  3646.   </tr>

  3647.   <tr>

  3648.     <td valign="top">nonavbar</td>

  3649.     <td valign="top">Do not generate navigation bar</td>

  3650.     <td align="center" valign="top">1.2</td>

  3651.     <td align="center" valign="top">No</td>

  3652.   </tr>

  3653.   <tr>

  3654.     <td valign="top">serialwarn</td>

  3655.     <td valign="top">FUTURE: Generate warning about @serial tag</td>

  3656.     <td align="center" valign="top">1.2</td>

  3657.     <td align="center" valign="top">No</td>

  3658.   </tr>

  3659.   <tr>

  3660.     <td valign="top">helpfile</td>

  3661.     <td valign="top">FUTURE: Specifies the HTML help file to use</td>

  3662.     <td align="center" valign="top">1.2</td>

  3663.     <td align="center" valign="top">No</td>

  3664.   </tr>

  3665.   <tr>

  3666.     <td valign="top">stylesheetfile</td>

  3667.     <td valign="top">Specifies the CSS stylesheet to use</td>

  3668.     <td align="center" valign="top">1.2</td>

  3669.     <td align="center" valign="top">No</td>

  3670.   </tr>

  3671.   <tr>

  3672.     <td valign="top">charset</td>

  3673.     <td valign="top">FUTURE: Charset for cross-platform viewing of generated

  3674.       documentation</td>

  3675.     <td align="center" valign="top">1.2</td>

  3676.     <td align="center" valign="top">No</td>

  3677.   </tr>

  3678.   <tr>

  3679.     <td valign="top">docencoding</td>

  3680.     <td valign="top">Output file encoding name</td>

  3681.     <td align="center" valign="top">1.1</td>

  3682.     <td align="center" valign="top">No</td>

  3683.   </tr>

  3684.   <tr>

  3685.     <td valign="top">doclet</td>

  3686.     <td valign="top">Specifies the class file that starts the doclet used in generating the documentation.</td>

  3687.     <td align="center" valign="top">1.2</td>

  3688.     <td align="center" valign="top">No</td>

  3689.   </tr>

  3690.   <tr>

  3691.     <td valign="top">docletpath</td>

  3692.     <td valign="top">Specifies the path to the doclet class file that is specified with the -doclet option.</td>

  3693.     <td align="center" valign="top">1.2</td>

  3694.     <td align="center" valign="top">No</td>

  3695.   </tr>

  3696.   <tr>

  3697.     <td valign="top">docletpathref</td>

  3698.     <td valign="top">Specifies the path to the doclet class file that

  3699.       is specified with the -doclet option by <a

  3700.       href="#references">reference</a> to a PATH defined elsewhere.</td>

  3701.     <td align="center" valign="top">1.2</td>

  3702.     <td align="center" valign="top">No</td>

  3703.   </tr>

  3704.   <tr>

  3705.     <td valign="top">additionalparam</td>

  3706.     <td valign="top">Lets you add additional parameters to the javadoc command line. Useful for doclets</td>

  3707.     <td align="center" valign="top">1.2</td>

  3708.     <td align="center" valign="top">No</td>

  3709.   </tr>

  3710.   <tr>

  3711.     <td valign="top">failonerror</td>

  3712.     <td valign="top">Stop the buildprocess if the command exits with a

  3713.       returncode other than 0.</td>

  3714.     <td align="center" valign="top">all</td>

  3715.     <td align="center" valign="top">No</td>

  3716.   </tr>

  3717. </table>

  3718. 

  3719. <h3>Parameters specified as nested elements</h3>

  3720. <h4>link</h4>

  3721. <p>Create link to javadoc output at the given URL. This performs the

  3722. same role as the link and linkoffline attributes. You can use either

  3723. syntax (or both at once), but with the nested elements you can easily

  3724. specify multiple occurrences of the arguments.</p>

  3725. <h4>Parameters</h4>

  3726. 

  3727. <table width="60%" border="1" cellpadding="2" cellspacing="0">

  3728.   <tr>

  3729.     <td valign="top"><b>Attribute</b></td>

  3730.     <td valign="top"><b>Description</b></td>

  3731.     <td align="center" valign="top"><b>Required</b></td>

  3732.   </tr>

  3733.   <tr>

  3734.     <td valign="top">href</td>

  3735.     <td valign="top">The URL for the external documentation you wish to link to</td>

  3736.     <td align="center" valign="top">Yes</td>

  3737.   </tr>

  3738.   <tr>

  3739.     <td valign="top">offline</td>

  3740.     <td valign="top">True if this link is not available online at the time of 

  3741.                      generating the documentation</td>

  3742.     <td align="center" valign="top">No</td>

  3743.   </tr>

  3744.   <tr>

  3745.     <td valign="top">packagelistLoc</td>

  3746.     <td valign="top">The location to the directory containing the package-list file for

  3747.                      the external documentation</td>

  3748.     <td align="center" valign="top">Only if the offline attribute is true</td>

  3749.   </tr>

  3750. </table>

  3751.   

  3752. <h4>groups</h4> 

  3753. <p>Separates packages on the overview page into whatever groups you

  3754. specify, one group per table. This performs the same role as the group

  3755. attribute. You can use either syntax (or both at once), but with the

  3756. nested elements you can easily specify multiple occurrences of the

  3757. arguments.</p>

  3758. 

  3759. <table width="60%" border="1" cellpadding="2" cellspacing="0">

  3760.   <tr>

  3761.     <td valign="top"><b>Attribute</b></td>

  3762.     <td valign="top"><b>Description</b></td>

  3763.     <td align="center" valign="top"><b>Required</b></td>

  3764.   </tr>

  3765.   <tr>

  3766.     <td valign="top">title</td>

  3767.     <td valign="top">Title of the group</td>

  3768.     <td align="center" valign="top">Yes</td>

  3769.   </tr>

  3770.   <tr>

  3771.     <td valign="top">packages</td>

  3772.     <td valign="top">List of packages to include in that group</td>

  3773.     <td align="center" valign="top">Yes</td>

  3774.   </tr>

  3775. </table>

  3776. 

  3777. <h4>doclet</h4>

  3778. <p>The doclet nested element is used to specify the doclet that javadoc will 

  3779. use to process the input source files. A number of the standard javadoc arguments

  3780. are actually arguments of the standard doclet. If these are specified in the javadoc

  3781. task's attributes, they will be passed to the doclet specified in the 

  3782. <code>&lt;doclet&gt;</code> nested element. Such attributes should only be specified, 

  3783. therefore, if they can be interpreted by the doclet in use.

  3784. 

  3785. <p>If the doclet requires additional parameters, these can be specified with

  3786. <code>&lt;param&gt;</code> elements within the <code>&lt;doclet&gt;</code> 

  3787. element. These paramaters are restricted to simple strings. An example usage

  3788. of the doclet element is shown below:

  3789. 

  3790. <pre>  &lt;javadoc ...&gt;

  3791.      &lt;doclet name="theDoclet"

  3792.              path="path/to/theDoclet"&gt;

  3793.         &lt;param name="-foo" value="foovalue"/&gt;

  3794.         &lt;param name="-bar" value="barvalue"/&gt;

  3795.      &lt;/doclet&gt;

  3796.   &lt;/javadoc&gt;

  3797. </pre>

  3798. 

  3799. <h4>sourcepath, classpath and bootclasspath</h4>

  3800. <p><code>Javadoc</code>'s <i>sourcepath</i>, <i>classpath</i> and

  3801. <i>bootclasspath</i> attributes are <a href="#path">PATH like

  3802. structure</a> and can also be set via nested <i>sourcepath</i>,

  3803. <i>classpath</i> and <i>bootclasspath</i> elements

  3804. respectively.</p>

  3805. 

  3806. <h3>Example</h3>

  3807. <pre>  &lt;javadoc packagenames=&quot;com.dummy.test.*&quot;

  3808.            sourcepath=&quot;src&quot;

  3809.            destdir=&quot;docs/api&quot;

  3810.            author=&quot;true&quot;

  3811.            version=&quot;true&quot;

  3812.            use=&quot;true&quot;

  3813.            windowtitle=&quot;Test API&quot;

  3814.            doctitle=&quot;&lt;h1&gt;Test&lt;/h1&gt;&quot;

  3815.            bottom=&quot;&lt;i&gt;Copyright &amp;#169; 2000 Dummy Corp. All Rights Reserved.&lt;/i&gt;&quot;&gt;

  3816.     &lt;group title=&quot;Group 1 Packages&quot; packages=&quot;com.dummy.test.a*&quot;/&gt;

  3817.     &lt;group title=&quot;Group 2 Packages&quot; packages=&quot;com.dummy.test.b*&quot;/&gt;

  3818.     &lt;link offline=&quot;true&quot; href=&quot;http://java.sun.com/products/jdk/1.2/docs/api/&quot; packagelistLoc=&quot;C:\tmp&quot;/&gt;

  3819.     &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;

  3820.   &lt/javadoc&gt;</pre>

  3821.   

  3822. <hr>

  3823. <h2><a name="mail">Mail</a></h2>

  3824. <h3>Description</h3>

  3825. <p>A task to send SMTP email.</p>

  3826. <h3>Parameters</h3>

  3827. <table border="1" cellpadding="2" cellspacing="0">

  3828.   <tr>

  3829.     <td valign="top"><b>Attribute</b></td>

  3830.     <td valign="top"><b>Description</b></td>

  3831.     <td align="center" valign="top"><b>Required</b></td>

  3832.   </tr>

  3833.   <tr>

  3834.     <td valign="top">from</td>

  3835.     <td valign="top">Email address of sender.</td>

  3836.     <td align="center" valign="top">Yes</td>

  3837.   </tr>

  3838.   <tr>

  3839.     <td valign="top">tolist</td>

  3840.     <td valign="top">Comma-separated list of recipients.</td>

  3841.     <td align="center" valign="top">Yes</td>

  3842.   </tr>

  3843.   <tr>

  3844.     <td valign="top">message</td>

  3845.     <td valign="top">Message to send in the body of the email.</td>

  3846.     <td align="center" valign="middle" rowspan="2">Yes</td>

  3847.   </tr>

  3848.   <tr>

  3849.     <td valign="top">files</td>

  3850.     <td valign="top">Filename(s) of text to send in the body of the email. 

  3851. 	Multiple files are comma-separated.</td>

  3852.   </tr>

  3853.   <tr>

  3854.     <td valign="top">mailhost</td>

  3855.     <td valign="top">Host name of the mail server.</td>

  3856.     <td align="center" valign="top">No, default to &quot;localhost&quot;</td>

  3857.   </tr>

  3858.   <tr>

  3859.     <td valign="top">subject</td>

  3860.     <td valign="top">Email subject line.</td>

  3861.     <td align="center" valign="top">No</td>

  3862.   </tr>

  3863. </table>

  3864. <h3>Examples</h3>

  3865. <pre>

  3866.   &lt;mail from=&quot;me&quot; tolist=&quot;you&quot; subject=&quot;Results of nightly build&quot;

  3867.         files=&quot;build.log&quot;/&gt;</pre>

  3868. <p>Sends an eMail from <i>me</i> to <i>you</i> with a subject of 

  3869. <i>Results of nightly build</i> and includes the contents of <i>build.log</i>

  3870. in the body of the message.</p>

  3871. <hr>

  3872. 

  3873. <h2><a name="mkdir">Mkdir</a></h2>

  3874. <h3>Description</h3>

  3875. <p>Creates a directory. Also non-existent parent directories are created, when

  3876. necessary.</p>

  3877. <h3>Parameters</h3>

  3878. <table border="1" cellpadding="2" cellspacing="0">

  3879.   <tr>

  3880.     <td valign="top"><b>Attribute</b></td>

  3881.     <td valign="top"><b>Description</b></td>

  3882.     <td align="center" valign="top"><b>Required</b></td>

  3883.   </tr>

  3884.   <tr>

  3885.     <td valign="top">dir</td>

  3886.     <td valign="top">the directory to create.</td>

  3887.     <td align="center" valign="top">Yes</td>

  3888.   </tr>

  3889. </table>

  3890. <h3>Examples</h3>

  3891. <pre>&lt;mkdir dir=&quot;${dist}&quot;/&gt;</pre>

  3892. <p>creates a directory <code>${dist}</code>.</p>

  3893. <pre>&lt;mkdir dir=&quot;${dist}/lib&quot;/&gt;</pre>

  3894. <p>creates a directory <code>${dist}/lib</code>.</p>

  3895. <hr>

  3896. <h2><a name="move">Move</a></h2>

  3897. <h3>Description</h3>

  3898. <p>Moves a file to a new file or directory, or sets of files to

  3899. a new directory.  By default, the

  3900. destination file is overwritten if it already exists.  When <var>overwrite</var> is

  3901. turned off, then files are only moved if the source file is newer than

  3902. the destination file, or when the destination file does not exist.</p>

  3903. <p><a href="#fileset">FileSet</a>s are used to select sets of files

  3904. to move to the <var>todir</var> directory.</p>

  3905. <h3>Parameters</h3>

  3906. <table border="1" cellpadding="2" cellspacing="0">

  3907.   <tr>

  3908.     <td valign="top"><b>Attribute</b></td>

  3909.     <td valign="top"><b>Description</b></td>

  3910.     <td align="center" valign="top"><b>Required</b></td>

  3911.   </tr>

  3912.   <tr>

  3913.     <td valign="top">file</td>

  3914.     <td valign="top">the file to move</td>

  3915.     <td valign="top" align="center">One of <var>file</var> or 

  3916.      at least one nested fileset element</td>

  3917.   </tr>

  3918.   <tr>

  3919.     <td valign="top">tofile</td>

  3920.     <td valign="top">the file to move to</td>

  3921.     <td valign="top" align="center" rowspan="2">With the <var>file</var> attribute, 

  3922.     either <var>tofile</var> or <var>todir</var> can be used.  With a nested fileset, 

  3923. 	 only <var>todir</var> is allowed.</td>

  3924.   </tr>

  3925.   <tr>

  3926.     <td valign="top">todir</td>

  3927.     <td valign="top">the directory to move to</td>

  3928.   </tr>

  3929.   <tr>

  3930.     <td valign="top">overwrite</td>

  3931.     <td valign="top">overwrite existing files even if the destination

  3932.       files are newer (default is &quot;true&quot;)</td>

  3933.     <td valign="top" align="center">No</td>

  3934.   </tr>

  3935.   <tr>

  3936.     <td valign="top">filtering</td>

  3937.     <td valign="top">indicates whether token filtering should take place during

  3938.       the move.  See the <a href="#filter">filter</a> task for a description of

  3939.       how filters work.</td>

  3940.     <td valign="top" align="center">No</td>

  3941.   </tr>

  3942.   <tr>

  3943.     <td valign="top">flatten</td>

  3944.     <td valign="top">ignore directory structure of source directory,

  3945.       copy all files into a single directory, specified by the <var>todir</var>

  3946.       attribute (default is &quot;false&quot;).Note that you can achieve the 

  3947.       same effect by using a <a href="#flatten-mapper">flatten mapper</a></td>

  3948.     <td valign="top" align="center">No</td>

  3949.   </tr>

  3950.   <tr>

  3951.     <td valign="top">includeEmptyDirs</td>

  3952. 	 <td valign="top">Copy empty directories included with the nested FileSet(s).

  3953. 	   Defaults to &quot;yes&quot;.</td>

  3954. 	 <td valign="top" align="center">No</td>

  3955.   </tr>

  3956. </table>

  3957. <h3>Parameters specified as nested elements</h3>

  3958. <h4>mapper</h4>

  3959. <p>You can define file name transformations by using a nested <a

  3960. href="#mapper">mapper</a> element. The default mapper used by

  3961. <code>&lt;copy&gt;</code> is the <a

  3962. href="#identity-mapper">identity</a>.</p>

  3963. <h3>Examples</h3>

  3964. <p><b>Move a single file (rename a file)</b></p>

  3965. <pre>

  3966.   &lt;move file=&quot;file.orig&quot; tofile=&quot;file.moved&quot;/&gt;

  3967. </pre>

  3968. <p><b>Move a single file to a directory</b></p>

  3969. <pre>

  3970.   &lt;move file=&quot;file.orig&quot; todir=&quot;dir/to/move/to&quot;/&gt;

  3971. </pre>

  3972. <p><b>Move a directory to a new directory</b></p>

  3973. <pre>

  3974.   &lt;move todir=&quot;new/dir/to/move/to&quot;&gt;

  3975.     &lt;fileset dir=&quot;src/dir&quot;/&gt;

  3976.   &lt;/move&gt;

  3977. </pre>

  3978. <p><b>Move a set of files to a new directory</b></p>

  3979. <pre>

  3980.   &lt;move todir=&quot;some/new/dir&quot; &gt;

  3981.     &lt;fileset dir=&quot;my/src/dir&quot; &gt;

  3982.       &lt;include name=&quot;**/*.jar&quot;/&gt;

  3983.       &lt;exclude name=&quot;**/ant.jar&quot;/&gt;

  3984.     &lt;/fileset&gt;

  3985.   &lt;/move&gt;

  3986. </pre>

  3987. <p><b>Append <code>&quot;.bak&quot;</code> to the names of all files

  3988. in a directory.</b></p>

  3989. <pre>

  3990.   &lt;move todir=&quot;my/src/dir&quot; &gt;

  3991.     &lt;fileset dir=&quot;my/src/dir&quot; &gt;

  3992.       &lt;exclude name=&quot;**/*.bak&quot;/&gt;

  3993.     &lt;/fileset&gt;

  3994.     &lt;mapper type=&quot;glob&quot; from=&quot;*&quot; to=&quot;*.bak&quot;/&gt;

  3995.   &lt;/move&gt;

  3996. </pre>

  3997. <hr>

  3998. <h2><a name="patch">Patch</a></h2>

  3999. <h3>Description</h3>

  4000. <p>Applies a diff file to originals.</p>

  4001. <h3>Parameters</h3>

  4002. <table border="1" cellpadding="2" cellspacing="0">

  4003.   <tr>

  4004.     <td valign="top"><b>Attribute</b></td>

  4005.     <td valign="top"><b>Description</b></td>

  4006.     <td align="center" valign="top"><b>Required</b></td>

  4007.   </tr>

  4008.   <tr>

  4009.     <td valign="top">patchfile</td> 

  4010.     <td valign="top">the file that includes the diff output</td>

  4011.     <td align="center" valign="top">Yes</td>

  4012.   </tr>

  4013.   <tr>

  4014.     <td valign="top">originalfile</td> 

  4015.     <td valign="top">the file to patch</td>

  4016.     <td align="center" valign="top">No, tries to guess it from the diff 

  4017.       file</td>

  4018.   </tr>

  4019.   <tr>

  4020.     <td valign="top">backups</td> 

  4021.     <td valign="top">Keep backups of the unpatched files</td>

  4022.     <td align="center" valign="top">No</td>

  4023.   </tr>

  4024.   <tr>

  4025.     <td valign="top">quiet</td> 

  4026.     <td valign="top">Work silently unless an error occurs</td>

  4027.     <td align="center" valign="top">No</td>

  4028.   </tr>

  4029.   <tr>

  4030.     <td valign="top">reverse</td> 

  4031.     <td valign="top">Assume patch was created with old and new files 

  4032.       swapped.</td>

  4033.     <td align="center" valign="top">No</td>

  4034.   </tr>

  4035.   <tr>

  4036.     <td valign="top">ignorewhitespace</td> 

  4037.     <td valign="top">Ignore whitespace differences.</td>

  4038.     <td align="center" valign="top">No</td>

  4039.   </tr>

  4040.   <tr>

  4041.     <td valign="top">strip</td> 

  4042.     <td valign="top">Strip the smallest prefix containing <i>num</i> leading 

  4043.       slashes from filenames.</td>

  4044.     <td align="center" valign="top">No</td>

  4045.   </tr>

  4046. </table>

  4047. <h3>Examples</h3>

  4048. <pre>  &lt;patch patchfile=&quot;module.1.0-1.1.patch&quot;/&gt;</pre>

  4049. <p>applies the diff included in <i>module.1.0-1.1.patch</i> to the

  4050. files in base directory guessing the filename(s) from the diff output.

  4051. <pre>  &lt;patch patchfile=&quot;module.1.0-1.1.patch&quot; strip=&quot;1&quot;/&gt;</pre>

  4052. <p>like above but one leading directory part will be removed. i.e. if

  4053. the diff output looked like

  4054. <pre>

  4055. --- a/mod1.0/A	Mon Jun  5 17:28:41 2000

  4056. +++ a/mod1.1/A	Mon Jun  5 17:28:49 2000

  4057. </pre> 

  4058. the leading <i>a/</i> will be stripped.

  4059. <hr>

  4060. <h2><a name="property">Property</a></h2>

  4061. <h3>Description</h3>

  4062. <p>Sets a property (by name and value), or set of properties (from file or

  4063. resource) in the project.</p>

  4064. <p>When a property was set by the user, or was a property in a parent project

  4065. (that started this project with the <a href="#ant">ant task</a>), then this

  4066. property cannot be set, and will be ignored. This means that properties set

  4067. outside the current project always override the properties of the current

  4068. project.</p>

  4069. <p>There are five ways to set properties:</p>

  4070. <ul>

  4071.   <li>By supplying both the <i>name</i> and <i>value</i> attribute.</li>

  4072.   <li>By supplying both the <i>name</i> and <i>refid</i> attribute.</li>

  4073.   <li>By setting the <i>file</i> attribute with the filename of the property

  4074.     file to load. This property file has the format as defined by the file used

  4075.     in the class java.util.Properties.</li>

  4076.   <li>By setting the <i>resource</i> attribute with the resource name of the

  4077.     property file to load. This property file has the format as defined by the

  4078.     file used in the class java.util.Properties.</li>

  4079.   <li>By setting the <i>environment</i> attribute with a prefix to use.

  4080.     Properties will be defined for every environment variable by

  4081.     prefixing the suplied name and a period to the name of the variable.</li>

  4082. </ul>

  4083. <p>Although combinations of the three ways are possible, only one should be used

  4084. at a time. Problems might occur with the order in which properties are set, for

  4085. instance.</p>

  4086. <p>The value part of the properties being set, might contain references to other

  4087. properties. These references are resolved at the time these properties are set.

  4088. This also holds for properties loaded from a property file.</p>

  4089. <h3>Parameters</h3>

  4090. <table border="1" cellpadding="2" cellspacing="0">

  4091.   <tr>

  4092.     <td valign="top"><b>Attribute</b></td>

  4093.     <td valign="top"><b>Description</b></td>

  4094.     <td align="center" valign="top"><b>Required</b></td>

  4095.   </tr>

  4096.   <tr>

  4097.     <td valign="top">name</td>

  4098.     <td valign="top">the name of the property to set.</td>

  4099.     <td valign="top" align="center">Yes</td>

  4100.   </tr>

  4101.   <tr>

  4102.     <td valign="top">value</td>

  4103.     <td valign="top">the value of the property.</td>

  4104.     <td valign="middle" align="center" rowspan="5">Yes</td>

  4105.   </tr>

  4106.   <tr>

  4107.     <td valign="top">refid</td>

  4108.     <td valign="top"><a href="#references">Reference</a> to an object

  4109.       defined elsewhere. Only yields reasonable results for references

  4110.       to <a href="#path">PATH like structures</a> or properties.</td>

  4111.   </tr>

  4112.   <tr>

  4113.     <td valign="top">resource</td>

  4114.     <td valign="top">the resource name of the property file.</td>

  4115.   </tr>

  4116.   <tr>

  4117.     <td valign="top">file</td>

  4118.     <td valign="top">the filename of the property file .</td>

  4119.   </tr>

  4120.   <tr>

  4121.     <td valign="top">location</td>

  4122.     <td valign="top">Sets the property to the absolute filename of the

  4123.       given file. If the value of this attribute is an absolute path, it

  4124.       is left unchanged (with / and \ characters converted to the

  4125.       current platforms conventions). Otherwise it is taken as a path

  4126.       relative to the project's basedir and expanded.</td>

  4127.   </tr>

  4128.   <tr>

  4129.     <td valign="top">classpath</td> 

  4130.     <td valign="top">the classpath to use when looking up a resource.</td>

  4131.     <td align="center" valign="top">No</td>

  4132.   </tr>

  4133.   <tr>

  4134.     <td valign="top">classpathref</td> 

  4135.     <td valign="top">the classpath to use when looking up a resource,

  4136.       given as <a href="#references">reference</a> to a PATH defined

  4137.       elsewhere..</td>

  4138.     <td align="center" valign="top">No</td>

  4139.   </tr>

  4140. </table>

  4141. <h3>Parameters specified as nested elements</h3>

  4142. <h4>classpath</h4>

  4143. <p><code>Property</code>'s <i>classpath</i> attribute is a <a

  4144. href="#path">PATH like structure</a> and can also be set via a nested

  4145. <i>classpath</i> element.</p>

  4146. <h3>Examples</h3>

  4147. <pre>  &lt;property name=&quot;foo.dist&quot; value=&quot;dist&quot;/&gt;</pre>

  4148. <p>sets the property <code>foo.dist</code> to the value &quot;dist&quot;.</p>

  4149. <pre>  &lt;property file=&quot;foo.properties&quot;/&gt;</pre>

  4150. <p>reads a set of properties from a file called &quot;foo.properties&quot;.</p>

  4151. <pre>  &lt;property resource=&quot;foo.properties&quot;/&gt;</pre>

  4152. <p>reads a set of properties from a resource called &quot;foo.properties&quot;.</p>

  4153. <p>Note that you can reference a global properties file for all of your Ant

  4154. builds using the following:

  4155. <pre>  &lt;property file=&quot;${user.home}/.ant-global.properties&quot;/&gt;</pre>

  4156. <p>since the &quot;user.home&quot; property is defined by the Java virtual machine

  4157. to be your home directory.  This technique is more appropriate for Unix than 

  4158. Windows since the notion of a home directory doesn't exist on Windows.  On the

  4159. JVM that I tested, the home directory on Windows is &quot;C:\&quot;.  Different JVM

  4160. implementations may use other values for the home directory on Windows.</p>

  4161. <hr>

  4162. <h2><a name="rename">Rename</a></h2>

  4163. <h3><i>Deprecated</i></h3>

  4164. <p><i>This task has been deprecated.  Use the Move task instead.</i></p>

  4165. <h3>Description</h3>

  4166. <p>Renames a given file.</p>

  4167. <h3>Parameters</h3>

  4168. <table border="1" cellpadding="2" cellspacing="0">

  4169.   <tr>

  4170.     <td valign="top"><b>Attribute</b></td>

  4171.     <td valign="top"><b>Description</b></td>

  4172.     <td align="center" valign="top"><b>Required</b></td>

  4173.   </tr>

  4174.   <tr>

  4175.     <td valign="top">src</td>

  4176.     <td valign="top">file to rename.</td>

  4177.     <td valign="top" align="center">Yes</td>

  4178.   </tr>

  4179.   <tr>

  4180.     <td valign="top">dest</td>

  4181.     <td valign="top">new name of the file.</td>

  4182.     <td valign="top" align="center">Yes</td>

  4183.   </tr>

  4184.   <tr>

  4185.     <td valign="top">replace</td>

  4186.     <td valign="top">Enable replacing of existing file (default: on).</td>

  4187.     <td valign="top" align="center">No</td>

  4188.   </tr>

  4189. </table>

  4190. <h3>Examples</h3>

  4191. <pre>  &lt;rename src=&quot;foo.jar&quot; dest=&quot;${name}-${version}.jar&quot;/&gt;</pre> 

  4192. <p>Renames the file <code>foo.jar</code> to <code>${name}-${version}.jar</code> (assuming <code>name</code>

  4193.  and <code>version</code> being predefined properties). If a file named <code>${name}-${version}.jar</code>

  4194.  already exists, it will be removed prior to renaming <code>foo.jar</code>.</p>

  4195. <hr>

  4196. <h2><a name="replace">Replace</a></h2>

  4197. <h3>Description</h3>

  4198. <p>Replace is a directory based task for replacing the occurrence of a given string with another string 

  4199. in selected file.</p>

  4200. <p>If you want to replace a text that crosses line boundaries, you

  4201. must use a nested <code>&lt;replacetoken&gt;</code> element.</p>

  4202. <h3>Parameters</h3>

  4203. <table border="1" cellpadding="2" cellspacing="0">

  4204.   <tr>

  4205.     <td valign="top"><b>Attribute</b></td>

  4206.     <td valign="top"><b>Description</b></td>

  4207.     <td align="center" valign="top"><b>Required</b></td>

  4208.   </tr>

  4209.   <tr>

  4210.     <td valign="top">file</td>

  4211.     <td valign="top">file for which the token should be replaced.</td>

  4212.     <td align="center" rowspan="2">Exactly one of the two.</td>

  4213.   </tr>

  4214.   <tr>

  4215.     <td valign="top">dir</td>

  4216.     <td valign="top">The base directory to use when replacing a token in 

  4217.       multiple files.</td>

  4218.   </tr>

  4219.   <tr>

  4220.     <td valign="top">token</td>

  4221.     <td valign="top">the token which must be replaced.</td>

  4222.     <td valign="top" align="center">Yes, unless a nested <code>replacetoken</code>

  4223.       element is used.</td>

  4224.   </tr>

  4225.   <tr>

  4226.     <td valign="top">value</td>

  4227.     <td valign="top">the new value for the token. When omitted, an empty string

  4228.       (&quot;&quot;) is used.</td>

  4229.     <td valign="top" align="center">No</td>

  4230.   </tr>

  4231.   <tr>

  4232.     <td valign="top">includes</td>

  4233.     <td valign="top">comma separated list of patterns of files that must be

  4234.       included. All files are included when omitted.</td>

  4235.     <td valign="top" align="center">No</td>

  4236.   </tr>

  4237.   <tr>

  4238.     <td valign="top">includesfile</td>

  4239.     <td valign="top">the name of a file. Each line of this file is

  4240.       taken to be an include pattern</td>

  4241.     <td valign="top" align="center">No</td>

  4242.   </tr>

  4243.   <tr>

  4244.     <td valign="top">excludes</td>

  4245.     <td valign="top">comma separated list of patterns of files that must be

  4246.       excluded. No files (except default excludes) are excluded when omitted.</td>

  4247.     <td valign="top" align="center">No</td>

  4248.   </tr>

  4249.   <tr>

  4250.     <td valign="top">excludesfile</td>

  4251.     <td valign="top">the name of a file. Each line of this file is

  4252.       taken to be an exclude pattern</td>

  4253.     <td valign="top" align="center">No</td>

  4254.   </tr>

  4255.   <tr>

  4256.     <td valign="top">defaultexcludes</td>

  4257.     <td valign="top">indicates whether default excludes should be used or not

  4258.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  4259.     <td valign="top" align="center">No</td>

  4260.   </tr>

  4261. </table>

  4262. <h3>Examples</h3>

  4263. <pre>  &lt;replace file=&quot;${src}/index.html&quot; token=&quot;@@@&quot; value=&quot;wombat&quot;/&gt;</pre>

  4264. <p>replaces occurrences of the string &quot;@@@&quot; with the string

  4265. &quot;wombat&quot;, in the file <code>${src}/index.html</code>.</p>

  4266. <h3>Parameters specified as nested elements</h3>

  4267. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  4268. supports all attributes of <code>&lt;fileset&gt;</code> as well as the

  4269. nested <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  4270. <code>&lt;patternset&gt;</code> elements.</p>

  4271. <p>If either the text you want to replace or the replacement text

  4272. cross line boundaries, you can use nested elements to specify

  4273. them.</p>

  4274. <h3>Examples</h3>

  4275. <blockquote><pre>  

  4276. &lt;replace dir=&quot;${src}&quot; value=&quot;wombat&quot;&gt;

  4277.   &lt;include name=&quot;**/*.html&quot;/&gt;

  4278.   &lt;replacetoken&gt;&lt;![CDATA[multi line

  4279. token]]>&lt;/replacetoken&gt;

  4280. &lt;/replace&gt;

  4281. </pre></blockquote>

  4282. <p>replaces occurrences of the string &quot;multi

  4283. line<i>\n</i>token&quot; with the string &quot;wombat&quot;, in all

  4284. HTML files in the directory <code>${src}</code>.Where <i>\n</i> is

  4285. the platform specific line separator.</p>

  4286. <blockquote><pre>  

  4287. &lt;replace file=&quot;${src}/index.html&quot;&gt;

  4288.   &lt;replacetoken&gt;&lt;![CDATA[two line

  4289. token]]>&lt;/replacetoken&gt;

  4290.   &lt;replacevalue&gt;&lt;![CDATA[two line

  4291. token]]>&lt;/replacevalue&gt;

  4292. &lt;/replace&gt;

  4293. </pre></blockquote>

  4294. <hr>

  4295. <h2><a name="rmic">Rmic</a></h2>

  4296. <h3>Description</h3>

  4297. <p>Runs the rmic compiler for a certain class.</p>

  4298. <p>Rmic can be run on a single class (as specified with the classname

  4299. attribute) or a number of classes at once (all classes below base that

  4300. are neither _Stub nor _Skel classes).</p>

  4301. <p>It is possible to refine the set of files that are being rmiced. This can be

  4302. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  4303. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  4304. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  4305. the files you want to have excluded. This is also done with patterns. And

  4306. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  4307. want to use default exclusions or not. See the section on <a

  4308. href="#directorybasedtasks">directory based tasks</a>, on how the

  4309. inclusion/exclusion of files works, and how to write patterns.</p>

  4310. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  4311. supports all attributes of <code>&lt;fileset&gt;</code>

  4312. (<code>dir</code> becomes <code>base</code>) as well as the nested

  4313. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  4314. <code>&lt;patternset&gt;</code> elements.</p>

  4315. <h3>Parameters</h3>

  4316. <table border="1" cellpadding="2" cellspacing="0">

  4317.   <tr>

  4318.     <td valign="top"><b>Attribute</b></td>

  4319.     <td valign="top"><b>Description</b></td>

  4320.     <td align="center" valign="top"><b>Required</b></td>

  4321.   </tr>

  4322.   <tr>

  4323.     <td valign="top">base</td>

  4324.     <td valign="top">the location to store the compiled files.</td>

  4325.     <td valign="top" align="center">Yes</td>

  4326.   </tr>

  4327.   <tr>

  4328.     <td valign="top">classname</td>

  4329.     <td valign="top">the class for which to run <code>rmic</code>.</td>

  4330.     <td valign="top" align="center">No</td>

  4331.   </tr>

  4332.   <tr>

  4333.     <td valign="top">filtering</td>

  4334.     <td valign="top">indicates whether token filtering should take place</td>

  4335.     <td valign="top" align="center">No</td>

  4336.   </tr>

  4337.   <tr>

  4338.     <td valign="top">sourcebase</td>

  4339.     <td valign="top">Pass the &quot;-keepgenerated&quot; flag to rmic and

  4340.  move the generated source file to the base directory.</td>

  4341.     <td align="center" valign="top">No</td>

  4342.   </tr>

  4343.   <tr>

  4344.     <td valign="top">stubversion</td>

  4345.     <td valign="top">Specify the JDK version for the generated stub code.

  4346.  Specify &quot;1.1&quot; to pass the &quot;-v1.1&quot; option to rmic.</td>

  4347.     <td align="center" valign="top">No</td>

  4348.   </tr>

  4349.   <tr>

  4350.     <td valign="top">classpath</td>

  4351.     <td valign="top">The classpath to use during compilation</td>

  4352.     <td align="center" valign="top">No</td>

  4353.   </tr>

  4354.   <tr>

  4355.     <td valign="top">classpathref</td>

  4356.     <td valign="top">The classpath to use during compilation, given as <a

  4357.       href="#references">reference</a> to a PATH defined elsewhere</td>

  4358.     <td align="center" valign="top">No</td>

  4359.   </tr>

  4360.   <tr>

  4361.     <td valign="top">includes</td>

  4362.     <td valign="top">comma separated list of patterns of files that must be

  4363.       included. All files are included when omitted.</td>

  4364.     <td valign="top" align="center">No</td>

  4365.   </tr>

  4366.   <tr>

  4367.     <td valign="top">includesfile</td>

  4368.     <td valign="top">the name of a file. Each line of this file is

  4369.       taken to be an include pattern</td>

  4370.     <td valign="top" align="center">No</td>

  4371.   </tr>

  4372.   <tr>

  4373.     <td valign="top">excludes</td>

  4374.     <td valign="top">comma separated list of patterns of files that must be

  4375.       excluded. No files (except default excludes) are excluded when omitted.</td>

  4376.     <td valign="top" align="center">No</td>

  4377.   </tr>

  4378.   <tr>

  4379.     <td valign="top">excludesfile</td>

  4380.     <td valign="top">the name of a file. Each line of this file is

  4381.       taken to be an exclude pattern</td>

  4382.     <td valign="top" align="center">No</td>

  4383.   </tr>

  4384.   <tr>

  4385.     <td valign="top">defaultexcludes</td>

  4386.     <td valign="top">indicates whether default excludes should be used or not

  4387.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  4388.     <td valign="top" align="center">No</td>

  4389.   </tr>

  4390.   <tr>

  4391.     <td valign="top">verify</td>

  4392.     <td valign="top">check that classes implement Remote before handing them 

  4393.         to rmic (default is false)</td>

  4394.     <td align="center" valign="top">No</td>

  4395.   </tr>

  4396.   <tr>

  4397.     <td valign="top">iiop</td>

  4398.     <td valign="top">indates that portable (RMI/IIOP) stubs should be generated</td>

  4399.     <td align="center" valign="top">No</td>

  4400.   </tr>

  4401.   <tr>

  4402.     <td valign="top">iiopopts</td>

  4403.     <td valign="top">additional arguments for IIOP class generation</td>

  4404.     <td align="center" valign="top">No</td>

  4405.   </tr>

  4406.   <tr>

  4407.     <td valign="top">idl</td>

  4408.     <td valign="top">indates that IDL output files should be generated</td>

  4409.     <td align="center" valign="top">No</td>

  4410.   </tr>

  4411.   <tr>

  4412.     <td valign="top">idlopts</td>

  4413.     <td valign="top">additional arguments for IDL file generation</td>

  4414.     <td align="center" valign="top">No</td>

  4415.   </tr>

  4416. </table>

  4417. <h3>Parameters specified as nested elements</h3>

  4418. <h4>classpath</h4>

  4419. <p><code>Rmic</code>'s <i>classpath</i> attribute is a <a

  4420. href="#path">PATH like structure</a> and can also be set via a nested

  4421. <i>classpath</i> elements.</p>

  4422. <h3>Examples</h3>

  4423. <pre>  &lt;rmic classname=&quot;com.xyz.FooBar&quot; base=&quot;${build}/classes&quot;/&gt;</pre>

  4424. <p>runs the rmic compiler for the class <code>com.xyz.FooBar</code>. The

  4425. compiled files will be stored in the directory <code>${build}/classes</code>.</p>

  4426. <pre>  &lt;rmic base=&quot;${build}/classes&quot; includes=&quot;**/Remote*.class&quot;/&gt;</pre>

  4427. <p>runs the rmic compiler for all classes with <code>.class</code>

  4428. files below <code>${build}/classes</code> whose classname starts with

  4429. <i>Remote</i>. The compiled files will be stored in the directory

  4430. <code>${build}/classes</code>.</p>

  4431. 

  4432. <hr>

  4433. <h2><a name="signjar">SignJar</a></h2>

  4434. <h3>Description</h3>

  4435. <p>Signs a jar or zip file with the javasign command line tool.</p>

  4436. 

  4437. <h3>Parameters</h3>

  4438. <table border="1" cellpadding="2" cellspacing="0">

  4439.   <tr>

  4440.     <td valign="top"><b>Attribute</b></td>

  4441.     <td valign="top"><b>Description</b></td>

  4442.     <td align="center" valign="top"><b>Required</b></td>

  4443.   </tr>

  4444.   <tr>

  4445.     <td valign="top">jar</td>

  4446.     <td valign="top">the jar file to sign</td>

  4447.     <td valign="top" align="center">Yes.</td>

  4448.   </tr>

  4449.   <tr>

  4450.     <td valign="top">alias</td>

  4451.     <td valign="top">the alias to sign under</td>

  4452.     <td valign="top" align="center">Yes.</td>

  4453.   </tr>

  4454.   <tr>

  4455.     <td valign="top">storepass</td>

  4456.     <td valign="top">password for keystore integrity.</td>

  4457.     <td valign="top" align="center">Yes.</td>

  4458.   </tr>

  4459.   <tr>

  4460.     <td valign="top">keystore</td>

  4461.     <td valign="top">keystore location</td>

  4462.     <td valign="top" align="center">No</td>

  4463.   </tr>

  4464.   <tr>

  4465.     <td valign="top">storetype</td>

  4466.     <td valign="top">keystore type</td>

  4467.     <td valign="top" align="center">No</td>

  4468.   </tr>

  4469.   <tr>

  4470.     <td valign="top">keypass</td>

  4471.     <td valign="top">password for private key (if different)</td>

  4472.     <td valign="top" align="center">No</td>

  4473.   </tr>

  4474.   <tr>

  4475.     <td valign="top">sigfile</td>

  4476.     <td valign="top">name of .SF/.DSA file</td>

  4477.     <td valign="top" align="center">No</td>

  4478.   </tr>

  4479.   <tr>

  4480.     <td valign="top">signedjar</td>

  4481.     <td valign="top">name of signed JAR file</td>

  4482.     <td valign="top" align="center">No</td>

  4483.   </tr>

  4484.   <tr>

  4485.     <td valign="top">verbose</td>

  4486.     <td valign="top">(true | false) verbose output when signing</td>

  4487.     <td valign="top" align="center">No</td>

  4488.   </tr>

  4489.   <tr>

  4490.     <td valign="top">internalsf</td>

  4491.     <td valign="top">(true | false) include the .SF file inside the signature

  4492. block</td>

  4493.     <td valign="top" align="center">No</td>

  4494.   </tr>

  4495.   <tr>

  4496.     <td valign="top">sectionsonly</td>

  4497.     <td valign="top">(true | false) don't compute hash of entire manifest</td>

  4498.     <td valign="top" align="center">No</td>

  4499.   </tr>

  4500. </table>

  4501. <h3>Examples</h3>

  4502. <blockquote>

  4503.   <p><code>&lt;signjar jar=&quot;${dist}/lib/ant.jar&quot;

  4504. alias=&quot;apache-group&quot; storepass=&quot;secret&quot;/&gt;</code></p>

  4505. </blockquote>

  4506. <p>signs the ant.jar with alias &quot;apache-group&quot; accessing the

  4507. keystore and private key via &quot;secret&quot; password.</p>

  4508. <hr>

  4509. <h2><a name="style">Style</a></h2>

  4510. <h3>Description</h3>

  4511. <p>Process a set of documents via XSLT.</p>

  4512. <p>This is useful for building views of XML based documentation,

  4513. or in generating code.</p>

  4514. <p>It is possible to refine the set of files that are being copied. This can be

  4515. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  4516. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  4517. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  4518. the files you want to have excluded. This is also done with patterns. And

  4519. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  4520. want to use default exclusions or not. See the section on <a

  4521. href="#directorybasedtasks">directory based tasks</a>, on how the

  4522. inclusion/exclusion of files works, and how to write patterns.</p>

  4523. <p>This task forms an implicit <a href="#fileset">FileSet</a> and supports all 

  4524.   attributes of <code>&lt;fileset&gt;</code> (<code>dir</code> becomes <code>basedir</code>) 

  4525.   as well as the nested <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> 

  4526.   and <code>&lt;patternset&gt;</code> elements.</p>

  4527. <p>Style supports the use of a &lt;param&gt; element which is use to pass values 

  4528.   to an &lt;xsl:param&gt; declaration.</p>

  4529. <h3>Parameters</h3>

  4530. <table border="1" cellpadding="2" cellspacing="0">

  4531.   <tr>

  4532.     <td valign="top"><b>Attribute</b></td>

  4533.     <td valign="top"><b>Description</b></td>

  4534.     <td align="center" valign="top"><b>Required</b></td>

  4535.   </tr>

  4536.   <tr>

  4537.     <td valign="top">basedir</td>

  4538.     <td valign="top">where to find the source xml file.</td>

  4539.     <td align="center" valign="top">Yes</td>

  4540.   </tr>

  4541.   <tr>

  4542.     <td valign="top">destdir</td>

  4543.     <td valign="top">directory where to store the results.</td>

  4544.     <td align="center" valign="top">Yes</td>

  4545.   </tr>

  4546.   <tr>

  4547.     <td valign="top">extension</td>

  4548.     <td valign="top">desired file extension to be used for the targets. If not 

  4549.       specified, the default is &quot;html&quot;.</td>

  4550.     <td align="center" valign="top">No</td>

  4551.   </tr>

  4552.   <tr>

  4553.     <td valign="top">style</td>

  4554.     <td valign="top">name of the stylesheet to use.</td>

  4555.     <td align="center" valign="top">Yes</td>

  4556.   </tr>

  4557.   <tr>

  4558.     <td valign="top">processor</td>

  4559.     <td valign="top">name of the XSLT processor to use.  Permissible values are

  4560.       &quot;trax&quot; for a TraX compliant processor, &quot;xslp&quot; for the 

  4561.       XSL:P processor, &quot;xalan&quot; for the Apache XML Xalan (version 1) 

  4562.       processor, or the name of an arbitrary XSLTLiaison class. Defaults to trax, 

  4563.       followed by xslp then xalan (in that order). The first one found in your 

  4564.       class path is the one that is used.</td>

  4565.     <td align="center" valign="top">No</td>

  4566.   </tr>

  4567.   <tr>

  4568.     <td valign="top">includes</td>

  4569.     <td valign="top">comma separated list of patterns of files that must be included. 

  4570.       All files are included when omitted.</td>

  4571.     <td valign="top" align="center">No</td>

  4572.   </tr>

  4573.   <tr>

  4574.     <td valign="top">includesfile</td>

  4575.     <td valign="top">the name of a file. Each line of this file is taken to be 

  4576.       an include pattern</td>

  4577.     <td valign="top" align="center">No</td>

  4578.   </tr>

  4579.   <tr>

  4580.     <td valign="top">excludes</td>

  4581.     <td valign="top">comma separated list of patterns of files that must be excluded. 

  4582.       No files (except default excludes) are excluded when omitted.</td>

  4583.     <td valign="top" align="center">No</td>

  4584.   </tr>

  4585.   <tr>

  4586.     <td valign="top">excludesfile</td>

  4587.     <td valign="top">the name of a file. Each line of this file is taken to be 

  4588.       an exclude pattern</td>

  4589.     <td valign="top" align="center">No</td>

  4590.   </tr>

  4591.   <tr>

  4592.     <td valign="top">defaultexcludes</td>

  4593.     <td valign="top">indicates whether default excludes should be used or not

  4594.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  4595.     <td valign="top" align="center">No</td>

  4596.   </tr>

  4597.   <tr>

  4598.     <td valign="top">in</td>

  4599.     <td valign="top">specifies a single XML document to be styled. Should be used 

  4600.       with the out attribute.</td>

  4601.     <td valign="top" align="center">No</td>

  4602.   </tr>

  4603.   <tr>

  4604.     <td valign="top">out</td>

  4605.     <td valign="top">specifies the output name for the sytled result from the 

  4606.       in attribute.</td>

  4607.     <td valign="top" align="center">No</td>

  4608.   </tr>

  4609. </table>

  4610. <h3>Parameters specified as nested elements</h3>

  4611. <h4>param</h4>

  4612. <p>Param is used to pass a parameter to the XSL stylesheet.</p>

  4613. <h4>Parameters</h4>

  4614. <table width="60%" border="1" cellpadding="2" cellspacing="0">

  4615.   <tr> 

  4616.     <td valign="top"><b>Attribute</b></td>

  4617.     <td valign="top"><b>Description</b></td>

  4618.     <td align="center" valign="top"><b>Required</b></td>

  4619.   </tr>

  4620.   <tr> 

  4621.     <td valign="top">name</td>

  4622.     <td valign="top">Name of the XSL parameter</td>

  4623.     <td align="center" valign="top">Yes</td>

  4624.   </tr>

  4625.   <tr> 

  4626.     <td valign="top">expression</td>

  4627.     <td valign="top">XSL expression to be placed into the param. To pass a text 

  4628.       value into the style sheet it needs to be escaped using single quotes.</td>

  4629.     <td align="center" valign="top">Yes</td>

  4630.   </tr>

  4631. </table>

  4632. <h3>Examples</h3>

  4633. <blockquote>

  4634.   <p>

  4635.   <pre>

  4636. &lt;style basedir=&quot;doc&quot; destdir=&quot;build/doc&quot;

  4637.        extension=&quot;html&quot; style=&quot;style/apache.xsl&quot;/&gt;</pre>

  4638.   <h4><br>

  4639.     Using XSL parameters<br>

  4640.   </h4>

  4641.   <pre>&lt;style basedir=&quot;doc&quot; destdir=&quot;build/doc&quot;

  4642. 		extension=&quot;html&quot; style=&quot;style/apache.xsl&quot;&gt;

  4643. 	&lt;param name=&quot;date&quot; expression=&quot;'07-01-2000'&quot;/&gt;

  4644. &lt;/style&gt;</pre>

  4645.   <p>This will replace an xsl:param definition&lt;xsl:param name="date"&gt;&lt;/xsl:param&gt; 

  4646.     with the text value 07-01-2000 </p>

  4647.   </blockquote>

  4648. <hr>

  4649. <h2><a name="tar">Tar</a></h2>

  4650. <h3>Description</h3>

  4651. <p>Creates a tar archive.</p>

  4652. <p>The <i>basedir</i> attribute is the reference directory from where to tar.</p>

  4653. <p>It is possible to refine the set of files that are being tarred. This can be

  4654. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  4655. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  4656. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  4657. the files you want to have excluded. This is also done with patterns. And

  4658. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  4659. want to use default exclusions or not. See the section on <a

  4660. href="#directorybasedtasks">directory based tasks</a>, on how the

  4661. inclusion/exclusion of files works, and how to write patterns.</p>

  4662. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  4663. supports all attributes of <code>&lt;fileset&gt;</code>

  4664. (<code>dir</code> becomes <code>basedir</code>) as well as the nested

  4665. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  4666. <code>&lt;patternset&gt;</code> elements.</p>

  4667. <p>Note that this task does not perform compression. You might want to use the <a href="#gzip">GZip</a>

  4668. task to come up with a .tar.gz package.</p>

  4669. <h3>Parameters</h3>

  4670. <table border="1" cellpadding="2" cellspacing="0">

  4671.   <tr>

  4672.     <td valign="top"><b>Attribute</b></td>

  4673.     <td valign="top"><b>Description</b></td>

  4674.     <td valign="top" align="center"><b>Required</b></td>

  4675.   </tr>

  4676.   <tr>

  4677.     <td valign="top">tarfile</td>

  4678.     <td valign="top">the tar-file to create.</td>

  4679.     <td align="center" valign="top">Yes</td>

  4680.   </tr>

  4681.   <tr>

  4682.     <td valign="top">basedir</td>

  4683.     <td valign="top">the directory from which to zip the files.</td>

  4684.     <td align="center" valign="top">Yes</td>

  4685.   </tr>

  4686.   <tr>

  4687.     <td valign="top">includes</td>

  4688.     <td valign="top">comma separated list of patterns of files that must be

  4689.       included. All files are included when omitted.</td>

  4690.     <td valign="top" align="center">No</td>

  4691.   </tr>

  4692.   <tr>

  4693.     <td valign="top">includesfile</td>

  4694.     <td valign="top">the name of a file. Each line of this file is

  4695.       taken to be an include pattern</td>

  4696.     <td valign="top" align="center">No</td>

  4697.   </tr>

  4698.   <tr>

  4699.     <td valign="top">excludes</td>

  4700.     <td valign="top">comma separated list of patterns of files that must be

  4701.       excluded. No files (except default excludes) are excluded when omitted.</td>

  4702.     <td valign="top" align="center">No</td>

  4703.   </tr>

  4704.   <tr>

  4705.     <td valign="top">excludesfile</td>

  4706.     <td valign="top">the name of a file. Each line of this file is

  4707.       taken to be an exclude pattern</td>

  4708.     <td valign="top" align="center">No</td>

  4709.   </tr>

  4710.   <tr>

  4711.     <td valign="top">defaultexcludes</td>

  4712.     <td valign="top">indicates whether default excludes should be used or not

  4713.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  4714.     <td valign="top" align="center">No</td>

  4715.   </tr>

  4716. </table>

  4717. <h3>Examples</h3>

  4718. <pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot; basedir=&quot;htdocs/manual&quot;/&gt;

  4719.   &lt;gzip zipfile=&quot;${dist}/manual.tar.gz&quot; src=&quot;${dist}/manual.tar&quot;/&gt;</pre>

  4720. <p>tars all files in the <code>htdocs/manual</code> directory into a file called <code>manual.tar</code>

  4721. in the <code>${dist}</code>  directory, then applies the gzip task to compress

  4722. it.</p>

  4723. <pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot;

  4724.        basedir=&quot;htdocs/manual&quot;

  4725.        excludes=&quot;mydocs/**, **/todo.html&quot;

  4726.   /&gt;</pre>

  4727. <p>tars all files in the <code>htdocs/manual</code> directory into a file called <code>manual.tar</code>

  4728. in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,

  4729. or files with the name <code>todo.html</code> are excluded.</p>

  4730. <hr>

  4731. <h2><a name="taskdef">Taskdef</a></h2>

  4732. <h3>Description</h3>

  4733. <p>Adds a task definition to the current project, such that this new task can be

  4734. used in the current project. Two attributes are needed, the name that identifies

  4735. this task uniquely, and the full name of the class (including the packages) that

  4736. implements this task.</p>

  4737. <p>Taskdef should be used to add your own tasks to the system. See also &quot;<a

  4738. href="#writingowntask">Writing your own task</a>&quot;.</p>

  4739. <h3>Parameters</h3>

  4740. <table border="1" cellpadding="2" cellspacing="0">

  4741.   <tr>

  4742.     <td valign="top"><b>Attribute</b></td>

  4743.     <td valign="top"><b>Description</b></td>

  4744.     <td align="center" valign="top"><b>Required</b></td>

  4745.   </tr>

  4746.   <tr>

  4747.     <td valign="top">name</td>

  4748.     <td valign="top">the name of the task</td>

  4749.     <td valign="top" align="center">Yes</td>

  4750.   </tr>

  4751.   <tr>

  4752.     <td valign="top">classname</td>

  4753.     <td valign="top">the full class name implementing the task</td>

  4754.     <td valign="top" align="center">Yes</td>

  4755.   </tr>

  4756.   <tr>

  4757.     <td valign="top">classpath</td> <td valign="top">the classpath to

  4758.       use when looking up <code>classname</code>.</td> <td

  4759.     align="center" valign="top">No</td>

  4760.   </tr>

  4761. </table>

  4762. <h3>Parameters specified as nested elements</h3>

  4763. <h4>classpath</h4>

  4764. <p><code>Taskdef</code>'s <i>classpath</i> attribute is a <a

  4765. href="#path">PATH like structure</a> and can also be set via a nested

  4766. <i>classpath</i> element.</p>

  4767. <h3>Examples</h3>

  4768. <pre>  &lt;taskdef name=&quot;myjavadoc&quot; classname=&quot;com.mydomain.JavadocTask&quot;/&gt;</pre>

  4769. <p>makes a task called <code>myjavadoc</code> available to Ant. The class <code>com.mydomain.JavadocTask</code>

  4770. implements the task.</p>

  4771. <hr>

  4772. <h2><a name="touch">Touch</a></h2>

  4773. <h3>Description</h3>

  4774. <p>Changes the modification time of a file and possibly creates it at

  4775. the same time.</p>

  4776. <p>For JDK 1.1 only the creation of new files with a modification time

  4777. of now works, all other cases will emit a warning.</p>

  4778. <h3>Parameters</h3>

  4779. <table border="1" cellpadding="2" cellspacing="0">

  4780.   <tr>

  4781.     <td valign="top"><b>Attribute</b></td>

  4782.     <td valign="top"><b>Description</b></td>

  4783.     <td align="center" valign="top"><b>Required</b></td>

  4784.   </tr>

  4785.   <tr>

  4786.     <td valign="top">file</td>

  4787.     <td valign="top">the name of the file</td>

  4788.     <td valign="top" align="center">Yes</td>

  4789.   </tr>

  4790.   <tr>

  4791.     <td valign="top">millis</td>

  4792.     <td valign="top">specifies the new modification time of the file

  4793.        in milliseconds since midnight Jan 1 1970</td>

  4794.     <td valign="top" align="center">No</td>

  4795.   </tr>

  4796.   <tr>

  4797.     <td valign="top">datetime</td>

  4798.     <td valign="top">specifies the new modification time of the file

  4799.        in the format MM/DD/YYYY HH:MM AM_or_PM.</td>

  4800.     <td valign="top" align="center">No</td>

  4801.   </tr>

  4802. </table>

  4803. <p>If both <code>millis</code> and <code>datetime</code> are omitted

  4804. the current time is assumed.</p>

  4805. <h3>Examples</h3>

  4806. <pre>  &lt;touch file=&quot;myfile&quot;/&gt;</pre>

  4807. <p>creates <code>myfile</code> if it doesn't exist and changes the

  4808. modification time to the current time.</p>

  4809. <pre>  &lt;touch file=&quot;myfile&quot; datetime=&quot;06/28/2000 2:02 pm&quot;/&gt;</pre>

  4810. <p>creates <code>myfile</code> if it doesn't exist and changes the

  4811. modification time to Jun, 28 2000 2:02 pm (14:02 for those used to 24

  4812. hour times).</p>

  4813. <hr>

  4814. <h2><a name="transform">Transform</a></h2>

  4815. <h3>Description</h3>

  4816. <p>Executes a system command. When the <i>os</i> attribute is specified, then

  4817. the command is only executed when Ant is run on one of the specified operating

  4818. systems.</p>

  4819. <p>The files and/or directories of a number of <a

  4820. href="#fileset">FileSet</a>s are passed as arguments to the system

  4821. command. The timestamp of each source file is compared to the

  4822. timestamp of a target file which is defined by a nested <a

  4823. href="#mapper">mapper</a> element. At least one fileset and exactly

  4824. one mapper element are required.</p>

  4825. <h3>Parameters</h3>

  4826. <table border="1" cellpadding="2" cellspacing="0">

  4827.   <tr>

  4828.     <td valign="top"><b>Attribute</b></td>

  4829.     <td valign="top"><b>Description</b></td>

  4830.     <td align="center" valign="top"><b>Required</b></td>

  4831.   </tr>

  4832.   <tr>

  4833.     <td valign="top">executable</td>

  4834.     <td valign="top">the command to execute without any command line

  4835.       arguments.</td>

  4836.     <td align="center" valign="top">Yes</td>

  4837.   </tr>

  4838.   <tr>

  4839.     <td valign="top">dest</td>

  4840.     <td valign="top">the directory where the target files will be placed.</td>

  4841.     <td align="center" valign="top">Yes</td>

  4842.   </tr>

  4843.   <tr>

  4844.     <td valign="top">dir</td>

  4845.     <td valign="top">the directory in which the command should be executed.</td>

  4846.     <td align="center" valign="top">No</td>

  4847.   </tr>

  4848.   <tr>

  4849.     <td valign="top">os</td>

  4850.     <td valign="top">list of Operating Systems on which the command may be

  4851.       executed.</td>

  4852.     <td align="center" valign="top">No</td>

  4853.   </tr>

  4854.   <tr>

  4855.     <td valign="top">output</td>

  4856.     <td valign="top">the file to which the output of the command should be

  4857.       redirected.</td>

  4858.     <td align="center" valign="top">No</td>

  4859.   </tr>

  4860.   <tr>

  4861.     <td valign="top">timeout</td>

  4862.     <td valign="top">Stop the command if it doesn't finish within the

  4863.       specified time (given in milliseconds).</td>

  4864.     <td align="center" valign="top">No</td>

  4865.   </tr>

  4866.   <tr>

  4867.     <td valign="top">failonerror</td>

  4868.     <td valign="top">Stop the buildprocess if the command exits with a

  4869.       returncode other than 0.</td>

  4870.     <td align="center" valign="top">No</td>

  4871.   </tr>

  4872.   <tr>

  4873.     <td valign="top">parallel</td>

  4874.     <td valign="top">Run the command only once, appending all files as

  4875.       arguments. Defaults to true. If false, command will be executed

  4876.       once for every file.</td>

  4877.     <td align="center" valign="top">No</td>

  4878.   </tr>

  4879.   <tr>

  4880.     <td valign="top">type</td>

  4881.     <td valign="top">One of <i>file</i>, <i>dir</i> or

  4882.       <i>both</i>. If set to <i>file</i>, only the names of plain

  4883.       files will be sent to the command. If set to <i>dir</i>, only

  4884.       the names of directories are considered.</td>

  4885.     <td align="center" valign="top">No, default is <i>file</i></td>

  4886.   </tr>

  4887. </table>

  4888. <h3>Parameters specified as nested elements</h3>

  4889. <h4>fileset</h4>

  4890. <p>You can use any number of nested <code>&lt;fileset&gt;</code>

  4891. elements to define the files for this task and refer to

  4892. <code>&lt;fileset&gt;</code>s defined elsewhere.</p>

  4893. <h4>arg</h4>

  4894. <p>Command line arguments should be specified as nested

  4895. <code>&lt;arg&gt;</code> elements. See <a

  4896. href="index.html#arg">Command line arguments</a>.</p>

  4897. <h4>srcfile</h4>

  4898. <p>By default the file names of the source files will be added to the

  4899. end of the command line. If you need to place it somewhere different,

  4900. use a nested <code>&lt;srcfile&gt;</code> element between your

  4901. <code>&lt;arg&gt;</code> elements to mark the insertion point.</code>

  4902. <h4>targetfile</h4>

  4903. <p><code>&lt;targetfile&gt;</code> is similar to

  4904. <code>&lt;srcfile&gt;</code> and marks the position of the target

  4905. filename on the command line. If omitted, the target filenames will

  4906. not be added to the command line at all.</p>

  4907. <h4>env</h4>

  4908. <p>It is possible to specify environment variables to pass to the

  4909. system command via nested <code>&lt;env&gt;</code> elements. See the

  4910. description in the section about <a href="#env">exec</a></p>

  4911. <p>Please note that the environment of the current Ant process is

  4912. <b>not</b> passed to the system command if you specify variables using

  4913. <code>&lt;env&gt;</code>.</p>

  4914. <h3>Examples</h3>

  4915. <blockquote><pre>

  4916. &lt;transform executable=&quot;cc&quot; dest=&quot;src/C&quot; parallel=&quot;false&quot;&gt;

  4917.   &lt;arg value=&quot;-c&quot;/&gt;

  4918.   &lt;arg value=&quot;-o&quot;/&gt;

  4919.   &lt;targetfile/&gt;

  4920.   &lt;srcfile/&gt;

  4921.   &lt;fileset dir=&quot;src/C&quot; includes=&quot;*.c&quot;/&gt;

  4922.   &lt;mapper type=&quot;glob&quot; from=&quot;*.c&quot; to=&quot;*.o&quot;/&gt;

  4923. &lt;/transform&gt;

  4924. </pre></blockquote>

  4925. <p>invokes <code>cc -c -o TARGETFILE SOURCEFILE</code> for each

  4926. <code>.c</code> file that is newer than the corresponding

  4927. <code>.o</code>, replacing TARGETFILE with the absolute filename of

  4928. the <code>.o</code> and SOURCEFILE with the absolute name of the

  4929. <code>.c</code> file.</p>

  4930. <hr>

  4931. <h2><a name="tstamp">Tstamp</a></h2>

  4932. <h3>Description</h3>

  4933. <p>Sets the DSTAMP, TSTAMP and TODAY properties in the current project. The

  4934. DSTAMP is in the &quot;yyyymmdd&quot; format, the TSTAMP is in the &quot;hhmm&quot;

  4935. format and TODAY is &quot;month day year&quot;.</p>

  4936. <p>These properties can be used in the buildfile, for instance, to create

  4937. timestamped filenames or used to replace placeholder tags inside documents to

  4938. indicate, for example, the release date. The best place for this task is in your

  4939. initialization target.</p>

  4940. <h3>Parameters</h3>

  4941. <table border="1" cellpadding="2" cellspacing="0">

  4942.   <tr>

  4943.     <td valign="top"><b>Attribute</b></td>

  4944.     <td valign="top"><b>Description</b></td>

  4945.     <td align="center" valign="top"><b>Required</b></td>

  4946.   </tr>

  4947.   <tr> <td colspan="3"/> No parameters</td>

  4948.   </tr>

  4949. </table>

  4950. 

  4951. <h3>Nested Elements</h3>

  4952. The tstamp task supports a format nested element which allows a property to be

  4953. given the current date and time in a given format. The date/time patterns are as defined in the Java 

  4954. SimpleDateFormat class. 

  4955. <p>

  4956. 

  4957. <table width="60%" border="1" cellpadding="2" cellspacing="0">

  4958.   <tr>

  4959.     <td valign="top"><b>Attribute</b></td>

  4960.     <td valign="top"><b>Description</b></td>

  4961.     <td align="center" valign="top"><b>Required</b></td>

  4962.   </tr>

  4963.   <tr>

  4964.     <td valign="top">property</td>

  4965.     <td valign="top">

  4966.         The property which is to receive the date/time string in the given pattern

  4967.     </td>

  4968.     <td align="center" valign="top">Yes</td>

  4969.   </tr>

  4970.   <tr>

  4971.     <td valign="top">pattern</td>

  4972.     <td valign="top">The date/time pattern to be used. The values are defined by the Java

  4973.                      SimpleDateFormat class</td>

  4974.     <td align="center" valign="top">Yes</td>

  4975.   </tr>

  4976. </table>

  4977. 

  4978. <h3>Examples</h3>

  4979. <p> Set the standard DSTAMP, TSTAMP and TODAY properties according to the formats above

  4980. <pre>  &lt;tstamp/&gt;</pre>

  4981. 

  4982. <p> As for the above example, set the standard properties and also set the property 

  4983. &quot;TODAY_UK&quot; with the date/time pattern &quot;d MMM yyyy&quot;

  4984. 

  4985. <pre>  &lt;tstamp&gt;

  4986.     &lt;format property=&quot;TODAY_UK&quot; pattern=&quot;d MMMM yyyy&quot;&gt;

  4987.   &lt;/tstamp&gt;

  4988. </pre>

  4989. 

  4990. <hr>

  4991. <h2><a name="uptodate">Uptodate</a></h2>

  4992. <h3>Description</h3>

  4993. <p>Sets a property if a target files are more up to date than a set of

  4994. Source files. Source files are specified by nested &lt;srcfiles&gt;

  4995. elements, these are <a href="#fileset">FileSet</a>s, while target

  4996. files are specified using a nested <a href="#mapper">mapper</a>

  4997. element.</p>

  4998. <p>The value part of the property being set is <i>true</i> if the

  4999. timestamp of the target files is more recent than the timestamp of

  5000. every corresponding source file.</p>

  5001. <p>The default behavior is to use a <a href="#merge-mapper">merge

  5002. mapper</a> whith the <code>to</code> attribute set to the value of the

  5003. targetfile attribute.</p>

  5004. <p>Normally, this task is used to set properties that are useful to avoid target

  5005. execution depending on the relative age of the specified files.</p>

  5006. <h3>Parameters</h3>

  5007. <table border="1" cellpadding="2" cellspacing="0">

  5008.   <tr>

  5009.     <td valign="top"><b>Attribute</b></td>

  5010.     <td valign="top"><b>Description</b></td>

  5011.     <td align="center" valign="top"><b>Required</b></td>

  5012.   </tr>

  5013.   <tr>

  5014.     <td valign="top">property</td>

  5015.     <td valign="top">the name of the property to set.</td>

  5016.     <td valign="top" align="center">Yes</td>

  5017.   </tr>

  5018.   <tr>

  5019.     <td valign="top">targetfile</td>

  5020.     <td valign="top">the file for which we want to determine the status.</td>

  5021.     <td valign="top" align="center">Yes, unless a nested mapper element is 

  5022.       present.</td>

  5023.   </tr>

  5024. </table>

  5025. <h3>Examples</h3>

  5026. <pre>  &lt;uptodate property=&quot;xmlBuild.notRequired&quot; targetfile=&quot;${deploy}\xmlClasses.jar&quot; &gt;

  5027.     &lt;srcfiles dir= &quot;${src}/xml&quot; includes=&quot;**/*.dtd&quot;/&gt;

  5028.   &lt;/uptodate&gt;</pre>

  5029. <p>sets the property <code><i>xmlBuild.notRequired</i></code> to the value &quot;true&quot;

  5030. 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>

  5031. <p>This can be written as

  5032. <pre>  &lt;uptodate property=&quot;xmlBuild.notRequired&quot;  &gt;

  5033.     &lt;srcfiles dir= &quot;${src}/xml&quot; includes=&quot;**/*.dtd&quot;/&gt;

  5034.     &lt;mapper type=&quot;merge&quot; to=&quot;${deploy}\xmlClasses.jar&quot;/&gt;

  5035.   &lt;/uptodate&gt;</pre>

  5036. <p>as well.</p>

  5037. <hr>

  5038. <h2><a name="unzip">Unjar/Unwar/Unzip</a></h2>

  5039. <h3>Description</h3>

  5040. <p>Unzips a zip-, war- or jarfile.</p>

  5041. <p>For JDK 1.1 &quot;last modified time&quot; field is set to current time instead of being 

  5042. carried from zipfile.</p>

  5043. <p>File permissions will not be restored on extracted files.</p>

  5044. <h3>Parameters</h3>

  5045. <table border="1" cellpadding="2" cellspacing="0">

  5046.   <tr>

  5047.     <td valign="top"><b>Attribute</b></td>

  5048.     <td valign="top"><b>Description</b></td>

  5049.     <td align="center" valign="top"><b>Required</b></td>

  5050.   </tr>

  5051.   <tr>

  5052.     <td valign="top">src</td>

  5053.     <td valign="top">zipfile to expand.</td>

  5054.     <td align="center" valign="top">Yes</td>

  5055.   </tr>

  5056.   <tr>

  5057.     <td valign="top">dest</td>

  5058.     <td valign="top">directory where to store the expanded files.</td>

  5059.     <td align="center" valign="top">Yes</td>

  5060.   </tr>

  5061. </table>

  5062. <h3>Examples</h3>

  5063. <blockquote>

  5064.   <p><code>&lt;unzip src=&quot;${tomcat_src}/tools-src.zip&quot; dest=&quot;${tools.home}&quot;

  5065.   /&gt;</code></p>

  5066. </blockquote>

  5067. <hr>

  5068. <h2><a name="untar">Untar</a></h2>

  5069. <h3>Description</h3>

  5070. <p>Untars a tarfile.</p>

  5071. <p>File permissions will not be restored on extracted files.</p>

  5072. <p>For JDK 1.1 &quot;last modified time&quot; field is set to current time instead of being 

  5073. carried from tarfile.</p>

  5074. <h3>Parameters</h3>

  5075. <table border="1" cellpadding="2" cellspacing="0">

  5076.   <tr>

  5077.     <td valign="top"><b>Attribute</b></td>

  5078.     <td valign="top"><b>Description</b></td>

  5079.     <td align="center" valign="top"><b>Required</b></td>

  5080.   </tr>

  5081.   <tr>

  5082.     <td valign="top">src</td>

  5083.     <td valign="top">tarfile to expand.</td>

  5084.     <td align="center" valign="top">Yes</td>

  5085.   </tr>

  5086.   <tr>

  5087.     <td valign="top">dest</td>

  5088.     <td valign="top">directory where to store the expanded files.</td>

  5089.     <td align="center" valign="top">Yes</td>

  5090.   </tr>

  5091. </table>

  5092. <h3>Examples</h3>

  5093. <blockquote>

  5094.   <p><code>

  5095. &lt;gunzip src=&quot;tools.tar.gz&quot;/&gt;<br>

  5096. &lt;untar src=&quot;tools.tar&quot; dest=&quot;${tools.home}&quot;/&gt;

  5097. </code></p>

  5098. </blockquote>

  5099. <hr>

  5100. <h2><a name="war">War</a></h2>

  5101. <h3>Description</h3>

  5102. <p>An extension of the <a href="#jar">Jar</a> task with special

  5103. treatment for files that should end up in the

  5104. <code>WEB-INF/lib</code>, <code>WEB-INF/classes</code> or

  5105. <code>WEB-INF</code> directories of the Web Application Archive.

  5106. <p>(The War task is a shortcut for specifying the particular layout of a WAR file. 

  5107. The same thing can be accomplished by using the <i>prefix</i> and <i>fullpath</i>

  5108. attributes of the prefixedfilesets in a Zip or Jar task.)</p>

  5109. <h3>Parameters</h3>

  5110. <table border="1" cellpadding="2" cellspacing="0">

  5111.   <tr>

  5112.     <td valign="top"><b>Attribute</b></td>

  5113.     <td valign="top"><b>Description</b></td>

  5114.     <td align="center" valign="top"><b>Required</b></td>

  5115.   </tr>

  5116.   <tr>

  5117.     <td valign="top">warfile</td>

  5118.     <td valign="top">the war-file to create.</td>

  5119.     <td valign="top" align="center">Yes</td>

  5120.   </tr>

  5121.   <tr>

  5122.     <td valign="top">webxml</td>

  5123.     <td valign="top">The deployment descriptor to use (WEB-INF/web.xml).</td>

  5124.     <td valign="top" align="center">Yes</td>

  5125.   </tr>

  5126.   <tr>

  5127.     <td valign="top">basedir</td>

  5128.     <td valign="top">the directory from which to jar the files.</td>

  5129.     <td valign="top" align="center">No</td>

  5130.   </tr>

  5131.   <tr>

  5132.     <td valign="top">compress</td>

  5133.     <td valign="top">Not only store data but also compress them, defaults to true</td>

  5134.     <td align="center" valign="top">No</td>

  5135.   </tr>

  5136.   <tr>

  5137.     <td valign="top">includes</td>

  5138.     <td valign="top">comma separated list of patterns of files that must be

  5139.       included. All files are included when omitted.</td>

  5140.     <td valign="top" align="center">No</td>

  5141.   </tr>

  5142.   <tr>

  5143.     <td valign="top">includesfile</td>

  5144.     <td valign="top">the name of a file. Each line of this file is

  5145.       taken to be an include pattern</td>

  5146.     <td valign="top" align="center">No</td>

  5147.   </tr>

  5148.   <tr>

  5149.     <td valign="top">excludes</td>

  5150.     <td valign="top">comma separated list of patterns of files that must be

  5151.       excluded. No files (except default excludes) are excluded when omitted.</td>

  5152.     <td valign="top" align="center">No</td>

  5153.   </tr>

  5154.   <tr>

  5155.     <td valign="top">excludesfile</td>

  5156.     <td valign="top">the name of a file. Each line of this file is

  5157.       taken to be an exclude pattern</td>

  5158.     <td valign="top" align="center">No</td>

  5159.   </tr>

  5160.   <tr>

  5161.     <td valign="top">defaultexcludes</td>

  5162.     <td valign="top">indicates whether default excludes should be used or not

  5163.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  5164.     <td valign="top" align="center">No</td>

  5165.   </tr>

  5166.   <tr>

  5167.     <td valign="top">manifest</td>

  5168.     <td valign="top">the manifest file to use.</td>

  5169.     <td valign="top" align="center">No</td>

  5170.   </tr>

  5171.   <tr>

  5172.     <td valign="top">whenempty</td>

  5173.     <td valign="top">Behavior to use if no files match.</td>

  5174.     <td valign="top" align="center">No</td>

  5175.   </tr>

  5176. </table>

  5177. <h3>Nested elements</h3>

  5178. <h4>lib</h4>

  5179. <p>The nested <code>lib</code> element specifies a <a

  5180. href="#fileset">FileSet</a>. All files included in this fileset will

  5181. end up in the <code>WEB-INF/lib</code> directory of the war file.</p>

  5182. <h4>classes</h4>

  5183. <p>The nested <code>classes</code> element specifies a <a

  5184. href="#fileset">FileSet</a>. All files included in this fileset will

  5185. end up in the <code>WEB-INF/classes</code> directory of the war file.</p>

  5186. <h4>webinf</h4>

  5187. <p>The nested <code>webinf</code> element specifies a <a

  5188. href="#fileset">FileSet</a>. All files included in this fileset will

  5189. end up in the <code>WEB-INF</code> directory of the war file. If this

  5190. fileset includes a file named <code>web.xml</code>, the file is

  5191. ignored and you will get a warning.</p>

  5192. <h3>Examples</h3>

  5193. <p>Assume the following structure in the project's base directory:

  5194. <pre>

  5195. thirdparty/libs/jdbc1.jar

  5196. thirdparty/libs/jdbc2.jar

  5197. build/main/com/myco/myapp/Servlet.class

  5198. src/metadata/myapp.xml

  5199. src/html/myapp/index.html

  5200. src/jsp/myapp/front.jsp

  5201. src/graphics/images/gifs/small/logo.gif

  5202. src/graphics/images/gifs/large/logo.gif

  5203. </pre>

  5204. then the war file <code>myapp.war</code> created with

  5205. <pre>

  5206. &lt;war warfile=&quot;myapp.war&quot; webxml=&quot;src/metadata/myapp.xml&quot;&gt;

  5207.   &lt;fileset dir=&quot;src/html/myapp&quot;/&gt;

  5208.   &lt;fileset dir=&quot;src/jsp/myapp&quot;/&gt;

  5209.   &lt;lib dir=&quot;thirdparty/libs&quot;&gt;

  5210.     &lt;exclude name=&quot;jdbc1.jar&quot;/&gt;

  5211.   &lt;/lib&gt;

  5212.   &lt;classes dir=&quot;build/main&quot;/&gt;

  5213.   &lt;prefixedfileset dir=&quot;src/graphics/images/gifs&quot; 

  5214.                    prefix="images"/&gt;

  5215. &lt;/war&gt;

  5216. </pre>

  5217. will consist of

  5218. <pre>

  5219. WEB-INF/web.xml

  5220. WEB-INF/lib/jdbc2.jar

  5221. WEB-INF/classes/com/myco/myapp/Servlet.class

  5222. META-INF/MANIFEST.MF

  5223. index.html

  5224. front.jsp

  5225. images/small/logo.gif

  5226. images/large/logo.gif

  5227. </pre>

  5228. using Ant's default manifest file. The content of

  5229. <code>WEB-INF/web.xml</code> is identical to

  5230. <code>src/metadata/myapp.xml</code>.

  5231. <hr>

  5232. <h2><a name="zip">Zip</a></h2>

  5233. <h3>Description</h3>

  5234. <p>Creates a zipfile.</p>

  5235. <p>The <i>basedir</i> attribute is the reference directory from where to zip.</p>

  5236. <p>Note that file permissions will not be stored in the resulting zipfile.</p>

  5237. <p>It is possible to refine the set of files that are being zipped. This can be

  5238. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  5239. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  5240. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  5241. the files you want to have excluded. This is also done with patterns. And

  5242. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  5243. want to use default exclusions or not. See the section on <a

  5244. href="#directorybasedtasks">directory based tasks</a>, on how the

  5245. inclusion/exclusion of files works, and how to write patterns. 

  5246. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  5247. supports all attributes of <code>&lt;fileset&gt;</code>

  5248. (<code>dir</code> becomes <code>basedir</code>) as well as the nested

  5249. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  5250. <code>&lt;patternset&gt;</code> elements.</p>

  5251. <p>Or, you may place within it nested file sets, or references to file sets.

  5252. In this case <code>basedir</code> is optional; the implicit file set is <i>only used</i>

  5253. if <code>basedir</code> is set. You may use any mixture of the implicit file set

  5254. (with <code>basedir</code> set, and optional attributes like <code>includes</code>

  5255. and optional subelements like <code>&lt;include&gt;</code>); explicit nested

  5256. <code>&lt;fileset&gt;</code> elements so long as at least one fileset total is specified. The ZIP file will

  5257. only reflect the relative paths of files <i>within</i> each fileset.</p>

  5258. <p><code>&lt;zip&gt;</code> elements may contain both regular <code>&lt;fileset&gt;</code> elements

  5259. and also <code>&lt;prefixedfileset&gt;</code> elements.  A <code>&lt;prefixedfileset&gt;</code> is an extended form of a fileset,

  5260. which may include one of two special attributes: 

  5261. <i>prefix</i> or <i>fullpath</i>. These attributes modify the location of the files when they are placed 

  5262. inside the archive. If the <i>prefix</i> attribute is set, all the files in the prefixedfileset are prefixed

  5263. with that path in the archive. If the <i>fullpath</i> attribute is set, the file described by the prefixedfileset is placed at that 

  5264. exact location in the archive. (The <i>fullpath</i> attribute can only be set for prefixedfilesets that 

  5265. represent a single file. The <i>prefix</i> and <i>fullpath</i> attributes cannot both be set on the

  5266. same prefixedfileset.)</p>

  5267. <p>The <code>whenempty</code> parameter controls what happens when no files match.

  5268. If <code>skip</code> (the default), the ZIP is not created and a warning is issued.

  5269. If <code>fail</code>, the ZIP is not created and the build is halted with an error.

  5270. If <code>create</code>, an empty ZIP file (explicitly zero entries) is created,

  5271. which should be recognized as such by compliant ZIP manipulation tools.</p>

  5272. <h3>Parameters</h3>

  5273. <table border="1" cellpadding="2" cellspacing="0">

  5274.   <tr>

  5275.     <td valign="top"><b>Attribute</b></td>

  5276.     <td valign="top"><b>Description</b></td>

  5277.     <td valign="top" align="center"><b>Required</b></td>

  5278.   </tr>

  5279.   <tr>

  5280.     <td valign="top">zipfile</td>

  5281.     <td valign="top">the zip-file to create.</td>

  5282.     <td align="center" valign="top">Yes</td>

  5283.   </tr>

  5284.   <tr>

  5285.     <td valign="top">basedir</td>

  5286.     <td valign="top">the directory from which to zip the files.</td>

  5287.     <td align="center" valign="top">No</td>

  5288.   </tr>

  5289.   <tr>

  5290.     <td valign="top">compress</td>

  5291.     <td valign="top">Not only store data but also compress them, defaults to true</td>

  5292.     <td align="center" valign="top">No</td>

  5293.   </tr>

  5294.   <tr>

  5295.     <td valign="top">includes</td>

  5296.     <td valign="top">comma separated list of patterns of files that must be

  5297.       included. All files are included when omitted.</td>

  5298.     <td valign="top" align="center">No</td>

  5299.   </tr>

  5300.   <tr>

  5301.     <td valign="top">includesfile</td>

  5302.     <td valign="top">the name of a file. Each line of this file is

  5303.       taken to be an include pattern</td>

  5304.     <td valign="top" align="center">No</td>

  5305.   </tr>

  5306.   <tr>

  5307.     <td valign="top">excludes</td>

  5308.     <td valign="top">comma separated list of patterns of files that must be

  5309.       excluded. No files (except default excludes) are excluded when omitted.</td>

  5310.     <td valign="top" align="center">No</td>

  5311.   </tr>

  5312.   <tr>

  5313.     <td valign="top">excludesfile</td>

  5314.     <td valign="top">the name of a file. Each line of this file is

  5315.       taken to be an exclude pattern</td>

  5316.     <td valign="top" align="center">No</td>

  5317.   </tr>

  5318.   <tr>

  5319.     <td valign="top">defaultexcludes</td>

  5320.     <td valign="top">indicates whether default excludes should be used or not

  5321.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  5322.     <td valign="top" align="center">No</td>

  5323.   </tr>

  5324.   <tr>

  5325.     <td valign="top">whenempty</td>

  5326.     <td valign="top">Behavior when no files match.</td>

  5327.     <td valign="top" align="center">No</td>

  5328.   </tr>

  5329. </table>

  5330. <h3>Examples</h3>

  5331. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;

  5332.        basedir=&quot;htdocs/manual&quot;

  5333.   /&gt;</pre>

  5334. <p>zips all files in the <code>htdocs/manual</code> directory into a file called <code>manual.zip</code>

  5335. in the <code>${dist}</code> directory.</p>

  5336. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;

  5337.        basedir=&quot;htdocs/manual&quot;

  5338.        excludes=&quot;mydocs/**, **/todo.html&quot;

  5339.   /&gt;</pre>

  5340. <p>zips all files in the <code>htdocs/manual</code> directory. Files in the directory <code>mydocs</code>,

  5341. or files with the name <code>todo.html</code> are excluded.</p>

  5342. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;

  5343.        basedir=&quot;htdocs/manual&quot;

  5344.        includes=&quot;api/**/*.html&quot;

  5345.        excludes=&quot;**/todo.html&quot;

  5346.   /&gt;</pre>

  5347. <p>zips all files in the <code>htdocs/manual</code> directory. Only html files under the directory <code>api</code>

  5348. are zipped, and files with the name <code>todo.html</code> are excluded.</p>

  5349. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;&gt;

  5350.     &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;

  5351.     &lt;fileset dir=&quot;.&quot; includes=&quot;ChangeLog.txt&quot;/&gt;

  5352.   &lt;/zip&gt;</pre>

  5353. <p>zips all files in the <code>htdocs/manual</code> directory, and also adds the file <code>ChangeLog.txt</code> in the

  5354. current directory. <code>ChangeLog.txt</code> will be added to the top of the ZIP file, just as if

  5355. it had been located at <code>htdocs/manual/ChangeLog.txt</code>.</p>

  5356. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;&gt;

  5357.     &lt;prefixedfileset dir=&quot;htdocs/manual&quot; prefix=&quot;docs/user-guide&quot;/&gt;

  5358.     &lt;prefixedfileset dir=&quot;.&quot; includes=&quot;ChangeLog27.txt&quot; fullpath=&quot;docs/ChangeLog.txt&quot;/&gt;

  5359.   &lt;/zip&gt;</pre>

  5360. <p>zips all files in the <code>htdocs/manual</code> directory into the <code>docs/user-guide</code> directory

  5361. in the archive, and also adds the file <code>ChangeLog27.txt</code> in the

  5362. current directory as <code>docs/ChangeLog.txt</code>. For example, the archive might end up containing two files:

  5363. <code>docs/user-guide/html/index.html</code> and <code>docs/ChangeLog.txt</code></p>

  5364. 

  5365. <hr>

  5366. <h2><a name="optionaltasks">Optional tasks</a></h2>

  5367. <ul>

  5368.   <li><a href="dotnet.html">.NET Tasks</a></li>

  5369.   <li><a href="antlr.html">ANTLR</a></li>

  5370.   <li><a href="#cab">Cab</a></li>

  5371.   <li><a href="clearcase.html">Clearcase Tasks</a></li>

  5372.   <li><a href="ejb.html">EJB Tasks</a></li>

  5373.   <li><a href="#ftp">FTP</a></li>

  5374.   <li><a href="javacc.html">JavaCC</a></li>

  5375.   <li><a href="jlink.html">Jlink</a></li>

  5376.   <li><a href="junit.html">JUnit</a></li>

  5377.   <li><a href="native2ascii.html">Native2Ascii</a></li>

  5378.   <li><a href="#netrexxc">NetRexxC</a></li>

  5379.   <li><a href="propertyfile.html">PropertyFile</a></li>

  5380.   <li><a href="#renameexts">RenameExtensions</a></li>

  5381.   <li><a href="#script">Script</a></li>

  5382.   <li><a href="#sound">Sound</a></li>

  5383.   <li><a href="#telnet">Telnet</a></li>

  5384.   <li><a href="#vssget">VssGet</a></li>

  5385. </ul>

  5386. <hr>

  5387. <h2><a name="cab">Cab</a></h2>

  5388. <h3>Description</h3>

  5389. <p>The cab task creates Microsoft cab archive files.  It is invoked

  5390. similar to the <a href="#jar">jar</a> or <a href="#zip">zip</a> tasks.

  5391. This task will only work on Windows, and will be silently ignored on

  5392. other platforms.  You must have the Microsoft cabarc tool available in

  5393. your executable path.</p>

  5394. <p>See the section on <a href="#directorybasedtasks">directory based

  5395. tasks</a>, on how the inclusion/exclusion of files works, and how to

  5396. write patterns.</p>

  5397. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  5398. supports all attributes of <code>&lt;fileset&gt;</code>

  5399. (<code>dir</code> becomes <code>basedir</code>) as well as the nested

  5400. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  5401. <code>&lt;patternset&gt;</code> elements.</p>

  5402. <h3>Parameters</h3>

  5403. <table border="1" cellpadding="2" cellspacing="0">

  5404.   <tr>

  5405.     <td valign="top"><b>Attribute</b></td>

  5406.     <td valign="top"><b>Description</b></td>

  5407.     <td align="center" valign="top"><b>Required</b></td>

  5408.   </tr>

  5409.   <tr>

  5410.     <td valign="top">cabfile</td>

  5411.     <td valign="top">the name of the cab file to create.</td>

  5412.     <td valign="top" align="center">Yes</td>

  5413.   </tr>

  5414.   <tr>

  5415.     <td valign="top">basedir</td>

  5416.     <td valign="top">the directory to start archiving files from.</td>

  5417.     <td valign="top" align="center">Yes</td>

  5418.   </tr>

  5419.   <tr>

  5420.     <td valign="top">verbose</td>

  5421.     <td valign="top">set to &quot;yes&quot; if you want to see the output from

  5422.       the cabarc tool.  defaults to &quot;no&quot;.</td>

  5423.     <td valign="top" align="center">No</td>

  5424.   </tr>

  5425.   <tr>

  5426.     <td valign="top">compress</td>

  5427.     <td valign="top">set to &quot;no&quot; to store files without compressing.

  5428.       defaults to &quot;yes&quot;.</td>

  5429.     <td valign="top" align="center">No</td>

  5430.   </tr>

  5431.   <tr>

  5432.     <td valign="top">options</td>

  5433.     <td valign="top">use to set additional command-line options for

  5434.       the cabarc tool.  should not normally be necessary.</td>

  5435.     <td valign="top" align="center">No</td>

  5436.   </tr>

  5437.   <tr>

  5438.     <td valign="top">includes</td>

  5439.     <td valign="top">comma separated list of patterns of files that

  5440.       must be included. All files are included when omitted.</td>

  5441.     <td valign="top" align="center">No</td>

  5442.   </tr>

  5443.   <tr>

  5444.     <td valign="top">includesfile</td>

  5445.     <td valign="top">the name of a file. Each line of this file is

  5446.       taken to be an include pattern</td>

  5447.     <td valign="top" align="center">No</td>

  5448.   </tr>

  5449.   <tr>

  5450.     <td valign="top">excludes</td>

  5451.     <td valign="top">comma separated list of patterns of files that

  5452.       must be excluded. No files (except default excludes) are excluded

  5453.       when omitted.</td>

  5454.     <td valign="top" align="center">No</td>

  5455.   </tr>

  5456.   <tr>

  5457.     <td valign="top">excludesfile</td>

  5458.     <td valign="top">the name of a file. Each line of this file is

  5459.       taken to be an exclude pattern</td>

  5460.     <td valign="top" align="center">No</td>

  5461.   </tr>

  5462.   <tr>

  5463.     <td valign="top">defaultexcludes</td>

  5464.     <td valign="top">indicates whether default excludes should be used

  5465.       or not (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

  5466.     <td valign="top" align="center">No</td>

  5467.   </tr>

  5468. </table>

  5469. <h3>Examples</h3>

  5470. <blockquote><pre>

  5471. &lt;cab cabfile=&quot;${dist}/manual.cab&quot;

  5472.      basedir=&quot;htdocs/manual&quot; 

  5473.   /&gt;

  5474. </pre></blockquote>

  5475. <p>cabs all files in the htdocs/manual directory into a file called

  5476. manual.cab in the ${dist} directory.</p>

  5477. <blockquote><pre>

  5478. &lt;cab cabfile=&quot;${dist}/manual.cab&quot;

  5479.      basedir=&quot;htdocs/manual&quot;

  5480.      excludes=&quot;mydocs/**, **/todo.html&quot;

  5481.   /&gt;

  5482. </pre></blockquote>

  5483. <p>cabs all files in the htdocs/manual directory into a file called

  5484. manual.cab in the ${dist} directory. Files in the directory mydocs,

  5485. or files with the name todo.html are excluded.</p>

  5486. <blockquote><pre>

  5487. &lt;cab cabfile=&quot;${dist}/manual.cab&quot;

  5488.      basedir=&quot;htdocs/manual&quot;

  5489.      includes=&quot;api/**/*.html&quot;

  5490.      excludes=&quot;**/todo.html&quot;

  5491.      verbose=&quot;yes&quot;

  5492.   /&gt;

  5493. </pre></blockquote>

  5494. <p>cab all files in the htdocs/manual directory into a file called

  5495. manual.cab in the ${dist} directory. Only html files under the

  5496. directory api are archived, and files with the name todo.html are

  5497. excluded. Output from the cabarc tool is displayed in the build

  5498. output.</p>

  5499. <hr>

  5500. <h2><a name="ftp">FTP</a></h2>

  5501. <h3>Description</h3>

  5502. <p>The ftp task implements a basic FTP client that can send, receive,

  5503. list, and delete files.  See below for descriptions and examples of how

  5504. to perform each task.</p>

  5505. <p>The ftp task makes no attempt to determine what file system syntax is

  5506. required by the remote server, and defaults to Unix standards.

  5507. <i>remotedir</i> must be specified in the exact syntax required by the ftp

  5508. server. If the usual Unix conventions are not supported by the server,

  5509. <i>separator</i> can be used to set the file separator that should be used

  5510. instead.</p>

  5511. <p>See the section on <a href="#directorybasedtasks">directory based

  5512. tasks</a>, on how the inclusion/exclusion of files works, and how to

  5513. write patterns.</p>

  5514. <h3>Parameters</h3>

  5515. <table border="1" cellpadding="2" cellspacing="0">

  5516.   <tr>

  5517.     <td valign="top"><b>Attribute</b></td>

  5518.     <td valign="top"><b>Description</b></td>

  5519.     <td align="center" valign="top"><b>Required</b></td>

  5520.   </tr>

  5521.   <tr>

  5522.     <td valign="top">server</td>

  5523.     <td valign="top">the address of the remote ftp server.</td>

  5524.     <td valign="top" align="center">Yes</td>

  5525.   </tr>

  5526.   <tr>

  5527.     <td valign="top">port</td>

  5528.     <td valign="top">the port number of the remote ftp server.

  5529.                      Defaults to port 21.</td>

  5530.     <td valign="top" align="center">No</td>

  5531.   </tr>

  5532.   <tr>

  5533.     <td valign="top">userid</td>

  5534.     <td valign="top">the login id to use on the ftp server.</td>

  5535.     <td valign="top" align="center">Yes</td>

  5536.   </tr>

  5537.   <tr>

  5538.     <td valign="top">password</td>

  5539.     <td valign="top">the login password to use on the ftp server.</td>

  5540.     <td valign="top" align="center">Yes</td>

  5541.   </tr>

  5542.   <tr>

  5543.     <td valign="top">remotedir</td>

  5544.     <td valign="top">the directory to which to upload files on the 

  5545.                      ftp server.</td>

  5546.     <td valign="top" align="center">No</td>

  5547.   </tr>

  5548.   <tr>

  5549.     <td valign="top">action</td>

  5550.     <td valign="top">the ftp action to perform, defaulting to &quot;send&quot;.  

  5551.                      Currently supports&quot;put&quot;, &quot;get&quot;,

  5552.                      &quot;del&quot;, and &quot;list&quot;.</td>

  5553.     <td valign="top" align="center">No</td>

  5554.   </tr>

  5555.   <tr>

  5556.     <td valign="top">binary</td>

  5557.     <td valign="top">selects binary-mode (&quot;yes&quot;) or text-mode 

  5558.                      (&quot;no&quot;) transfers.  

  5559.                      Defaults to &quot;yes&quot;</td>

  5560.     <td valign="top" align="center">No</td>

  5561.   </tr>

  5562.   <tr>

  5563.     <td valign="top">passive</td>

  5564.     <td valign="top">selects passive-mode (&quot;yes&quot;) transfers.  

  5565.                      Defaults to &quot;no&quot;</td>

  5566.     <td valign="top" align="center">No</td>

  5567.   </tr>

  5568.   <tr>

  5569.     <td valign="top">verbose</td>

  5570.     <td valign="top">displays information on each file transferred if set 

  5571.                      to &quot;yes&quot;. Defaults to &quot;no&quot;.</td>

  5572.     <td valign="top" align="center">No</td>

  5573.   </tr>

  5574.   <tr>

  5575.     <td valign="top">depends</td>

  5576.     <td valign="top">transfers only new or changed files if set to 

  5577.                      &quot;yes&quot;. Defaults to &quot;no&quot;.</td>

  5578.     <td valign="top" align="center">No</td>

  5579.   </tr>

  5580.   <tr>

  5581.     <td valign="top">newer</td>

  5582.     <td valign="top">a synonym for <i>depends</i>.</td>

  5583.     <td valign="top" align="center">No</td>

  5584.   </tr>

  5585.   <tr>

  5586.     <td valign="top">separator</td>

  5587.     <td valign="top">sets the file separator used on the ftp server.

  5588.                      Defaults to &quot;/&quot;.</td>

  5589.     <td valign="top" align="center">No</td>

  5590.   </tr>

  5591.   <tr>

  5592.     <td valign="top">listing</td>

  5593.     <td valign="top">the file to write results of the &quot;list&quot; action.

  5594.                      Required for the &quot;list&quot; action, ignored otherwise.</td>

  5595.     <td valign="top" align="center">No</td>

  5596.   </tr>

  5597. </table>

  5598. <h3>Sending Files</h3>

  5599. <p>The easiest way to describe how to send files is with a couple of examples:</p>

  5600. <pre>

  5601.   &lt;ftp server=&quot;ftp.apache.org&quot;

  5602.        userid=&quot;anonymous&quot;

  5603.        password=&quot;me@myorg.com&quot;&gt;

  5604.     &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;

  5605.   &lt;/ftp&gt;

  5606. </pre>

  5607. <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and 

  5608. uploads all files in the <code>htdocs/manual</code> directory 

  5609. to the default directory for that user.</p>

  5610. <pre>  &lt;ftp server=&quot;ftp.apache.org&quot;

  5611.        remotedir=&quot;incoming&quot;

  5612.        userid=&quot;anonymous&quot;

  5613.        password=&quot;me@myorg.com&quot;

  5614.        depends=&quot;yes&quot;

  5615.   &gt;

  5616.     &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;

  5617.   &lt;/ftp&gt;</pre>

  5618. <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and 

  5619. uploads all new or changed files in the <code>htdocs/manual</code> directory 

  5620. to the <code>incoming</code> directory relative to the default directory

  5621. for <code>anonymous</code>.</p>

  5622. <pre>  &lt;ftp server=&quot;ftp.apache.org&quot;

  5623.        port=&quot;2121&quot;

  5624.        remotedir=&quot;/pub/incoming&quot;

  5625.        userid=&quot;coder&quot;

  5626.        password=&quot;java1&quot;

  5627.        depends=&quot;yes&quot;

  5628.        binary=&quot;no&quot;

  5629.   &gt;

  5630.     &lt;fileset dir=&quot;htdocs/manual&quot;&gt;

  5631.       &lt;include name=&quot;**/*.html&quot;/&gt;

  5632.     &lt;/fileset&gt;

  5633.   &lt;/ftp&gt;</pre>

  5634. <p>Logs in to <code>ftp.apache.org</code> at port <code>2121</code> as 

  5635. <code>coder</code> with password <code>java1</code> and uploads all new or 

  5636. changed HTML files in the <code>htdocs/manual</code> directory to the 

  5637. <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>

  5638. <pre>  &lt;ftp server=&quot;ftp.nt.org&quot;

  5639.        remotedir=&quot;c:\uploads&quot;

  5640.        userid=&quot;coder&quot;

  5641.        password=&quot;java1&quot;

  5642.        separator=&quot;\&quot;

  5643.        verbose=&quot;yes&quot;</pre>

  5644. <PRE>

  5645.   &gt;

  5646.     &lt;fileset dir=&quot;htdocs/manual&quot;&gt;

  5647.       &lt;include name=&quot;**/*.html&quot;/&gt;

  5648.     &lt;/fileset&gt;

  5649.   &lt;/ftp&gt;</PRE><p>Logs in to the Windows-based <code>ftp.nt.org</code> as 

  5650. <code>coder</code> with password <code>java1</code> and uploads all 

  5651. HTML files in the <code>htdocs/manual</code> directory to the 

  5652. <code>c:\uploads</code> directory.  Progress messages are displayed as each

  5653. file is uploaded.</p>

  5654. <h3>Getting Files</h3>

  5655. <p>Getting files from an FTP server works pretty much the same way as 

  5656. sending them does.  The only difference is that the nested filesets

  5657. use the remotedir attribute as the base directory for the files on the

  5658. FTP server, and the dir attribute as the local directory to put the files

  5659. into.  The file structure from the FTP site is preserved on the local machine.</p>

  5660. <pre>

  5661.   &lt;ftp action=&quot;get&quot;

  5662.        server=&quot;ftp.apache.org&quot;

  5663.        userid=&quot;anonymous&quot;

  5664.        password=&quot;me@myorg.com&quot;&gt;

  5665.     &lt;fileset dir=&quot;htdocs/manual&quot; &gt;

  5666.       &lt;include name=&quot;**/*.html&quot;/&gt;

  5667.     &lt;/fileset&gt;

  5668.   &lt;/ftp&gt;

  5669. </pre>

  5670. <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and 

  5671. recursively downloads all .html files from default directory for that user 

  5672. into the <code>htdocs/manual</code> directory on the local machine.</p>

  5673. <h3>Deleting Files</h3>

  5674. As you've probably guessed by now, you use nested fileset elements to 

  5675. select the files to delete from the remote FTP server.  Again, the 

  5676. filesets are relative to the remote directory, not a local directory.  In

  5677. fact, the dir attribute of the fileset is ignored completely.

  5678. <pre>

  5679.   &lt;ftp action=&quot;del&quot;

  5680.        server=&quot;ftp.apache.org&quot;

  5681.        userid=&quot;anonymous&quot;

  5682.        password=&quot;me@myorg.com&quot; &gt;

  5683.     &lt;fileset&gt;

  5684.       &lt;include name=&quot;**/*.tmp&quot;/&gt;

  5685.     &lt;/fileset&gt;

  5686.   &lt;/ftp&gt;

  5687. </pre>

  5688. <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and

  5689. tries to delete all *.tmp files from the default directory for that user.

  5690. If you don't have permission to delete a file, a BuildException is thrown.</p>

  5691. <h3>Listing Files</h3>

  5692. <pre>

  5693.   &lt;ftp action=&quot;list&quot;

  5694.        server=&quot;ftp.apache.org&quot;

  5695.        userid=quot;anonymous&quot;

  5696.        password=&quot;me@myorg.com&quot; 

  5697.        listing=&quot;data/ftp.listing&quot; &gt;

  5698.     &lt;fileset&gt;

  5699.       &lt;include name=&quot;**&quot;/&gt;

  5700.     &lt;/fileset&gt;

  5701.   &lt;/ftp&gt;

  5702. </pre>

  5703. <p>This provides a file listing in <code>data/ftp.listing</code> of all the files on

  5704. the FTP server relative to the default directory of the <code>anonymous</code>

  5705. user. The listing is in whatever format the FTP server normally lists files.</p>

  5706. <hr>

  5707. <h2><a name="netrexxc">NetRexxC</a></h2>

  5708. <h3>Description</h3>

  5709. <p>Compiles a <a href="http://www2.hursley.ibm.com/netrexx">NetRexx</a>

  5710. source tree within the running (Ant) VM.</p>

  5711. <p>The source and destination directory will be recursively scanned for

  5712. NetRexx source files to compile.  Only NetRexx files that have no corresponding

  5713. class file or where the class file is older than the java file will be compiled.</p>

  5714. <p>Files in the source tree are copied to the destination directory,

  5715. allowing support files to be located properly in the classpath. The source 

  5716. files are copied because the NetRexx compiler cannot produce class files in a

  5717. specific directory via parameters</p>

  5718. <p>The directory structure of the source tree should follow the package

  5719. hierarchy.</p>

  5720. <p>It is possible to refine the set of files that are being compiled/copied.

  5721. This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and

  5722. <i>defaultexcludes</i> attributes. With the <i>includes</i> or <i>includesfile</i> attribute you 

  5723. specify the files you want to have included by using patterns. The 

  5724. <i>exclude</i> or <i>excludesfile</i> attribute is used to specify the files you want to have 

  5725. excluded.  This is also done with patterns.  And finally with the 

  5726. <i>defaultexcludes</i> attribute, you can specify whether you

  5727. want to use default exclusions or not. See the section on <a

  5728. href="#directorybasedtasks">directory based tasks</a>, on how the

  5729. inclusion/exclusion of files works, and how to write patterns.</p>

  5730. <p>This task forms an implicit <a href="#fileset">FileSet</a> and

  5731. supports all attributes of <code>&lt;fileset&gt;</code>

  5732. (<code>dir</code> becomes <code>srcdir</code>) as well as the nested

  5733. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  5734. <code>&lt;patternset&gt;</code> elements.</p>

  5735. 

  5736. <h3>Parameters</h3>

  5737. <table border="1" cellpadding="2" cellspacing="0">

  5738.   <tr>

  5739.     <td valign="top"><b>Attribute</b></td>

  5740.     <td valign="top"><b>Description</b></td>

  5741.     <td align="center" valign="top"><b>Required</b></td>

  5742.   </tr>

  5743.   <tr>

  5744.     <td valign="top">binary</td>

  5745.     <td valign="top">Whether literals are treated as the java binary

  5746.       type rather than the NetRexx types</td>

  5747.     <td valign="top" align="center">No</td>

  5748.   </tr>

  5749.   <tr>

  5750.     <td valign="top">classpath</td>

  5751.     <td valign="top">The classpath to use during compilation</td>

  5752.     <td valign="top" align="center">No</td>

  5753.   </tr>

  5754.   <tr>

  5755.     <td valign="top">comments</td>

  5756.     <td valign="top">Whether comments are passed through to the

  5757.       generated java source</td>

  5758.     <td valign="top" align="center">No</td>

  5759.   </tr>

  5760.   <tr>

  5761.     <td valign="top">compact</td>

  5762.     <td valign="top">Whether error messages come out in compact or

  5763.       verbose format</td>

  5764.     <td valign="top" align="center">No</td>

  5765.   </tr>

  5766.   <tr>

  5767.     <td valign="top">compile</td>

  5768.     <td valign="top">Whether the NetRexx compiler should compile the

  5769.       generated java code</td>

  5770.     <td valign="top" align="center">No</td>

  5771.   </tr>

  5772.   <tr>

  5773.     <td valign="top">console</td>

  5774.     <td valign="top">Whether or not messages should be displayed on the

  5775.       'console'</td>

  5776.     <td valign="top" align="center">No</td>

  5777.   </tr>

  5778.   <tr>

  5779.     <td valign="top">crossref</td>

  5780.     <td valign="top">Whether variable cross references are generated</td>

  5781.     <td valign="top" align="center">No</td>

  5782.   </tr>

  5783.   <tr>

  5784.     <td valign="top">decimal</td>

  5785.     <td valign="top">Whether decimal arithmetic should be used for the

  5786.       NetRexx code</td>

  5787.     <td valign="top" align="center">No</td>

  5788.   </tr>

  5789.   <tr>

  5790.     <td valign="top">defaultexcludes</td>

  5791.     <td valign="top">indicates whether default excludes should be used or not

  5792.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when

  5793.       omitted.</td>

  5794.     <td valign="top" align="center">No</td>

  5795.   </tr>

  5796.   <tr>

  5797.     <td valign="top">destDir</td>

  5798.     <td valign="top">the destination directory into which the NetRexx

  5799.       source files should be copied and then compiled</td>

  5800.     <td valign="top" align="center">Yes</td>

  5801.   </tr>

  5802.   <tr>

  5803.     <td valign="top">diag</td>

  5804.     <td valign="top">Whether diagnostic information about the compile is

  5805.       generated</td>

  5806.     <td valign="top" align="center">No</td>

  5807.   </tr>

  5808.   <tr>

  5809.     <td valign="top">excludes</td>

  5810.     <td valign="top">comma separated list of patterns of files that must be

  5811.       excluded. No files (except default excludes) are excluded when

  5812.       omitted.</td>

  5813.     <td valign="top" align="center">No</td>

  5814.   </tr>

  5815.   <tr>

  5816.     <td valign="top">excludesfile</td>

  5817.     <td valign="top">the name of a file. Each line of this file is

  5818.       taken to be an exclude pattern</td>

  5819.     <td valign="top" align="center">No</td>

  5820.   </tr>

  5821.   <tr>

  5822.     <td valign="top">explicit</td>

  5823.     <td valign="top">Whether variables must be declared explicitly

  5824.       before use</td>

  5825.     <td valign="top" align="center">No</td>

  5826.   </tr>

  5827.   <tr>

  5828.     <td valign="top">format</td>

  5829.     <td valign="top">Whether the generated java code is formatted nicely

  5830.       or left to match NetRexx line numbers for call stack debugging</td>

  5831.     <td valign="top" align="center">No</td>

  5832.   </tr>

  5833.   <tr>

  5834.     <td valign="top">includes</td>

  5835.     <td valign="top">comma separated list of patterns of files that must be

  5836.       included. All files are included when omitted.</td>

  5837.     <td valign="top" align="center">No</td>

  5838.   </tr>

  5839.   <tr>

  5840.     <td valign="top">includesfile</td>

  5841.     <td valign="top">the name of a file. Each line of this file is

  5842.       taken to be an include pattern</td>

  5843.     <td valign="top" align="center">No</td>

  5844.   </tr>

  5845.   <tr>

  5846.     <td valign="top">java</td>

  5847.     <td valign="top">Whether the generated java code is produced</td>

  5848.     <td valign="top" align="center">No</td>

  5849.   </tr>

  5850.   <tr>

  5851.     <td valign="top">keep</td>

  5852.     <td valign="top">Sets whether the generated java source file should be kept

  5853.       after compilation. The generated files will have an extension of

  5854.       .java.keep, <b>not</b> .java</td>

  5855.     <td valign="top" align="center">No</td>

  5856.   </tr>

  5857.   <tr>

  5858.     <td valign="top">logo</td>

  5859.     <td valign="top">Whether the compiler text logo is displayed when

  5860.       compiling</td>

  5861.     <td valign="top" align="center">No</td>

  5862.   </tr>

  5863.   <tr>

  5864.     <td valign="top">replace</td>

  5865.     <td valign="top">Whether the generated .java file should be replaced

  5866.       when compiling</td>

  5867.     <td valign="top" align="center">No</td>

  5868.   </tr>

  5869.   <tr>

  5870.     <td valign="top">savelog</td>

  5871.     <td valign="top">Whether the compiler messages will be written to

  5872.       NetRexxC.log as well as to the console</td>

  5873.     <td valign="top" align="center">No</td>

  5874.   </tr>

  5875.   <tr>

  5876.     <td valign="top">sourcedir</td>

  5877.     <td valign="top">Tells the NetRexx compiler to store the class files in the

  5878.       same directory as the source files. The alternative is the working

  5879.       directory</td>

  5880.     <td valign="top" align="center">No</td>

  5881.   </tr>

  5882.   <tr>

  5883.     <td valign="top">srcDir</td>

  5884.     <td valign="top">Set the source dir to find the source Netrexx

  5885.       files</td>

  5886.     <td valign="top" align="center">Yes</td>

  5887.   </tr>

  5888.   <tr>

  5889.     <td valign="top">strictargs</td>

  5890.     <td valign="top">Tells the NetRexx compiler that method calls always

  5891.       need parentheses, even if no arguments are needed, e.g. 

  5892.       <code>aStringVar.getBytes</code> vs. 

  5893.       <code>aStringVar.getBytes()</code></td>

  5894.     <td valign="top" align="center">No</td>

  5895.   </tr>

  5896.   <tr>

  5897.     <td valign="top">strictassign</td>

  5898.     <td valign="top">Tells the NetRexx compile that assignments must

  5899.       match exactly on type</td>

  5900.     <td valign="top" align="center">No</td>

  5901.   </tr>

  5902.   <tr>

  5903.     <td valign="top">strictcase</td>

  5904.     <td valign="top">Specifies whether the NetRexx compiler should be

  5905.       case sensitive or not</td>

  5906.     <td valign="top" align="center">No</td>

  5907.   </tr>

  5908.   <tr>

  5909.     <td valign="top">strictimport</td>

  5910.     <td valign="top">Whether classes need to be imported explicitly using an 

  5911.       <code>import</code> statement.  By default the NetRexx compiler will 

  5912.       import certain packages automatically</td>

  5913.     <td valign="top" align="center">No</td>

  5914.   </tr>

  5915.   <tr>

  5916.     <td valign="top">strictprops</td>

  5917.     <td valign="top">Whether local properties need to be qualified

  5918.       explicitly using <code>this</code></td>

  5919.     <td valign="top" align="center">No</td>

  5920.   </tr>

  5921.   <tr>

  5922.     <td valign="top">strictsignal</td>

  5923.     <td valign="top">Whether the compiler should force catching of

  5924.       exceptions by explicitly named types</td>

  5925.     <td valign="top" align="center">No</td>

  5926.   </tr>

  5927.   <tr>

  5928.     <td valign="top">symbols</td>

  5929.     <td valign="top">Whether debug symbols should be generated into the

  5930.       class file</td>

  5931.     <td valign="top" align="center">No</td>

  5932.   </tr>

  5933.   <tr>

  5934.     <td valign="top">time</td>

  5935.     <td valign="top">Asks the NetRexx compiler to print compilation

  5936.       times to the console</td>

  5937.     <td valign="top" align="center">No</td>

  5938.   </tr>

  5939.   <tr>

  5940.     <td valign="top">trace</td>

  5941.     <td valign="top">Turns on or off tracing and directs the resultant

  5942.       trace output</td>

  5943.     <td valign="top" align="center">No</td>

  5944.   </tr>

  5945.   <tr>

  5946.     <td valign="top">utf8</td>

  5947.     <td valign="top">Tells the NetRexx compiler that the source is in UTF8</td>

  5948.     <td valign="top" align="center">No</td>

  5949.   </tr>

  5950.   <tr>

  5951.     <td valign="top">verbose</td>

  5952.     <td valign="top">Whether lots of warnings and error messages should

  5953.       be generated</td>

  5954.     <td valign="top" align="center">Yes</td>

  5955.   </tr>

  5956. </table>

  5957. <h3>Examples</h3>

  5958. <blockquote>

  5959.   <p><code>&lt;netrexxc srcDir=&quot;/source/project&quot;

  5960.            includes=&quot;vnr/util/*&quot;

  5961.            destDir=&quot;/source/project/build&quot;

  5962.            classpath=&quot;/source/project2/proj.jar&quot;

  5963.            comments=&quot;true&quot;

  5964.            crossref=&quot;false&quot; replace=&quot;true&quot;

  5965.            keep=&quot;true&quot;/&gt;</code>

  5966.   </p>

  5967. </blockquote>

  5968. <hr>

  5969. <h2><a name="renameexts">RenameExtensions</a></h2>

  5970. <h3><i>Deprecated</i></h3>

  5971. <p><i>This task has been deprecated.  Use the <a href="#move">move</a>

  5972. task with a <a href="#glob-mapper">glob mapper</a> instead.</i></p>

  5973. <h3>Description</h3>

  5974. <p>Renames files in the <code>srcDir</code> directory ending with the

  5975. <code>fromExtension</code> string so that they end with the 

  5976. <code>toExtension</code> string. Files are only replaced if 

  5977. <code>replace</code> is true

  5978. </p>

  5979. <p>See the section on 

  5980. <a href="#directorybasedtasks">directory based tasks</a>, on how the

  5981. inclusion/exclusion of files works, and how to write patterns. 

  5982. This task forms an implicit <a href="#fileset">FileSet</a> and

  5983. supports all attributes of <code>&lt;fileset&gt;</code>

  5984. (<code>dir</code> becomes <code>srcDir</code>) as well as the nested

  5985. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and

  5986. <code>&lt;patternset&gt;</code> elements.</p>

  5987. <h3>Parameters</h3>

  5988. <table border="1" cellpadding="2" cellspacing="0">

  5989.   <tr>

  5990.     <td valign="top"><b>Attribute</b></td>

  5991.     <td valign="top"><b>Description</b></td>

  5992.     <td align="center" valign="top"><b>Required</b></td>

  5993.   </tr>

  5994.   <tr>

  5995.     <td valign="top">defaultexcludes</td>

  5996.     <td valign="top">indicates whether default excludes should be used or not

  5997.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when

  5998.       omitted.</td>

  5999.     <td valign="top" align="center">No</td>

  6000.   </tr>

  6001.   <tr>

  6002.     <td valign="top">excludes</td>

  6003.     <td valign="top">comma separated list of patterns of files that must be

  6004.       excluded. No files (except default excludes) are excluded when

  6005.       omitted.</td>

  6006.     <td valign="top" align="center">No</td>

  6007.   </tr>

  6008.   <tr>

  6009.     <td valign="top">excludesfile</td>

  6010.     <td valign="top">the name of a file. Each line of this file is

  6011.       taken to be an exclude pattern</td>

  6012.     <td valign="top" align="center">No</td>

  6013.   </tr>

  6014.   <tr>

  6015.     <td valign="top">fromExtention</td>

  6016.     <td valign="top">The string that files must end in to be renamed</td>

  6017.     <td valign="top" align="center">Yes</td>

  6018.   </tr>

  6019.   <tr>

  6020.     <td valign="top">includes</td>

  6021.     <td valign="top">comma separated list of patterns of files that must be

  6022.       included. All files are included when omitted.</td>

  6023.     <td valign="top" align="center">No</td>

  6024.   </tr>

  6025.   <tr>

  6026.     <td valign="top">includesfile</td>

  6027.     <td valign="top">the name of a file. Each line of this file is

  6028.       taken to be an include pattern</td>

  6029.     <td valign="top" align="center">No</td>

  6030.   </tr>

  6031.   <tr>

  6032.     <td valign="top">replace</td>

  6033.     <td valign="top">Whether the file being renamed to should be

  6034.       replaced if it already exists</td>

  6035.     <td valign="top" align="center">No</td>

  6036.   </tr>

  6037.   <tr>

  6038.     <td valign="top">srcDir</td>

  6039.     <td valign="top">The starting directory for files to search in</td>

  6040.     <td valign="top" align="center">Yes</td>

  6041.   </tr>

  6042.   <tr>

  6043.     <td valign="top">toExtension</td>

  6044.     <td valign="top">The string that renamed files will end with on

  6045.       completion</td>

  6046.     <td valign="top" align="center">Yes</td>

  6047.   </tr>

  6048. </table>

  6049. <h3>Examples</h3>

  6050. <blockquote>

  6051.   <p><code>&lt;renameext srcDir=&quot;/source/project1&quot;

  6052.               includes=&quot;**&quot;

  6053.               excludes=&quot;**/samples/*&quot;

  6054.               fromExtension=&quot;.java.keep&quot;

  6055.               toExtension=&quot;.java&quot;

  6056.               replace=&quot;true&quot;/&gt;

  6057. </code>

  6058.   </p>

  6059. </blockquote>

  6060. 

  6061. <hr>

  6062. <h2><a name="script">Script</a></h2>

  6063. <h3>Description</h3>

  6064. <p>Execute a script in a 

  6065.   <a href="http://oss.software.ibm.com/developerworks/opensource/bsf/">BSF</a> supported language.

  6066. <p>All items (tasks, targets, etc) of the running project are

  6067. accessible from the script, using either their <code>name</code> or

  6068. <code>id</code> attributes.</p>

  6069. <p>Scripts can do almost anything a task written in Java could do.</p>

  6070. <h3>Parameters</h3>

  6071. <table border="1" cellpadding="2" cellspacing="0">

  6072.   <tr>

  6073.     <td valign="top"><b>Attribute</b></td>

  6074.     <td valign="top"><b>Description</b></td>

  6075.     <td align="center" valign="top"><b>Required</b></td>

  6076.   </tr>

  6077.   <tr>

  6078.     <td valign="top">language</td>

  6079.     <td valign="top">The programming language the script is written in.

  6080.       Must be a supported BSF language</td>

  6081.     <td valign="top" align="center">No</td>

  6082.   </tr>

  6083.   <tr>

  6084.     <td valign="top">src</td>

  6085.     <td valign="top">The location of the script as a file, if not inline</td>

  6086.     <td valign="top" align="center">No</td>

  6087.   </tr>

  6088. </table>

  6089. <h3>Examples</h3>

  6090. <blockquote><pre>

  6091. &lt;project name=&quot;squares&quot; default=&quot;main&quot; basedir=&quot;.&quot;&gt;

  6092. 

  6093.   &lt;target name=&quot;setup&quot;&gt;

  6094. 

  6095.     &lt;script language=&quot;javascript&quot;&gt; &lt;![CDATA[

  6096. 

  6097.       for (i=1; i&lt;=10; i++) {

  6098.         echo = squares.createTask(&quot;echo&quot;);

  6099.         main.addTask(echo);

  6100.         echo.setMessage(i*i);

  6101.       }

  6102. 

  6103.     ]]&gt; &lt;/script&gt;

  6104. 

  6105.   &lt;/target&gt;

  6106. 

  6107.   &lt;target name=&quot;main&quot; depends=&quot;setup&quot;/&gt;

  6108. 

  6109. &lt;/project&gt;

  6110. </pre></blockquote>

  6111. <p>generates</p>

  6112. <blockquote><pre>

  6113. setup:

  6114. 

  6115. main:

  6116. 1

  6117. 4

  6118. 9

  6119. 16

  6120. 25

  6121. 36

  6122. 49

  6123. 64

  6124. 81

  6125. 100

  6126. 

  6127. BUILD SUCCESSFUL

  6128. </pre></blockquote>

  6129. <p>Another example, using <a href="#references">references by id</a>

  6130. and two different scripting languages:</p>

  6131. <blockquote><pre>

  6132. &lt;project name=&quot;testscript&quot; default=&quot;main&quot;&gt;

  6133.   &lt;target name=&quot;sub&quot;&gt;

  6134.     &lt;echo id=&quot;theEcho&quot;/&gt;

  6135.   &lt;/target&gt;

  6136. 

  6137.   &lt;target name=&quot;sub1&quot;&gt;

  6138.     &lt;script language=&quot;netrexx&quot;&gt;&lt;![CDATA[

  6139.       theEcho.setMessage(&quot;In sub1&quot;)

  6140.       sub.execute

  6141.     ]]&gt;&lt;/script&gt;

  6142.   &lt;/target&gt;

  6143. 

  6144.   &lt;target name=&quot;sub2&quot;&gt;

  6145.     &lt;script language=&quot;javascript&quot;&gt;&lt;![CDATA[

  6146.       theEcho.setMessage(&quot;In sub2&quot;);

  6147.       sub.execute();

  6148.     ]]&gt;&lt;/script&gt;

  6149.   &lt;/target&gt;

  6150. 

  6151.   &lt;target name=&quot;main&quot; depends=&quot;sub1,sub2&quot;/&gt;

  6152. &lt;/project&gt;

  6153. </pre></blockquote>

  6154. <p>generates</p>

  6155. <blockquote><pre>

  6156. sub1:

  6157. In sub1

  6158. 

  6159. sub2:

  6160. In sub2

  6161. 

  6162. main:

  6163. 

  6164. BUILD SUCCESSFUL

  6165. </pre></blockquote>

  6166. 

  6167. <hr>

  6168. <h2><a name="sound">Sound</a></h2>

  6169. <h3>Description</h3>

  6170. <p>Plays a sound-file at the end of the build, according to whether

  6171. the build failed or succeeded. You can specify either a specific

  6172. sound-file to play, or, if a directory is specified, the

  6173. <code>&lt;sound&gt;</code> task will randomly select a file to play.

  6174. Note: At this point, the random selection is based on all the files

  6175. in the directory, not just those ending in appropriate suffixes

  6176. for sound-files, so be sure you only have sound-files in the 

  6177. directory you specify.

  6178. 

  6179. <h3>Parameters</h3>

  6180. <table border="1" cellpadding="2" cellspacing="0">

  6181.   <tr>

  6182.     <td valign="top"><b>Attribute</b></td>

  6183.     <td valign="top"><b>Description</b></td>

  6184.     <td align="center" valign="top"><b>Required</b></td>

  6185.   </tr>

  6186.   <tr>

  6187.     <td valign="top">loops</td>

  6188.     <td valign="top">the number of extra times to play the sound-file;

  6189.       default is <code>0</code>.

  6190.     </td>

  6191.     <td valign="top" align="center">No</td>

  6192.   </tr>

  6193.   <tr>

  6194.     <td valign="top">duration</td>

  6195.     <td valign="top">the amount of time (in milliseconds) to play

  6196.       the sound-file.

  6197.     </td>

  6198.     <td valign="top" align="center">No</td>

  6199.   </tr>

  6200. </table>

  6201. <p>

  6202. To specify the sound-files or the sound-file directories, use the

  6203. nested <code>&lt;success&gt;</code> and <code>&lt;fail&gt;</code> 

  6204. elements:

  6205. <blockquote>

  6206. <pre>

  6207. &lt;success&gt;     the path to a sound-file directory, or the name of a

  6208.               specific sound-file, to be played if the build succeeded.

  6209. &lt;fail&gt;        the path to a sound-file directory, or the name of a

  6210.               specific sound-file, to be played if the build succeeded.

  6211. </pre>

  6212. </blockquote>

  6213. 

  6214. <h3>Examples</h3>

  6215. <blockquote>

  6216. <pre>

  6217. &lt;target name="fun" if="fun" unless="fun.done"&gt;

  6218.   &lt;sound loops="2"&gt;

  6219.     &lt;success source="${user.home}/sounds/bell.wav"/&gt;

  6220.     &lt;fail source="${user.home}/sounds/ohno.wav"/&gt;

  6221.   &lt;/sound&gt;

  6222.   &lt;property name="fun.done" value="true"/&gt;

  6223. &lt;/target&gt;

  6224. </pre>

  6225. </blockquote>

  6226. plays the <code>bell.wav</code> sound-file if the build succeeded, or

  6227. the <code>ohno.wav</code> sound-file if the build failed, three times,

  6228. if the <code>fun</code> property is set to <code>true</code>.

  6229. If the target

  6230. is a dependency of an &quot;initialization&quot; target that other

  6231. targets depend on, the

  6232. <code>fun.done</code> property prevents the target from being executed

  6233. more than once.

  6234. <blockquote>

  6235. <pre>

  6236. &lt;target name="fun" if="fun" unless="fun.done"&gt;

  6237.   &lt;sound>

  6238.     &lt;success source="//intranet/sounds/success"/&gt;

  6239.     &lt;fail source="//intranet/sounds/failure"/&gt;

  6240.   &lt;/sound&gt;

  6241.   &lt;property name="fun.done" value="true"/&gt;

  6242. &lt;/target&gt;

  6243. </pre>

  6244. </blockquote>

  6245. randomly selects a sound-file to play when the build succeeds or fails.

  6246. 

  6247. <hr>

  6248. <h2><a name="telnet">Telnet</a></h2>

  6249. <h3>Description</h3>

  6250. Task to automate a remote telnet session. The task uses nested &lt;read&gt; to indicate strings to wait for, and  &lt;write&gt; tags to specify text to send.  

  6251. 

  6252. <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>

  6253. <h3>Parameters</h3>

  6254. <table border="1" cellpadding="2" cellspacing="0">

  6255.   <tr>

  6256.     <th>Attribute</th>

  6257.     <th>Values</th>

  6258.     <th>Required</th>

  6259.   </tr>

  6260.   <tr>

  6261.      <td>userid</td>

  6262.      <td>the login id to use on the telnet server.</td>

  6263.      <td>No</td>

  6264.   </tr>

  6265.   <tr>

  6266.      <td>password</td>

  6267.      <td>the login password to use on the telnet server.</td>

  6268.      <td>No</td>

  6269.   </tr>

  6270.   <tr>

  6271.      <td>server</td>

  6272.      <td>the address of the remote telnet server.</td>

  6273.      <td>Yes</td>

  6274.   </tr>

  6275.   <tr>

  6276.      <td>port</td>

  6277.      <td>the port number of the remote telnet server. Defaults to port 23.</td>

  6278.      <td>No</td>

  6279.   </tr>

  6280.   <tr>

  6281.      <td>initialCR</td>

  6282.      <td>send a cr after connecting ("yes"). Defaults to "no".</td>

  6283.      <td>No</td>

  6284.   </tr>

  6285.   <tr>

  6286.      <td>timeout</td>

  6287.      <td>set a default timeout to wait for a response. Specified in seconds. Default is no timeout.</td>

  6288.      <td>No</td>

  6289.   </tr>

  6290. </table>

  6291. <h3>Examples</h3>

  6292. 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.

  6293. <blockquote><pre>

  6294. &lt;telnet userid=&quot;bob&quot; password=&quot;badpass&quot; server=&quot;localhost&quot;&gt;

  6295.    &lt;read&gt;/home/bob&lt;/read&gt;

  6296.    &lt;write&gt;ls&lt;/write&gt;

  6297.    &lt;read string=&quot;/home/bob&quot;/&gt;

  6298. &lt;/telnet&gt;

  6299. </pre></blockquote>

  6300. 

  6301. This task can be rewritten as:

  6302. <blockquote><pre>

  6303. &lt;telnet server=&quot;localhost&quot;&gt;

  6304.    &lt;read&gt;ogin:&lt;/read&gt;

  6305.    &lt;write&gt;bob&lt;/write&gt;

  6306.    &lt;read&gt;assword:&lt;/read&gt;

  6307.    &lt;write&gt;badpass&lt;/write&gt;

  6308.    &lt;read&gt;/home/bob&lt;/read&gt;

  6309.    &lt;write&gt;ls&lt;/write&gt;

  6310.    &lt;read&gt;/home/bob&lt;/read&gt;

  6311. &lt;/telnet&gt;

  6312. </pre></blockquote>

  6313. 

  6314. A timeout can be specified at the &lt;telnet&gt; level or at the &lt;read&gt; level. This will connect, issue a sleep command that is suppressed from displaying and wait 10 seconds before quitting.

  6315. <blockquote><pre>

  6316. &lt;telnet userid=&quot;bob&quot; password=&quot;badpass&quot; server=&quot;localhost&quot; timeout=&quot;20&quot;&gt;

  6317.    &lt;read&gt;/home/bob&lt;/read&gt;

  6318.    &lt;write echo=&quot;false&quot;&gt;sleep 15&lt;/write&gt;

  6319.    &lt;read timeout=&quot;10&quot;&gt;/home/bob&lt;/read&gt;

  6320. &lt;/telnet&gt;

  6321. </pre></blockquote>

  6322. 

  6323. The task can be used with other ports as well:

  6324. <blockquote><pre>

  6325. &lt;telnet port=&quot;80&quot; server=&quot;localhost&quot; timeout=&quot;20&quot;&gt;

  6326.    &lt;read/&gt;

  6327.    &lt;write&gt;GET / http/0.9&lt;/write&gt;

  6328.    &lt;write/&gt;

  6329.    &lt;read timeout=&quot;10&quot;&gt;&amp;lt;/HTML&amp;gt;&lt;/read&gt;

  6330. &lt;/telnet&gt;

  6331. </pre></blockquote>

  6332. <hr>

  6333. <h2><a name="vssget">VssGet</a></h2>

  6334. <h3>Description</h3>

  6335. Task to perform GET commands to Microsoft Visual Source Safe.

  6336. <p>If you specify two or more attributes from version, date and 

  6337. label only one will be used in the order version, date, label.</p>

  6338. <h3>Parameters</h3>

  6339. <table border="1" cellpadding="2" cellspacing="0">

  6340.   <tr>

  6341.     <th>Attribute</th>

  6342.     <th>Values</th>

  6343.     <th>Required</th>

  6344.   </tr>

  6345.   <tr>

  6346.      <td>login</td>

  6347.      <td>username,password</td>

  6348.      <td>No</td>

  6349.   </tr>

  6350.   <tr>

  6351.      <td>vsspath</td>

  6352.      <td>SourceSafe path</td>

  6353.      <td>Yes</td>

  6354.   </tr>

  6355.   <tr>

  6356.      <td>localpath</td>

  6357.      <td>Override the working directory and get to the specified path</td>

  6358.      <td>No</td>

  6359.   </tr>

  6360.   <tr>

  6361.      <td>writable</td>

  6362.      <td>true or false</td>

  6363.      <td>No</td>

  6364.   </tr>

  6365.   <tr>

  6366.      <td>recursive</td>

  6367.      <td>true or false</td>

  6368.      <td>No</td>

  6369.   </tr>

  6370.   <tr>

  6371.      <td>version</td>

  6372.      <td>a version number to get</td>

  6373.      <td>No</td>

  6374.   </tr>

  6375.   <tr>

  6376.      <td>date</td>

  6377.      <td>a date stamp to get at</td>

  6378.      <td>No</td>

  6379.   </tr>

  6380.   <tr>

  6381.      <td>label</td>

  6382.      <td>a label to get for</td>

  6383.      <td>No</td>

  6384.   </tr>

  6385.   <tr>

  6386.      <td>ssdir</td>

  6387.      <td>directory where <code>ss.exe</code> resides. By default the

  6388.      task expects it to be in the PATH.</td>

  6389.      <td>No</td>

  6390.   </tr>

  6391. </table>

  6392. <p>Note that only one of version, date or label should be specified</p>

  6393. <h3>Examples</h3>

  6394. <blockquote>

  6395. <pre>

  6396. &lt;vssget localPath=&quot;C:\mysrc\myproject&quot;

  6397.         recursive=&quot;true&quot; 

  6398.         label=&quot;Release1&quot;

  6399.         login=&quot;me,mypassword&quot;

  6400.         vsspath=&quot;/source/aProject&quot;

  6401.         writable=&quot;true&quot;/&gt;

  6402. </pre>

  6403. </blockquote>

  6404. <p>Does a get on the VSS-Project <i>$/source/aproject</i> using the username

  6405. <i>me</i> and the password <i>mypassword</i>. It will recursively get the files 

  6406. which are labeled <i>Release1</i> and write them to the local directory

  6407. <i>C:\mysrc\myproject</i>. The local files will be writable.</p>

  6408. <hr>

  6409. 

  6410. <h2><a name="buildevents">Build Events</a></h2>

  6411. Ant is capable of generating build events as it performs the tasks necessary to build a project. 

  6412. Listeners can be attached to Ant to receive these events. This capability could be used, for example,

  6413. to connect Ant to a GUI or to integrate Ant with an IDE. 

  6414. 

  6415. <p>To use build events you need to create an ant <code>Project</code> object. You can then call the 

  6416. <code>addBuildListener</code> method to add your listener to the project. Your listener must implement

  6417. the <code>org.apache.tools.antBuildListener</code> interface. The listener will receive BuildEvents 

  6418. for the following events

  6419. <ul>

  6420. <li>Build started

  6421. <li>Build finished

  6422. <li>Target started

  6423. <li>Target finished

  6424. <li>Task started

  6425. <li>Task finished

  6426. <li>Message logged

  6427. </ul>

  6428. 

  6429. If you wish to attach a listener from the command line you may use the

  6430. <code>-listener</code> option. For example:

  6431. <blockquote>

  6432.   <pre>ant -listener org.apache.tools.ant.XmlLogger</pre>

  6433. </blockquote>

  6434. will run Ant with a listener that generates an XML representation of the build progress. This 

  6435. listener is included with Ant, as is the default listener, which generates the logging to standard output.

  6436. 

  6437. <hr>

  6438. <h2><a name="writingowntask">Writing Your Own Task</a></h2>

  6439. <p>It is very easy to write your own task:</p>

  6440. <ol>

  6441.   <li>Create a Java class that extends <code>org.apache.tools.ant.Task</code>.</li>

  6442.   <li>For each attribute, write a <i>setter</i> method. The setter method must be a 

  6443.     <code>public void</code> method that takes a single argument. The

  6444.     name of the method must begin with <code>set</code>, followed by the

  6445.     attribute name, with the first character of the name in uppercase, and the rest in

  6446.     lowercase. The type of the attribute can be:

  6447. <ul>

  6448. <li>

  6449. <code>String</code>

  6450. </li>

  6451. <li>

  6452. any primitive type (they are converted for you from their String-representation

  6453. in the buildfile)

  6454. </li>

  6455. <li>

  6456. boolean &#150; your method will be passed the value 

  6457. <i>true</i> if the value specified in the buildfile is one of <code>true</code>,

  6458. <code>yes</code>, or <code>on</code>)

  6459. </li>

  6460. <li>

  6461. <code>Class</code>

  6462. <li>

  6463. <code>File</code>

  6464. (in which case the value of the attribute is interpreted relative to the 

  6465. project's basedir)

  6466. </li>

  6467. <li>

  6468. any other type that has a constructor with a single 

  6469. <code>String</code> argument

  6470. </li>

  6471. </ul>

  6472. <li>If your task has enumerated attributes, you should consider using

  6473. a subclass of <code>org.apache.tools.ant.types.EnumeratedAttribute</code>

  6474. as an argument

  6475. to your setter method. See

  6476. <code>org/apache/tools/ant/taskdefs/FixCRLF.java</code> for

  6477. an example.</li>

  6478. <li>If the task should support character data, write a <code>public void 

  6479. addText(String)</code> method.</li>

  6480. <li>For each nested element, write a <i>create</i> or <i>add</i> method.

  6481. A create method 

  6482. must be a <code>public</code> method that takes no arguments and returns 

  6483. an <code>Object</code> type. The name of the create method must begin with 

  6484. <code>create</code>, followed by the element name. An add method must be 

  6485. a <code>public void</code> method that takes a single argument of an 

  6486. <code>Object</code> type with a no-argument constructor.

  6487. The name of the add method 

  6488. must begin with <code>add</code>, followed by the element name.

  6489. <li>Write a <code>public void execute</code> method, with no arguments, that

  6490. throws a <code>BuildException</code>. This method implements the task

  6491. itself.</li>

  6492. </ol>

  6493. 

  6494. <h3>The Life-cycle of a Task</h3>

  6495. <ol>

  6496.   <li>The task gets instantiated using a no-argument constructor, at parser

  6497.     time. This means even tasks that are never executed get

  6498.     instantiated.</li>

  6499. 

  6500.   <li>The task gets references to its project and location inside the

  6501.     buildfile via its inherited <code>project</code> and

  6502.     <code>location</code> variables.</li>

  6503. 

  6504.   <li>If the user specified an <code>id</code> attribute to this task,

  6505.     the project

  6506.     registers a reference to this newly created task, at parser

  6507.     time.</li>

  6508. 

  6509.   <li>The task gets a reference to the target it belongs to via its

  6510.     inherited <code>target</code> variable.</li>

  6511. 

  6512.   <li><code>init()</code> is called at parser time.</li>

  6513. 

  6514.   <li>All child elements of the XML element corresponding to this task

  6515.     are created via this task's <code>createXXX()</code> methods or

  6516.     instantiated and added to this task via its <code>addXXX()</code>

  6517.     methods, at parser time.</li>

  6518. 

  6519.   <li>All attributes of this task get set via their corresponding

  6520.     <code>setXXX</code> methods, at runtime.</li>

  6521. 

  6522.   <li>The content character data sections inside the XML element

  6523.     corresponding to this task is added to the task via its

  6524.     <code>addText</code> method, at runtime.</li>

  6525. 

  6526.   <li>All attributes of all child elements get set via their corresponding

  6527.     <code>setXXX</code> methods, at runtime.</li>

  6528. 

  6529.   <li><code>execute()</code> is called at runtime. While the above initialization 

  6530.     steps only occur once, the execute() method may be 

  6531.     called more than once, if the task is invoked more than once. For example, 

  6532.     if <code>target1</code> and <code>target2</code> both depend

  6533.     on <code>target3</code>, then running 

  6534.     <code>'ant target1 target2'</code> will run all tasks in

  6535.     <code>target3</code> twice.</li>

  6536. </ol>

  6537. 

  6538. <h3>Example</h3>

  6539. <p>Let's write our own task, which prints a message on the

  6540. <code>System.out</code> stream.

  6541. The

  6542. task has one attribute, called <code>message</code>.</p>

  6543. <blockquote>

  6544. <pre>

  6545. package com.mydomain;

  6546. 

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

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

  6549. 

  6550. public class MyVeryOwnTask extends Task {

  6551.   private String msg;

  6552. 

  6553.   // The method executing the task

  6554.   public void execute() throws BuildException {

  6555.     System.out.println(msg);

  6556.   }

  6557. 

  6558.   // The setter for the &quot;message&quot; attribute

  6559.   public void setMessage(String msg) {

  6560.     this.msg = msg;

  6561.   }

  6562. }

  6563. </pre>

  6564. </blockquote>

  6565. <p>It's really this simple ;-)</p>

  6566. <p>Adding your task to the system is rather simple too:</p>

  6567. <ol>

  6568.   <li>Make sure the class that implements your task is in the classpath when

  6569.     starting Ant.</li>

  6570.   <li>Add a <code>&lt;taskdef&gt;</code> element to your project.

  6571.     This actually adds your task to the system.</li>

  6572.   <li>Use your task in the rest of the buildfile.</li>

  6573. </ol>

  6574. 

  6575. <h3>Example</h3>

  6576. <blockquote>

  6577. <pre>

  6578. &lt;?xml version=&quot;1.0&quot;?&gt;

  6579. 

  6580. &lt;project name=&quot;OwnTaskExample&quot; default=&quot;main&quot; basedir=&quot;.&quot;&gt;

  6581.   &lt;taskdef name=&quot;mytask&quot; classname=&quot;com.mydomain.MyVeryOwnTask&quot;/&gt;

  6582. 

  6583.   &lt;target name=&quot;main&quot;&gt;

  6584.     &lt;mytask message=&quot;Hello World! MyVeryOwnTask works!&quot;/&gt;

  6585.   &lt;/target&gt;

  6586. &lt;/project&gt;

  6587. </pre>

  6588. </blockquote>

  6589. <p>Another way to add a task (more permanently), is to add the task name and

  6590. implementing class name to the <code>default.properties</code> file in the

  6591. <code>org.apache.tools.ant.taskdefs</code>

  6592. package. Then you can use it as if it were a built-in task.</p>

  6593. 

  6594. <hr>

  6595. <h2><a name="faq">FAQ, DTD, External Resources</a></h2>

  6596. <p>There is an on-line FAQ for Ant at <a

  6597. href="http://jakarta.apache.org/jyve-faq/Turbine/screen/DisplayTopics/action/SetAll/project_id/2/faq_id/16">jakarta.apache.org</a>. This

  6598. FAQ is interactive, which means you can ask and answer questions

  6599. on line.</p>

  6600. <p>One of the questions popping up quite often is &quot;Is there a DTD for

  6601. buildfiles?&quot; Please refer to the FAQ for an answer.</p>

  6602. 

  6603. <hr>

  6604. <h2><a name="feedback">Feedback</a></h2>

  6605. <p>To provide feedback on this software, please subscribe to the Ant User

  6606. Mail List (<a href="mailto:ant-user-subscribe@jakarta.apache.org">ant-user-subscribe@jakarta.apache.org</a>)</p>

  6607. <p>If you want to contribute to Ant or stay current with the latest

  6608. development, join the Ant Development Mail List (<a

  6609. href="mailto:ant-dev-subscribe@jakarta.apache.org">ant-dev-subscribe@jakarta.apache.org</a>)</p>

  6610. <p>Archives of both lists can be found at <a

  6611. href="http://archive.covalent.net/">http://archive.covalent.net/</a>. Many

  6612. thanks to Covalent Technologies. A searchable archive can be found at <a

  6613. href="http://marc.theaimsgroup.com">http://marc.theaimsgroup.com</a>. If

  6614. you know of any additional archive sites, please report them to the

  6615. lists.</p>

  6616. <hr>

  6617. <p align="center">Copyright &copy; 2000,2001 Apache Software Foundation. All rights

  6618. Reserved.</p>

  6619. 

  6620. </body>

  6621. </html>
Please read the following content carefully:

Dear OpenI User

Thank you for your continuous support to the Openl Qizhi Community AI Collaboration Platform. In order to protect your usage rights and ensure network security, we updated the Openl Qizhi Community AI Collaboration Platform Usage Agreement in January 2024. The updated agreement specifies that users are prohibited from using intranet penetration tools. After you click "Agree and continue", you can continue to use our services. Thank you for your cooperation and understanding.

For more agreement content, please refer to the《Openl Qizhi Community AI Collaboration Platform Usage Agreement》

Agree and continue
Disagree, exit