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: 084609e5ef
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '084609e5ef'
${ noResults }
ant/docs/index.html

3645 lines
146 KiB
Raw Blame History 

  1. <html>

  2. 

  3. <head>

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

  5. <title>Ant</title>

  6. </head>

  7. 

  8. <body>

  9. 

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

  11. <p>by</p>

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

  13. <ul>

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

  15.   <li>Stefan Bodewig (<a href="mailto:stefan.bodewig@megabit.net">stefan.bodewig@megabit.net</a>)</li>

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

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

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

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

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

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

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

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

  24. </ul>

  25. 

  26. <p>Version 1.0.8.2 - 2000/07/12</p>

  27. 

  28. <hr>

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

  30. <ul>

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

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

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

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

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

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

  37.   <li><a href="#buildfile">Writing a simple buildfile</a>

  38.   <li><a href="#directorybasedtasks">Directory based tasks</a></li>

  39.   <li><a href="#tasks">Built in Tasks</a>

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

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

  42.   <li><a href="#writingowntask">Writing your own task</a></li>

  43.   <li><a href="#faq">FAQ, DTD, external resources</a>

  44.   <li><a href="#license">License</a></li>

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

  46. </ul>

  47. 

  48. <hr>

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

  50. <p>Ant is a Java based build tool. In theory it is kind of like make without

  51. make's wrinkles.</p>

  52. <h3>Why?</h3>

  53. <p>Why another build tool when there is already make, gnumake, nmake, jam, and

  54. others? Because all of those tools have limitations that its original author

  55. couldn't live with when developing software across multiple platforms. Make like

  56. tools are inherently shell based. They evaluate a set of dependencies and then

  57. execute commands not unlike what you would issue on a shell. This means that you

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

  59. you are working on. However, this also means that you limit yourself to the OS,

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

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

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

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

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

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

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

  67. commands, it is extended using Java classes. Instead of writing shell commands,

  68. the configuration files are XML based calling out a target tree where various

  69. tasks get executed. Each task is run by an object which implements a particular

  70. Task interface.</p>

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

  72. able to construct a shell command such as `find . -name foo -exec rm {}` but it

  73. gives you the ability to be cross platform. To work anywhere and everywhere. And

  74. hey, if you really need to execute a shell command, Ant has an exec rule that

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

  76. on.</p>

  77. 

  78. <hr>

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

  80. <h3>Binary edition</h3>

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

  82. href="http://jakarta.apache.org/builds/tomcat/release/v3.0/ant.zip">http://jakarta.apache.org/builds/tomcat/release/v3.0/ant.zip</a>.

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

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

  85. <h3>Source edition</h3>

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

  87. href="http://jakarta.apache.org/builds/tomcat/release/v3.0/src/jakarta-tools.src.zip">http://jakarta.apache.org/builds/tomcat/release/v3.0/src/jakarta-tools.src.zip</a>

  88. (latest stable) or from <a

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

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

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

  92. 

  93. <hr>

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

  95. <p>

  96.   To build and use ant you must have a JAXP compilant XML parser installed and available on your classpath.

  97.   <p>

  98.   If you do not have a JAXP compliant XML parse installed, you may use the reference implementation 

  99.   available from Sun. It is available from <a href="http://java.sun.com/xml">http://java.sun.com/xml</a>.

  100.   Once installed make sure the "jaxp.jar" and "parser.jar" files are in your classpath.

  101.   <p>

  102.   You will also need the JDK installed on your system, version 1.1 or later. 

  103. 

  104. <hr>  

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

  106. <p>Go to the directory <code>jakarta-ant</code>.</p>

  107. <p>Make sure the JDK is in you path.</p>

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

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

  110. <p>When finished, use</p>

  111. <blockquote>

  112.   <p><code>build.bat -Dant.dist.dir=&lt;directory to install Ant&gt; dist</code></p>

  113. </blockquote>

  114. <p>for Windows, and</p>

  115. <blockquote>

  116.   <p><code>build.sh -Dant.dist.dir=&lt;directory to install Ant&gt; dist</code></p>

  117. </blockquote>

  118. <p>for UNIX, to create a binary distribution of Ant. This distribution can be

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

  120. <hr>

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

  122. <p>The binary distribution of Ant consists of three directories: <code>bin</code>,

  123. <code>docs</code> and <code>lib</code>. Only the <code>bin</code> and <code>lib</code>

  124. directory are crucial for running Ant. To run Ant, the following must be done:</p>

  125. <ul>

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

  127.   <li>Set the ANT_HOME environment variable. This should be set to the directory

  128.     which contains the <code>bin</code> and <code>lib</code> directory.</li>

  129.   <li>Set the JAVA_HOME environment variable. This should be set to the

  130.     directory where the JDK is installed.</li>

  131. </ul>

  132. <h3>Windows</h3>

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

  134. environment:</p>

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

  136. set JAVA_HOME=c:\jdk1.2.2

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

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

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

  140. the environment:</p>

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

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

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

  144. <h3>Advanced</h3>

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

  146. least the following:</p>

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

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

  149. <p>When you need JDK functionality (like a <a href="#javac">javac</a> task, or a

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

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

  152. must be added. The scripts supplied with ant, in the bin directory, will add 

  153. <code>tools.jar</code> automatically if the JAVA_HOME environment variable is set.</p>

  154. <p>When you are executing platform specific applications (like the <a

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

  156. must be set to the directory containing a bin directory, which contains the <code>antRun</code> shell script necessary to run execs on Unix.</p>

  157. <hr>

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

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

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

  161. <p>When nothing is specified, Ant looks for a <code>build.xml</code> file in the

  162. current directory. When found, it uses that file as a buildfile. To make Ant use

  163. another buildfile, use the commandline option <i>-buildfile &lt;file&gt;</i>,

  164. where <i>&lt;file&gt;</i> is the buildfile you want to use.</p>

  165. <p>You can also set properties which override properties specified in the

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

  167. This can be done with the <i>-D&lt;property&gt;=&lt;value&gt;</i>

  168. option, where <i>&lt;property&gt;</i> is the name of the property and <i>&lt;value&gt;</i>

  169. the value.</p>

  170. <p>To more options are <i>-quiet</i> which instructs Ant to print less

  171. information on the console when running. The option <i>-verbose</i> on the other

  172. hand makes Ant print more information on the console.</p>

  173. <p>It is also possible to specify the target that should be executed. Default

  174. the target that is mentioned in the <i>default</i> attribute of the project is

  175. used. This can be overridden by adding the target name to the end of the

  176. commandline.</p>

  177. <p>Commandline option summary:</p>

  178. <pre>ant [options] [target]

  179. Options:

  180. -help                  print this message

  181. -version               print the version information and exit

  182. -quiet                 be extra quiet

  183. -verbose               be extra verbose

  184. -logfile &lt;file&gt;        use given file for log

  185. -listener &lt;classname&gt;  add an instance of class as a project listener

  186. -buildfile &lt;file&gt;      use given buildfile

  187. -D&lt;property&gt;=&lt;value&gt;   use value for given property</pre>

  188. <h3>Examples</h3>

  189. <blockquote>

  190.   <pre>ant</pre>

  191. </blockquote>

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

  193. the default target.</p>

  194. <blockquote>

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

  196. </blockquote>

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

  198. the default target.</p>

  199. <blockquote>

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

  201. </blockquote>

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

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

  204. <blockquote>

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

  206. </blockquote>

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

  208. target called <code>dist</code>. It also sets the <i>build</i> property to the

  209. value <i>build/classes</i>.</p>

  210. <h3>Running Ant by hand</h3>

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

  212. with:</p>

  213. <blockquote>

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

  215. </blockquote>

  216. 

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

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

  219. command. This example assumes you have set up your classpath to include

  220. <ul>

  221. <li>ant.jar

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

  223. <li>the JDK's tools.jar

  224. </ul>

  225. <hr>

  226. <h2><a name="buildfile">Writing a simple buildfile</a></h2>

  227. <p>The buildfile is written in XML. Each buildfile contains one project.</p>

  228. <h3>Projects</h3>

  229. <p>A project has three attributes:</p>

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

  231.   <tr>

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

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

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

  235.   </tr>

  236.   <tr>

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

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

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

  240.   </tr>

  241.   <tr>

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

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

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

  245.   </tr>

  246.   <tr>

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

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

  249.       done. This attribute might be overridden by setting the &quot;basedir&quot;

  250.       property on forehand. When this is done, it might be ommitted in the

  251.       project tag.</td>

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

  253.   </tr>

  254. </table>

  255. <p>Each project defines one or more targets. A target is a set of tasks you want

  256. to be executed. When starting Ant, you can select which target you want to have

  257. executed. When no target is given, the project's default is used.</p>

  258. <h3>Targets</h3>

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

  260. for instance, and a target for creating a distributable. You can only build a

  261. distributable when you have compiled first, so the distribute target depends on

  262. the compile target. Ant resolves all these dependencies.</p>

  263. <p>Ant tries to execute the targets in the <i>depends</i> attribute in the order

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

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

  266. <blockquote>

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

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

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

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

  271. </blockquote>

  272. <p>Suppose we want to execute target D. From its <i>depends</i> attribute, you

  273. might think that first target C, then B and then A is executed. Wrong! C depends

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

  275. <p>A target gets executed only once. Even when more targets depend on it (see

  276. the previous example).</p>

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

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

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

  280. (java version, OS, command line properties, etc...).  To make target

  281. <i>sense</i> this property you should add the <i>if</i> (or

  282. <i>unless</i>) attribute with the name of the property that the target

  283. should react to, for example</p>

  284. <blockquote>

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

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

  287. </blockquote>

  288. <p>If no <i>if</i> and no <i>unless</i> attribute is present, the target will 

  289. always be executed.</p>

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

  291. href="#tstamp">tstamp</a> tasks in a so called initialization target, on which

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

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

  294. have the name "init".</p>

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

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

  297.   <tr>

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

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

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

  301.   </tr>

  302.   <tr>

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

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

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

  306.   </tr>

  307.   <tr>

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

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

  310.       target depends.</td>

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

  312.   </tr>

  313.   <tr>

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

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

  316.       target to execute.</td>

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

  318.   </tr>

  319.   <tr>

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

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

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

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

  324.   </tr>

  325. </table>

  326. <h3>Tasks</h3>

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

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

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

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

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

  332. <blockquote>

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

  334. </blockquote>

  335. <p>where name is the name of the task, attribute-x the attribute name, and

  336. value-x the value of this attribute.</p>

  337. <p>There is a set of <a href="#tasks">built in tasks</a>, but it is also very

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

  339. <p>All tasks share a <code>taskname</code> attribute. The value of

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

  341. Ant.</p>

  342. <h3>Properties</h3>

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

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

  345. property has a name and a value. Properties might be used in in the value of

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

  347. &quot;${&quot; and &quot;}&quot; in the attribute value.</p>

  348. <p>If there is a property called &quot;builddir&quot; with the value

  349. &quot;build&quot;, then this could be used in an attribute like this: &quot;${builddir}/classes&quot;.

  350. This is resolved as &quot;build/classes&quot;.</p>

  351. <h3>Token Filters</h3>

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

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

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

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

  356. <p>Since this can be a very harmful behavior, the tokens in the files <b>must</b>

  357. be of the form<i> @token@</i> where <i>token</i> is the token name that is set

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

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

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

  361. <p>Note: in case a token with the format @token@ if found in a file but no

  362. filter is associated with that token, no changes take place. So, no escaping

  363. method is present, but as long as you choose appropriate names for your tokens,

  364. this should not cause problems.</p>

  365. <h3>Examples</h3>

  366. <blockquote>

  367.   <pre>&lt;project name=&quot;foo&quot; default=&quot;dist&quot; basedir=&quot;.&quot;&gt;

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

  369.     &lt;tstamp/&gt;

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

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

  372.     &lt;filter token=&quot;version&quot; value=&quot;1.0.3&quot; /&gt;

  373.     &lt;filter token=&quot;year&quot; value=&quot;2000&quot; /&gt;

  374.   &lt;/target&gt;

  375. 

  376.   &lt;target name=&quot;prepare&quot; depends=&quot;init&quot;&gt;

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

  378.   &lt;/target&gt;

  379. 

  380.   &lt;target name=&quot;compile&quot; depends=&quot;prepare&quot;&gt;

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

  382.   &lt;/target&gt;

  383. 

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

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

  386.     &lt;jar jarfile=&quot;${dist}/lib/foo${DSTAMP}.jar&quot;

  387.      basedir=&quot;${build}&quot; items=&quot;com&quot;/&gt;

  388.   &lt;/target&gt;

  389. 

  390.   &lt;target name=&quot;clean&quot; depends=&quot;init&quot;&gt;

  391.     &lt;deltree dir=&quot;${build}&quot; /&gt;

  392.     &lt;deltree dir=&quot;${dist}&quot; /&gt;

  393.   &lt;/target&gt;

  394. &lt;/project&gt;

  395. </pre>

  396. </blockquote>

  397. 

  398. <hr>

  399. <h2><a name="directorybasedtasks">Directory based tasks</a></h2>

  400. <p>Some tasks use directory trees for the task they perform. For instance, the <a

  401. href="#javac">Javac task</a> which works upon a directory tree with .java files.

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

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

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

  405. time:</p>

  406. <ul>

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

  408.     patterns</li>

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

  410.     patterns</li>

  411. </ul>

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

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

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

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

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

  417. patterns.</p>

  418. <h3>Patterns</h3>

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

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

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

  422. <p>Examples:</p>

  423. <p>'*.java' matches '.java', 'x.java' and 'FooBar.java', but not 'FooBar.xml'

  424. (does not end with '.java').</p>

  425. <p>'?.java' matches 'x.java', 'A.java', but not '.java' or 'xyz.java' (both

  426. don't have one character before '.java').</p>

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

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

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

  430. the second directories are matched, and so on. E.g. when we have the pattern '/?abc/*/*.java'

  431. and the path '/xabc/foobar/test.java', then first '?abc' is matched with 'xabc',

  432. then '*' is matched with 'foobar' and finally '*.java' is matched with 'test.java'.

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

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

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

  436. complete directory tree, or a file anywhere in the directory tree. To do this, '**'

  437. must be used as the name of a directory. When '**' is used as the name of a

  438. directory in the pattern, it matches zero or more directories. For instance:

  439. '/test/**' matches all files/directories under '/test/', such as '/test/x.java',

  440. or '/test/foo/bar/xyz.html', but not '/xyz.xml'.</p>

  441. <p>There is one &quot;shorthand&quot;, if a pattern ends with '/' or '\', then '**'

  442. is appended. E.g. &quot;mypackage/test/&quot; is interpreted as were it &quot;mypackage/test/**&quot;.</p>

  443. <p>Examples:</p>

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

  445.   <tr>

  446.     <td valign="top">**/CVS/*</td>

  447.     <td valign="top">Matches all files in CVS directories, that can be located

  448.       anywhere in the directory tree.

  449.       <p>Matches:</p>

  450.       <p>CVS/Repository<br>

  451.       org/apache/CVS/Entries<br>

  452.       org/apache/jakarta/tools/ant/CVS/Entries</p>

  453.       <p>But not:</p>

  454.       <p>org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)</td>

  455.   </tr>

  456.   <tr>

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

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

  459.       <p>Matches:</p>

  460.       <p>org/apache/jakarta/tools/ant/docs/index.html<br>

  461.       org/apache/jakarta/test.xml</p>

  462.       <p>But not:</p>

  463.       <p>org/apache/xyz.java ('jakarta'/' part is missing)</td>

  464.   </tr>

  465.   <tr>

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

  467.     <td valign="top">Matches all files in CVS directories, that are located

  468.       anywhere in the directory tree under org/apache.

  469.       <p>Matches:</p>

  470.       <p>org/apache/CVS/Entries<br>

  471.       org/apache/jakarta/tools/ant/CVS/Entries</p>

  472.       <p>But not:</p>

  473.       <p>org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)</td>

  474.   </tr>

  475.   <tr>

  476.     <td valign="top">**/test/**</td>

  477.     <td valign="top">Matches all files which have a directory 'test' in their

  478.       path, including 'test' as a filename.</td>

  479.   </tr>

  480. </table>

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

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

  483. <h3>Examples</h3>

  484. <pre>  &lt;copydir src=&quot;${src}&quot;

  485.            dest=&quot;${dist}&quot;

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

  487.            excludes=&quot;**/*.gif&quot; /&gt;</pre>

  488. <p>This copies all files in directories called &quot;images&quot;, that are

  489. located in the directory tree &quot;${src}&quot; to the destination &quot;${dist}&quot;,

  490. but excludes all &quot;*.gif&quot; files from the copy.</p>

  491. <p> This example can also be expressed using nested elements as

  492. <pre>  &lt;copydir src=&quot;${src}&quot;

  493.            dest=&quot;${dist}&quot;&gt;

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

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

  496.   &lt;/copydir&gt;

  497. </pre>

  498. 

  499. <h3>Default Excludes</h3>

  500. <p>There are a set of definitions which are excluded by default from all directory based tasks.

  501. They are:

  502. <pre>        &quot;**/*~&quot;,

  503.         &quot;**/#*#&quot;,

  504.         &quot;**/%*%&quot;,

  505.         &quot;**/CVS&quot;,

  506.         &quot;**/CVS/*&quot;,

  507.         &quot;**/.cvsignore&quot;

  508. </pre>

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

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

  511. <hr>

  512. <h2><a name="tasks">Built in tasks</a></h2>

  513. <ul>

  514.   <li><a href="#ant">Ant</a></li>

  515.   <li><a href="#available">Available</a></li>

  516.   <li><a href="#chmod">Chmod</a></li>

  517.   <li><a href="#copydir">Copydir</a></li>

  518.   <li><a href="#copyfile">Copyfile</a></li>

  519.   <li><a href="#cvs">Cvs</a></li>

  520.   <li><a href="#delete">Delete</a></li>

  521.   <li><a href="#deltree">Deltree</a></li>

  522.   <li><a href="#echo">Echo</a></li>

  523.   <li><a href="#exec">Exec</a></li>

  524.   <li><a href="#unzip">Expand</a></li>

  525.   <li><a href="#filter">Filter</a></li>

  526.   <li><a href="#fixcrlf">FixCRLF</a></li>

  527.   <li><a href="#get">Get</a></li>

  528.   <li><a href="#gunzip">GUnzip</a></li>

  529.   <li><a href="#gzip">GZip</a></li>

  530.   <li><a href="#jar">Jar</a></li>

  531.   <li><a href="#java">Java</a></li>

  532.   <li><a href="#javac">Javac</a></li>

  533.   <li><a href="#javadoc">Javadoc/Javadoc2</a></li>

  534.   <li><a href="#keysubst">KeySubst</a></li>

  535.   <li><a href="#mkdir">Mkdir</a></li>

  536.   <li><a href="#patch">Patch</a></li>

  537.   <li><a href="#property">Property</a></li>

  538.   <li><a href="#rename">Rename</a></li>

  539.   <li><a href="#replace">Replace</a></li>

  540.   <li><a href="#rmic">Rmic</a></li>

  541.   <li><a href="#signjar">SignJar</a></li>

  542.   <li><a href="#tar">Tar</a></li>

  543.   <li><a href="#taskdef">Taskdef</a></li>

  544.   <li><a href="#touch">Touch</a></li>

  545.   <li><a href="#tstamp">Tstamp</a></li>

  546.   <li><a href="#style">Style</a></li>

  547.   <li><a href="#unzip">Unjar</a></li>

  548.   <li><a href="#untar">Untar</a></li>

  549.   <li><a href="#unzip">Unzip</a></li>

  550.   <li><a href="#zip">Zip</a></li>

  551. </ul>

  552. <hr>

  553. <h2><a name="ant">Ant</a></h2>

  554. <h3><b>Description:</b></h3>

  555. <p>Runs Ant on a supplied buildfile. This can be used to build subprojects.</p>

  556. <p>When the <i>antfile</i> attribute is omitted, the file &quot;build.xml&quot;

  557. in the supplied directory (<i>dir</i> attribute) is used.</p>

  558. <p>If no target attribute is supplied, the default target of the new project is

  559. used.</p>

  560. <p>The properties of the current project will be available in the new project.

  561. These properties will override the properties that are set in the new project.

  562. (See also the <a href="#property">properties task</a>).</p>

  563. <h3>Parameters:</h3>

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

  565.   <tr>

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

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

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

  569.   </tr>

  570.   <tr>

  571.     <td valign="top">antfile</td>

  572.     <td valign="top">the buildfile to use.</td>

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

  574.   </tr>

  575.   <tr>

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

  577.     <td valign="top">the directory to use as a basedir for the new Ant project.</td>

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

  579.   </tr>

  580.   <tr>

  581.     <td valign="top">target</td>

  582.     <td valign="top">the target of the new Ant project that should be executed.</td>

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

  584.   </tr>

  585.   <tr>

  586.     <td valign="top">output</td>

  587.     <td valign="top">Filename to write the ant output to.

  588.     </td>

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

  590.   </tr>

  591. </table>

  592. <h3>Examples</h3>

  593. <blockquote>

  594.   <p><code>&lt;ant antfile=&quot;subproject/subbuild.xml&quot; dir=&quot;subproject&quot;

  595.   target=&quot;compile&quot; /&gt;</code></p>

  596.   <p><code>&lt;ant dir=&quot;subproject&quot; /&gt;</code></p>

  597. </blockquote>

  598. <hr>

  599. <h2><a name="available">Available</a></h2>

  600. <h3>Description</h3>

  601. <p>Sets a property if a resource is available at runtime. This resource can be a

  602. file resource, a class in classpath or a JVM system resource.</p>

  603. <p>The value part of the properties being set is <i>true</i> if the resource is

  604. present, otherwise, the property is not set.</p>

  605. <p>Normally, this task is used to set properties that are useful to avoid target

  606. execution depending on system parameters.</p>

  607. <h3>Parameters</h3>

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

  609.   <tr>

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

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

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

  613.   </tr>

  614.   <tr>

  615.     <td valign="top">property</td>

  616.     <td valign="top">the name of the property to set.</td>

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

  618.   </tr>

  619.   <tr>

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

  621.     <td valign="top">the class to look for in classpath.</td>

  622.     <td valign="middle" align="center" rowspan="3">Yes</td>

  623.   </tr>

  624.   <tr>

  625.     <td valign="top">resource</td>

  626.     <td valign="top">the resource to look for in the JVM</td>

  627.   </tr>

  628.   <tr>

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

  630.     <td valign="top">the file to look for.</td>

  631.   </tr>

  632. </table>

  633. <h3>Examples</h3>

  634. <pre>  &lt;available classname=&quot;org.whatever.Myclass&quot; property=&quot;Myclass.present&quot; /&gt;</pre>

  635. <p>sets the property <code><i>Myclass.present</i></code> to the value &quot;true&quot;

  636. if the <i>org.whatever.Myclass</i> is found in Ant's classpath.</p>

  637. <hr>

  638. <h2><a name="chmod">Chmod</a></h2>

  639. <h3>Description</h3>

  640. <p>Changes the permissions of a file or all files inside a specified directory. Right now it has efect only under Unix.

  641. The permissions are also UNIX style, like the argument for the chmod command.</p>

  642. <p>It is possible to refine the set of files whose permissions are changed. This can be

  643. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  644. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  645. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  646. the files you want to have excluded. This is also done with patterns. And

  647. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  648. want to use default exclusions or not. See the section on <a

  649. href="#directorybasedtasks">directory based tasks</a>, on how the

  650. inclusion/exclusion of files works, and how to write patterns. The patterns are

  651. relative to the <i>dir</i> directory.</p>

  652. <h3>Parameters</h3>

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

  654.   <tr>

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

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

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

  658.   </tr>

  659.   <tr>

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

  661.     <td valign="top">the file or single directory of which the permissions 

  662.       must be changed.</td>

  663.     <td valign="top" valign="middle" rowspan="2">exactly one of the two</td>

  664.   </tr>

  665.   <tr>

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

  667.     <td valign="top">the directory which holds the files whose permissions 

  668.       must be changed.</td>

  669.   </tr>

  670.   <tr>

  671.     <td valign="top">src</td>

  672.     <td valign="top">the file or single directory of which the permissions 

  673.       must be changed (<b>deprecated</b>, use <i>file</i> instead).</td>

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

  675.   </tr>

  676.   <tr>

  677.     <td valign="top">perm</td>

  678.     <td valign="top">the new permissions.</td>

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

  680.   </tr>

  681.   <tr>

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

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

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

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

  686.   </tr>

  687.   <tr>

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

  689.     <td valign="top">the name of a file. Each line of this file is

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

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

  692.   </tr>

  693.   <tr>

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

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

  696.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  698.   </tr>

  699.   <tr>

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

  701.     <td valign="top">the name of a file. Each line of this file is

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

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

  704.   </tr>

  705.   <tr>

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

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

  708.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  710.   </tr>

  711. </table>

  712. <h3>Examples</h3>

  713. <blockquote>

  714.   <p><code>&lt;chmod file=&quot;${dist}/start.sh&quot; perm=&quot;ugo+rx&quot;

  715.   /&gt;</code></p>

  716. </blockquote>

  717. <p>makes the &quot;start.sh&quot; file readable and executable for anyone on a

  718. UNIX system.</p>

  719. <pre>

  720.     &lt;chmod dir=&quot;${dist}/bin&quot; perm=&quot;ugo+rx&quot; includes="**/*.sh" /&gt;

  721. </pre>

  722. </blockquote>

  723. <p>makes all &quot;.sh&quot; files below <code>${dist}/bin</code>

  724. readable and executable for anyone on a UNIX system.</p>

  725. <hr>

  726. <h2><a name="copydir">Copydir</a></h2>

  727. <h3>Description</h3>

  728. <p>Copies a directory tree from the source to the destination.</p>

  729. <p>It is possible to refine the set of files that are being copied. This can be

  730. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  731. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  732. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  733. the files you want to have excluded. This is also done with patterns. And

  734. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  735. want to use default exclusions or not. See the section on <a

  736. href="#directorybasedtasks">directory based tasks</a>, on how the

  737. inclusion/exclusion of files works, and how to write patterns. The patterns are

  738. relative to the <i>src</i> directory.</p>

  739. <p>The <i>ignore</i> attribute contains the names of the files/directories that

  740. must be excluded from the copy. The names specified in the <i>ignore</i>

  741. attribute are just names, they do not contain any path information! Note that

  742. this attribute has been replaced by the <i>excludes</i> attribute.</p>

  743. <h3>Parameters</h3>

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

  745.   <tr>

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

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

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

  749.   </tr>

  750.   <tr>

  751.     <td valign="top">src</td>

  752.     <td valign="top">the directory to copy.</td>

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

  754.   </tr>

  755.   <tr>

  756.     <td valign="top">dest</td>

  757.     <td valign="top">the directory to copy to.</td>

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

  759.   </tr>

  760.   <tr>

  761.     <td valign="top">ignore</td>

  762.     <td valign="top">comma separated list of filenames/directorynames to ignore.

  763.       No files (except default excludes) are excluded when omitted. (<b>deprecated</b>,

  764.       use <i>excludes</i> instead).</td>

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

  766.   </tr>

  767.   <tr>

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

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

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

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

  772.   </tr>

  773.   <tr>

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

  775.     <td valign="top">the name of a file. Each line of this file is

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

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

  778.   </tr>

  779.   <tr>

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

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

  782.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  784.   </tr>

  785.   <tr>

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

  787.     <td valign="top">the name of a file. Each line of this file is

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

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

  790.   </tr>

  791.   <tr>

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

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

  794.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  796.   </tr>

  797.   <tr>

  798.     <td valign="top">filtering</td>

  799.     <td valign="top">indicates whether token filtering should take place during

  800.       the copy</td>

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

  802.   </tr>

  803.   <tr>

  804.     <td valign="top">forceoverwrite</td>

  805.     <td valign="top">overwrite existing files even if the destination

  806.       files are newer (default is false).</td>

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

  808.   </tr>

  809. </table>

  810. <h3>Examples</h3>

  811. <pre>  &lt;copydir src=&quot;${src}/resources&quot;

  812.            dest=&quot;${dist}&quot;

  813.   /&gt;</pre>

  814. <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>.</p>

  815. <pre>  &lt;copydir src=&quot;${src}/resources&quot;

  816.            dest=&quot;${dist}&quot;

  817.            includes=&quot;**/*.java&quot;

  818.            excludes=&quot;**/Test.java&quot;

  819.   /&gt;</pre>

  820. <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>

  821. recursively. All java files are copied, except for files with the name <code>Test.java</code>.</p>

  822. <pre>  &lt;copydir src=&quot;${src}/resources&quot;

  823.            dest=&quot;${dist}&quot;

  824.            includes=&quot;**/*.java&quot;

  825.            excludes=&quot;mypackage/test/**&quot; /&gt;</pre>

  826. <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>

  827. recursively. All java files are copied, except for the files under the <code>mypackage/test</code>

  828. directory.</p>

  829. <hr>

  830. <h2><a name="copyfile">Copyfile</a></h2>

  831. <h3>Description</h3>

  832. <p>Copies a file from the source to the destination. The file is only copied if

  833. the source file is newer than the destination file, or when the destination file

  834. does not exist.</p>

  835. <h3>Parameters</h3>

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

  837.   <tr>

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

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

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

  841.   </tr>

  842.   <tr>

  843.     <td valign="top">src</td>

  844.     <td valign="top">the filename of the file to copy.</td>

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

  846.   </tr>

  847.   <tr>

  848.     <td valign="top">dest</td>

  849.     <td valign="top">the filename of the file where to copy to.</td>

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

  851.   </tr>

  852.   <tr>

  853.     <td valign="top">filtering</td>

  854.     <td valign="top">indicates whether token filtering should take place during

  855.       the copy</td>

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

  857.   </tr>

  858. </table>

  859. <h3>Examples</h3>

  860. <blockquote>

  861.   <p><code>&lt;copyfile src=&quot;test.java&quot; dest=&quot;subdir/test.java&quot;

  862.   /&gt;</code></p>

  863.   <p><code>&lt;copyfile src=&quot;${src}/index.html&quot; dest=&quot;${dist}/help/index.html&quot;

  864.   /&gt;</code></p>

  865. </blockquote>

  866. <hr>

  867. <h2><a name="cvs">Cvs</a></h2>

  868. <h3>Description</h3>

  869. <p>Handles packages/modules retrieved from a 

  870. <a href="http://www.cyclic.com/">CVS</a> repository.</p>

  871. <p>When doing automated builds, the <a href="#get">get task</a> should be

  872. preferred over the <i>checkout</i> command, because of speed.</p>

  873. <h3>Parameters</h3>

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

  875.   <tr>

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

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

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

  879.   </tr>

  880.   <tr>

  881.     <td valign="top">command</td>

  882.     <td valign="top">the CVS command to execute.</td>

  883.     <td align="center" valign="top">No, default &quot;checkout&quot;</td>

  884.   </tr>

  885.   <tr>

  886.     <td valign="top">cvsRoot</td>

  887.     <td valign="top">the CVSROOT variable.</td>

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

  889.   </tr>

  890.   <tr>

  891.     <td valign="top">dest</td>

  892.     <td valign="top">the directory where the checked out files should be placed.</td>

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

  894.   </tr>

  895.   <tr>

  896.     <td valign="top">package</td>

  897.     <td valign="top">the package/module to check out.</td>

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

  899.   </tr>

  900.   <tr>

  901.     <td valign="top">tag</td>

  902.     <td valign="top">the tag of the package/module to check out.</td>

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

  904.   </tr>

  905.   <tr>

  906.     <td valign="top">date</td>

  907.     <td valign="top">Use the most recent revision no later than the given date</td>

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

  909.   </tr>

  910.   <tr>

  911.     <td valign="top">quiet</td>

  912.     <td valign="top">supress informational messages.</td>

  913.     <td align="center" valign="top">No, default &quot;false&quot;</td>

  914.   </tr>

  915.   <tr>

  916.     <td valign="top">noexec</td>

  917.     <td valign="top">report only, don't change any files.</td>

  918.     <td align="center" valign="top">No, default &quot;false&quot;</td>

  919.   </tr>

  920.   <tr>

  921.     <td valign="top">failonerror</td>

  922.     <td valign="top">Stop the buildprocess if the command exits with a

  923.       returncode other than 0.</td>

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

  925.   </tr>

  926. </table>

  927. <h3>Examples</h3>

  928. <pre>  &lt;cvs cvsRoot=&quot;:pserver:anoncvs@jakarta.apache.org:/home/cvspublic&quot;

  929.        package=&quot;jakarta-tools&quot;

  930.        dest=&quot;${ws.dir}&quot;

  931.   /&gt;</pre>

  932. <p>checks out the package/module &quot;jakarta-tools&quot; from the CVS

  933. repository pointed to by the cvsRoot attribute, and stores the files in &quot;${ws.dir}&quot;.</p>

  934. <pre>  &lt;cvs dest=&quot;${ws.dir}&quot; command=&quot;update&quot; /&gt;</pre>

  935. <p>updates the package/module that has previously been checked out into

  936. &quot;${ws.dir}&quot;.</p>

  937. <hr>

  938. <h2><a name="delete">Delete</a></h2>

  939. <h3>Description</h3>

  940. <p>Deletes either a single file or

  941. all files in a specified directory and its sub-directories.</p>

  942. <p>It is possible to refine the set of files that are being deleted. This can be

  943. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  944. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  945. have included in the deletion process by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  946. the files you want to have excluded from the deletion process. This is also done with patterns. And

  947. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  948. want to use default exclusions or not. See the section on <a

  949. href="#directorybasedtasks">directory based tasks</a>, on how the

  950. inclusion/exclusion of files works, and how to write patterns. The patterns are

  951. relative to the <i>dir</i> directory.</p>

  952. <h3>Parameters</h3>

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

  954.   <tr>

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

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

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

  958.   </tr>

  959.   <tr>

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

  961.     <td valign="top">The file to delete.</td>

  962.     <td align="center" valign="middle" rowspan="2">at least one of the two</td>

  963.   </tr>

  964.   <tr>

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

  966.     <td valign="top">The directory to delete files from.</td>

  967.   </tr>

  968.   <tr>

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

  970.     <td valign="top">Comma separated list of patterns of files that must be

  971.       deleted. All files are in the current directory 

  972.       and any sub-directories are deleted when omitted.</td>

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

  974.   </tr>

  975.   <tr>

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

  977.     <td valign="top">the name of a file. Each line of this file is

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

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

  980.   </tr>

  981.   <tr>

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

  983.     <td valign="top">Comma separated list of patterns of files that must be

  984.       excluded from the deletion list. No files (except default excludes) are excluded when omitted.</td>

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

  986.   </tr>

  987.   <tr>

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

  989.     <td valign="top">the name of a file. Each line of this file is

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

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

  992.   </tr>

  993.   <tr>

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

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

  996.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  998.   </tr>

  999.   <tr>

  1000.     <td valign="top">verbose</td>

  1001.     <td valign="top">Show name of each deleted file (&quot;true&quot;/&quot;false&quot;). Default is "false" when omitted.</td>

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

  1003.   </tr>

  1004. </table>

  1005. <h3>Examples</h3>

  1006. <pre>  &lt;delete file=&quot;/lib/ant.jar&quot; /&gt;</pre>

  1007. <p>deletes the file <code>/lib/ant.jar</code>.</p>

  1008. <pre>  &lt;delete dir=&quot;lib&quot; /&gt;</pre>

  1009. <p>deletes all files in the <code>/lib</code> directory.</p>

  1010. <pre>  &lt;delete dir=&quot;.&quot;

  1011.           include=&quot;**/*.bak&quot;

  1012.   /&gt;

  1013. </pre>

  1014. <p>deletes all files with the extension &quot;<code>.bak</code>&quot from the current directory 

  1015. and any sub-directories.</p>

  1016. <h2><a name="deltree">Deltree</a></h2>

  1017. <h3>Description</h3>

  1018. <p>Deletes a directory with all its files and subdirectories.</p>

  1019. <h3>Parameters</h3>

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

  1021.   <tr>

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

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

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

  1025.   </tr>

  1026.   <tr>

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

  1028.     <td valign="top">the directory to delete.</td>

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

  1030.   </tr>

  1031. </table>

  1032. <h3>Examples</h3>

  1033. <pre>  &lt;deltree dir=&quot;dist&quot; /&gt;</pre>

  1034. <p>deletes the directory <code>dist</code>, including its files and

  1035. subdirectories.</p>

  1036. <pre>  &lt;deltree dir=&quot;${dist}&quot; /&gt;</pre>

  1037. <p>deletes the directory <code>${dist}</code>, including its files and

  1038. subdirectories.</p>

  1039. <hr>

  1040. <h2><a name="echo">Echo</a></h2>

  1041. <h3>Description</h3>

  1042. <p>Echoes a message to System.out.</p>

  1043. <h3>Parameters</h3>

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

  1045.   <tr>

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

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

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

  1049.   </tr>

  1050.   <tr>

  1051.     <td valign="top">message</td>

  1052.     <td valign="top">the message to echo.</td>

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

  1054.   </tr>

  1055. </table>

  1056. <h3>Examples</h3>

  1057. <pre>  &lt;echo message=&quot;Hello world&quot; /&gt;</pre>

  1058. <hr>

  1059. <h2><a name="exec">Exec</a></h2>

  1060. <h3>Description</h3>

  1061. <p>Executes a system command. When the <i>os</i> attribute is specified, then

  1062. the command is only executed when Ant is run on one of the specified operating

  1063. systems.</p>

  1064. <h3>Parameters</h3>

  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">command</td>

  1073.     <td valign="top">the command to execute.</td>

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

  1075.   </tr>

  1076.   <tr>

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

  1078.     <td valign="top">the directory in which the command should be executed.</td>

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

  1080.   </tr>

  1081.   <tr>

  1082.     <td valign="top">os</td>

  1083.     <td valign="top">list of Operating Systems on which the command may be

  1084.       executed.</td>

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

  1086.   </tr>

  1087.   <tr>

  1088.     <td valign="top">output</td>

  1089.     <td valign="top">the file to which the output of the command should be

  1090.       redirected.</td>

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

  1092.   </tr>

  1093.   <tr>

  1094.     <td valign="top">failonerror</td>

  1095.     <td valign="top">Stop the buildprocess if the command exits with a

  1096.       returncode other than 0.</td>

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

  1098.   </tr>

  1099. </table>

  1100. <h3>Examples</h3>

  1101. <blockquote>

  1102.   <p><code>&lt;exec dir=&quot;${src}&quot; command=&quot;dir&quot; os=&quot;windows&quot;

  1103.   output=&quot;dir.txt&quot; /&gt;</code></p>

  1104. </blockquote>

  1105. <hr>

  1106. <h2><a name="unzip">Expand/Unzip/Unjar</a></h2>

  1107. <h3>Description</h3>

  1108. <p>Unzips a zip- or jarfile.</p>

  1109. <p>For JDK 1.1 "last modified time" field is set to current time instead of being 

  1110. carried from zipfile.</p>

  1111. <p>DEPRECATION: the expand task simply points to the unzip task and it's

  1112. there for back compatibility reasons.</p>

  1113. <h3>Parameters</h3>

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

  1115.   <tr>

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

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

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

  1119.   </tr>

  1120.   <tr>

  1121.     <td valign="top">src</td>

  1122.     <td valign="top">zipfile to expand.</td>

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

  1124.   </tr>

  1125.   <tr>

  1126.     <td valign="top">dest</td>

  1127.     <td valign="top">directory where to store the expanded files.</td>

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

  1129.   </tr>

  1130. </table>

  1131. <h3>Examples</h3>

  1132. <blockquote>

  1133.   <p><code>&lt;unzip src=&quot;${tomcat_src}/tools-src.zip&quot; dest=&quot;${tools.home}&quot;

  1134.   /&gt;</code></p>

  1135. </blockquote>

  1136. <hr>

  1137. <h2><a name="filter">Filter</a></h2>

  1138. <h3>Description</h3>

  1139. <p>Sets a token filter for this project. Token filters are used by all tasks

  1140. that perform file copying operations through the Project commodity methods.</p>

  1141. <p>Note: the token string must not contain the separators chars (@).</p>

  1142. <h3>Parameters</h3>

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

  1144.   <tr>

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

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

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

  1148.   </tr>

  1149.   <tr>

  1150.     <td valign="top">token</td>

  1151.     <td valign="top">the token string without @</td>

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

  1153.   </tr>

  1154.   <tr>

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

  1156.     <td valign="top">the string that should be put to replace the token when the

  1157.       file is copied</td>

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

  1159.   </tr>

  1160. </table>

  1161. <h3>Examples</h3>

  1162. <pre>  &lt;filter token=&quot;year&quot; value=&quot;2000&quot; /&gt;

  1163.   &lt;copydir src=&quot;${src.dir}&quot; dest=&quot;${dest.dir}&quot;/&gt;</pre>

  1164. <p>will copy recursively all the files from the <i>src.dir</i> directory into

  1165. the <i>dest.dir</i> directory replacing all the occurencies of the string <i>@year@</i>

  1166. with <i>2000.</i></p>

  1167. <hr>

  1168. <h2><a name="fixcrlf">FixCRLF</a></h2>

  1169. <h3>Description</h3>

  1170. <p>Adjusts a text file to local.</p>

  1171. <p>It is possible to refine the set of files that are being adjusted. This can be

  1172. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  1173. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  1174. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  1175. the files you want to have excluded. This is also done with patterns. And

  1176. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  1177. want to use default exclusions or not. See the section on <a

  1178. href="#directorybasedtasks">directory based tasks</a>, on how the

  1179. inclusion/exclusion of files works, and how to write patterns. The patterns are

  1180. relative to the <i>src</i> directory.</p>

  1181. <h3>Parameters</h3>

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

  1183.   <tr>

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

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

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

  1187.   </tr>

  1188.   <tr>

  1189.     <td valign="top">srcDir</td>

  1190.     <td valign="top">Where to find the files to be fixed up.</td>

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

  1192.   </tr>

  1193.   <tr>

  1194.     <td valign="top">destDir</td>

  1195.     <td valign="top">Where to place the corrected files.  Defaults to

  1196.       srcDir (replacing the original file)</td>

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

  1198.   </tr>

  1199.   <tr>

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

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

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

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

  1204.   </tr>

  1205.   <tr>

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

  1207.     <td valign="top">the name of a file. Each line of this file is

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

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

  1210.   </tr>

  1211.   <tr>

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

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

  1214.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  1216.   </tr>

  1217.   <tr>

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

  1219.     <td valign="top">the name of a file. Each line of this file is

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

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

  1222.   </tr>

  1223.   <tr>

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

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

  1226.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  1228.   </tr>

  1229.   <tr>

  1230.     <td valign="top">cr</td>

  1231.     <td valign="top">Specifies how carriage return (CR) characters are to

  1232.       be handled.  Valid values for this property are:

  1233.       <ul>

  1234.       <li>add: ensure that there is a CR before every LF

  1235.       <li>asis: leave CR characters alone

  1236.       <li>remove: remove all CR characters

  1237.       </ul>

  1238.       Default is based on the platform on which you are running this task.

  1239.       For Unix platforms, the default is remove.  For DOS based systems

  1240.       (including Windows), the default is add.

  1241.       <p>

  1242.       Note: Unless this property is specified as "asis", extra CR characters

  1243.       which do not preceed a LF will be removed.

  1244.       </td>

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

  1246.   </tr>

  1247.   <tr>

  1248.     <td valign="top">tab</td>

  1249.     <td valign="top">Specifies how tab characters are to be handled.  Valid

  1250.       values for this property are:

  1251.       <ul>

  1252.       <li>add: convert sequences of spaces which span a tab stop to tabs

  1253.       <li>asis: leave tab and space characters alone

  1254.       <li>remove: convert tabs to spaces

  1255.       </ul>

  1256.       Default for this parameter is "asis".

  1257.       <p>

  1258.       Note: Unless this property is specified as "asis", extra spaces and

  1259.       tabs after the last non-whitespace character on the line will be removed.

  1260.       </td>

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

  1262.   </tr>

  1263.   <tr>

  1264.     <td valign="top">tablength</td>

  1265.     <td valign="top">The number of characters a TAB stop corresponds to. 

  1266.       Must be a positive power of 2, default for this parameter is 8.</td>

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

  1268.   </tr>

  1269.   <tr>

  1270.     <td valign="top">eof</td>

  1271.     <td valign="top">Specifies how DOS end of file (control-Z) characters are

  1272.       to be handled.  Valid values for this property are:

  1273.       <ul>

  1274.       <li>add: ensure that there is an EOF character at the end of the file

  1275.       <li>asis: leave EOF characters alone

  1276.       <li>remove: remove any EOF character found at the end

  1277.       </ul>

  1278.       Default is based on the platform on which you are running this task.

  1279.       For Unix platforms, the default is remove.  For DOS based systems

  1280.       (including Windows), the default is asis.

  1281.       </td>

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

  1283.   </tr>

  1284. </table>

  1285. <h3>Examples</h3>

  1286. <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;

  1287.        cr=&quot;remove&quot; eof=&quot;remove&quot;

  1288.        includes=&quot;**/*.sh&quot;

  1289.   /&gt;</pre>

  1290. <p>Removes carriage return and eof characters from the shell scripts.  Tabs and

  1291. spaces are left as is.

  1292. <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;

  1293.        cr=&quot;add&quot;

  1294.        includes=&quot;**/*.bat&quot;

  1295.   /&gt;</pre>

  1296. <p>Ensures that there are carriage return characters prior to evey line feed.

  1297. Tabs and spaces are left as is.

  1298. EOF characters are left alone if run on

  1299. DOS systems, and are removed if run on Unix systems.</p>

  1300. <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;

  1301.        tabs=&quot;add&quot;

  1302.        includes=&quot;**/Makefile&quot;

  1303.   /&gt;</pre>

  1304. <p>Adds or removes CR characters to match local OS conventions, and

  1305. converts spaces to tabs when appropriate.  EOF characters are left alone if

  1306. run on DOS systems, and are removed if run on Unix systems.

  1307. Many versions of make require tabs prior to commands.</p>

  1308. <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;

  1309.        tabs=&quot;remove&quot;

  1310.        includes=&quot;**/README*&quot;

  1311.   /&gt;</pre>

  1312. <p>Adds or removes CR characters to match local OS conventions, and

  1313. converts all tabs to spaces.  EOF characters are left alone if run on

  1314. DOS systems, and are removed if run on Unix systems.

  1315. You never know what editor a user will use to browse README's.</p>

  1316. <hr>

  1317. <h2><a name="get">Get</a></h2>

  1318. <h3>Description</h3>

  1319. <p>Gets a file from an URL. When the verbose option is &quot;on&quot;, this task

  1320. displays a '.' for every 100 Kb retrieved.</p>

  1321. <p>This task should be preferred above the <a href="#cvs">CVS task</a> when

  1322. doing automated builds. CVS is significant slower than loading a compressed

  1323. archive with http/ftp.</p>

  1324. <h3>Parameters</h3>

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

  1326.   <tr>

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

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

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

  1330.   </tr>

  1331.   <tr>

  1332.     <td valign="top">src</td>

  1333.     <td valign="top">the URL from which to retrieve a file.</td>

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

  1335.   </tr>

  1336.   <tr>

  1337.     <td valign="top">dest</td>

  1338.     <td valign="top">the file where to store the retrieved file.</td>

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

  1340.   </tr>

  1341.   <tr>

  1342.     <td valign="top">verbose</td>

  1343.     <td valign="top">show verbose information (&quot;on&quot;/&quot;off&quot;).</td>

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

  1345.   </tr>

  1346.   <tr>

  1347.     <td valign="top">ignoreerrors</td>

  1348.     <td valign="top">Log errors but don't treat as fatal.</td>

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

  1350.   </tr>

  1351. </table>

  1352. <h3>Examples</h3>

  1353. <pre>  &lt;get src=&quot;http://jakarta.apache.org/&quot; dest=&quot;help/index.html&quot; /&gt;</pre>

  1354. <p>gets the index page of http://jakarta.apache.org/, and stores it in the file <code>help/index.html</code>.</p>

  1355. <hr>

  1356. <h2><a name="gunzip">GUnzip</a></h2>

  1357. <h3>Description</h3>

  1358. <p>Expands a GZip file.</p>

  1359. 

  1360. <p>If <i>dest</i> is a directory the name of the destination file is

  1361. the same as <i>src</i> (with the &quot;.gz&quot; extension removed if

  1362. present). If <i>dest</i> is ommited, the parent dir of <i>src</i> is

  1363. taken. The file is only expanded if the source file is newer than the

  1364. destination file, or when the destination file does not exist.</p>

  1365. 

  1366. <h3>Parameters</h3>

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

  1368.   <tr>

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

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

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

  1372.   </tr>

  1373.   <tr>

  1374.     <td valign="top">src</td>

  1375.     <td valign="top">the file to expand.</td>

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

  1377.   </tr>

  1378.   <tr>

  1379.     <td valign="top">dest</td>

  1380.     <td valign="top">the destination file or directory.</td>

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

  1382.   </tr>

  1383. </table>

  1384. <h3>Examples</h3>

  1385. <blockquote>

  1386.   <p><code>&lt;gunzip src=&quot;test.tar.gz&quot;/&gt;</code></p>

  1387. </blockquote>

  1388. <p>expands <i>test.tar.gz</i> to <i>test.tar</i></p>

  1389. <blockquote>

  1390.   <p><code>&lt;gunzip src=&quot;test.tar.gz&quot; dest=&quot;test2.tar&quot;/&gt;</code></p>

  1391. </blockquote>

  1392. <p>expands <i>test.tar.gz</i> to <i>test2.tar</i></p>

  1393. <blockquote>

  1394.   <p><code>&lt;gunzip src=&quot;test.tar.gz&quot; dest=&quot;subdir&quot;/&gt;</code></p>

  1395. </blockquote>

  1396. <p>expands <i>test.tar.gz</i> to <i>subdir/test.tar</i> (assuming

  1397. subdir is a directory).</p>

  1398. 

  1399. <hr>

  1400. <h2><a name="gzip">GZip</a></h2>

  1401. <h3>Description</h3>

  1402. <p>GZips a file.</p>

  1403. <h3>Parameters</h3>

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

  1405.   <tr>

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

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

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

  1409.   </tr>

  1410.   <tr>

  1411.     <td valign="top">src</td>

  1412.     <td valign="top">the file to gzip.</td>

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

  1414.   </tr>

  1415.   <tr>

  1416.     <td valign="top">zipfile</td>

  1417.     <td valign="top">the destination file.</td>

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

  1419.   </tr>

  1420. </table>

  1421. <h3>Examples</h3>

  1422. <blockquote>

  1423.   <p><code>&lt;gzip src=&quot;test.tar&quot; zipfile=&quot;test.tar.gz&quot;

  1424.   /&gt;</code></p>

  1425. </blockquote>

  1426. <hr>

  1427. <h2><a name="jar">Jar</a></h2>

  1428. <h3>Description</h3>

  1429. <p>Jars a set of files.</p>

  1430. <p>The <i>basedir</i> attribute is the reference directory from where to jar.</p>

  1431. <p>It is possible to refine the set of files that are being jarred. This can be

  1432. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  1433. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  1434. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  1435. the files you want to have excluded. This is also done with patterns. And

  1436. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  1437. want to use default exclusions or not. See the section on <a

  1438. href="#directorybasedtasks">directory based tasks</a>, on how the

  1439. inclusion/exclusion of files works, and how to write patterns. The patterns are

  1440. relative to the <i>basedir</i> directory.</p>

  1441. <p>The <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i> attributes

  1442. replace the <i>items</i> and <i>ignore</i> attributes. The following explains

  1443. how the deprecated <i>items</i> and <i>ignore</i> attribute behave.</p>

  1444. <p>When &quot;*&quot; is used for <i>items</i>, all files in the basedir, and

  1445. its subdirectories, will be jarred. Otherwise all the files and directories

  1446. mentioned in the items list will jarred. When a directory is specified, then all

  1447. files within it are also jarred.</p>

  1448. <p>With the <i>ignore</i> attribute, you can specify files or directories to

  1449. ignore. These files will not be jarred. The items in the <i>ignore</i> attribute

  1450. override the items in the <i>items</i> attribute. The names specified in the <i>ignore</i>

  1451. attribute are just names, they do not contain any path information!</p>

  1452. <h3>Parameters</h3>

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

  1454.   <tr>

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

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

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

  1458.   </tr>

  1459.   <tr>

  1460.     <td valign="top">jarfile</td>

  1461.     <td valign="top">the jar-file to create.</td>

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

  1463.   </tr>

  1464.   <tr>

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

  1466.     <td valign="top">the directory from which to jar the files.</td>

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

  1468.   </tr>

  1469.   <tr>

  1470.     <td valign="top">compress</td>

  1471.     <td valign="top">Not only store data but also compress them, defaults to true</td>

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

  1473.   </tr>

  1474.   <tr>

  1475.     <td valign="top">items</td>

  1476.     <td valign="top">a comma separated list of the files/directories to jar. All

  1477.       files are included when omitted. (<b>deprecated</b>, use <i>includes</i>

  1478.       instead).</td>

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

  1480.   </tr>

  1481.   <tr>

  1482.     <td valign="top">ignore</td>

  1483.     <td valign="top">comma separated list of filenames/directorynames to exclude

  1484.       from the jar. No files (except default excludes) are excluded when

  1485.       omitted. (<b>deprecated</b>, use <i>excludes</i> instead).</td>

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

  1487.   </tr>

  1488.   <tr>

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

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

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

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

  1493.   </tr>

  1494.   <tr>

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

  1496.     <td valign="top">the name of a file. Each line of this file is

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

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

  1499.   </tr>

  1500.   <tr>

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

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

  1503.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  1505.   </tr>

  1506.   <tr>

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

  1508.     <td valign="top">the name of a file. Each line of this file is

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

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

  1511.   </tr>

  1512.   <tr>

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

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

  1515.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  1517.   </tr>

  1518.   <tr>

  1519.     <td valign="top">manifest</td>

  1520.     <td valign="top">the manifest file to use.</td>

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

  1522.   </tr>

  1523. </table>

  1524. <h3>Examples</h3>

  1525. <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot; /&gt;</pre>

  1526. <p>jars all files in the <code>${build}/classes</code> directory in a file

  1527. called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>

  1528. <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;

  1529.        basedir=&quot;${build}/classes&quot;

  1530.        excludes=&quot;**/Test.class&quot;

  1531.   /&gt;</pre>

  1532. <p>jars all files in the <code>${build}/classes</code> directory in a file

  1533. called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Files

  1534. with the name <code>Test.class</code> are excluded.</p>

  1535. <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;

  1536.        basedir=&quot;${build}/classes&quot;

  1537.        includes=&quot;mypackage/test/**&quot;

  1538.        excludes=&quot;**/Test.class&quot;

  1539.   /&gt;</pre>

  1540. <p>jars all files in the <code>${build}/classes</code> directory in a file

  1541. called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Only

  1542. files under the directory <code>mypackage/test</code> are used, and files with

  1543. the name <code>Test.class</code> are excluded.</p>

  1544. <h3>Deprecated examples</h3>

  1545. <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot; items=&quot;*&quot; /&gt;</pre>

  1546. <p>jars all files in the <code>${build}/classes</code> directory in a file

  1547. called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>

  1548. <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot; items=&quot;*&quot; ignore=&quot;Test.class&quot; /&gt;</pre>

  1549. <p>jars all files in the <code>${build}/classes</code> directory in a file

  1550. called <code>app.jar</code> in the <code>${dist}/lib</code> directory.

  1551. Files/directories with the name <code>Test.class</code> are excluded.</p>

  1552. <hr>

  1553. <h2><a name="java">Java</a></h2>

  1554. <h3>Description</h3>

  1555. <p>Executes a Java class within the running (Ant) VM or forks another VM if

  1556. specified.</p>

  1557. <p>Be careful that the executed class doesn't call System.exit(), because it

  1558. will terminate the VM and thus Ant. In case this happens, it's highly suggested

  1559. that you set the fork attribute so that System.exit() stops the other VM and not

  1560. the one that is currently running Ant.</p>

  1561. <h3>Parameters</h3>

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

  1563.   <tr>

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

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

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

  1567.   </tr>

  1568.   <tr>

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

  1570.     <td valign="top">the Java class to execute.</td>

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

  1572.   </tr>

  1573.   <tr>

  1574.     <td valign="top">args</td>

  1575.     <td valign="top">the arguments for the class that is executed.</td>

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

  1577.   </tr>

  1578.   <tr>

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

  1580.     <td valign="top">the classpath to use.</td>

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

  1582.   </tr>

  1583.   <tr>

  1584.     <td valign="top">fork</td>

  1585.     <td valign="top">if enabled triggers the class execution in another VM

  1586.       (disabled by default)</td>

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

  1588.   </tr>

  1589.   <tr>

  1590.     <td valign="top">jvm</td>

  1591.     <td valign="top">the command used to invoke the Java Virtual Machine,

  1592.       default is 'java'.  The command is resolved by java.lang.Runtime.exec().

  1593.       Ignored if fork is disabled.

  1594.     </td>

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

  1596.   </tr>

  1597.   <tr>

  1598.     <td valign="top">jvmargs</td>

  1599.     <td valign="top">the arguments to pass to the forked VM (ignored if fork is

  1600.       disabled)</td>

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

  1602.   </tr>

  1603.   <tr>

  1604.     <td valign="top">failonerror</td>

  1605.     <td valign="top">Stop the buildprocess if the command exits with a

  1606.       returncode other than 0. Only available if fork is true.</td>

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

  1608.   </tr>

  1609. </table>

  1610. <h3>Examples</h3>

  1611. <pre>  &lt;java classname=&quot;test.Main&quot; /&gt;</pre>

  1612. <pre>  &lt;java classname=&quot;test.Main&quot; args=&quot;-h&quot; /&gt;</pre>

  1613. <pre>  &lt;java classname=&quot;test.Main&quot;

  1614.         args=&quot;-h&quot;

  1615.         fork=&quot;yes&quot;

  1616.         jvmargs=&quot;-Xrunhprof:cpu=samples,file=log.txt,depth=3&quot;

  1617.   /&gt;</pre>

  1618. 

  1619. <hr>

  1620. <h2><a name="javac">Javac</a></h2>

  1621. <h3>Description</h3>

  1622. <p>Compiles a source tree within the running (Ant) VM.</p>

  1623. <p>The source and destination directory will be recursively scanned for Java

  1624. source files to compile. Only Java files that have no corresponding class file

  1625. or where the class file is older than the java file will be compiled.</p>

  1626. <p>Files in the source tree, that are no java files, are copied to the

  1627. destination directory, allowing support files to be located properly in the

  1628. classpath.</p>

  1629. <p>The directory structure of the source tree should follow the package

  1630. hierarchy.</p>

  1631. <p>It is possible to refine the set of files that are being compiled/copied.

  1632. This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  1633. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  1634. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  1635. the files you want to have excluded. This is also done with patterns. And

  1636. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  1637. want to use default exclusions or not. See the section on <a

  1638. href="#directorybasedtasks">directory based tasks</a>, on how the

  1639. inclusion/exclusion of files works, and how to write patterns. The patterns are

  1640. relative to the <i>srcdir</i> directory.</p>

  1641. <p>It is possible to use different compilers. This can be selected with the

  1642. &quot;build.compiler&quot; property. There are three choices:</p>

  1643. <ul>

  1644.   <li>classic (the standard compiler of JDK 1.1/1.2)</li>

  1645.   <li>modern (the new compiler of JDK 1.3)</li>

  1646.   <li>jikes (the <a

  1647.     href="http://oss.software.ibm.com/developerworks/opensource/jikes/project">Jikes</a>

  1648.     compiler)</li>

  1649. </ul>

  1650. <p>For JDK 1.1/1.2 is classic the default. For JDK 1.3 is modern the default.</p>

  1651. <h3>Parameters</h3>

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

  1653.   <tr>

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

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

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

  1657.   </tr>

  1658.   <tr>

  1659.     <td valign="top">srcdir</td>

  1660.     <td valign="top">location of the java files.</td>

  1661.     <td align="center" valign="top">Yes, unless nested <code>&lt;src&gt;</code> elements are present.</td>

  1662.   </tr>

  1663.   <tr>

  1664.     <td valign="top">destdir</td>

  1665.     <td valign="top">location where to store the class files.</td>

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

  1667.   </tr>

  1668.   <tr>

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

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

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

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

  1673.   </tr>

  1674.   <tr>

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

  1676.     <td valign="top">the name of a file. Each line of this file is

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

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

  1679.   </tr>

  1680.   <tr>

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

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

  1683.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  1685.   </tr>

  1686.   <tr>

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

  1688.     <td valign="top">the name of a file. Each line of this file is

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

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

  1691.   </tr>

  1692.   <tr>

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

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

  1695.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  1697.   </tr>

  1698.   <tr>

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

  1700.     <td valign="top">the classpath to use.</td>

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

  1702.   </tr>

  1703.   <tr>

  1704.     <td valign="top">bootclasspath</td>

  1705.     <td valign="top">location of bootstrap class files.</td>

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

  1707.   </tr>

  1708.   <tr>

  1709.     <td valign="top">extdirs</td>

  1710.     <td valign="top">location of installed extensions.</td>

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

  1712.   </tr>

  1713.   <tr>

  1714.     <td valign="top">debug</td>

  1715.     <td valign="top">indicates whether there should be compiled with debug

  1716.       information (&quot;on&quot;).</td>

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

  1718.   </tr>

  1719.   <tr>

  1720.     <td valign="top">optimize</td>

  1721.     <td valign="top">indicates whether there should be compiled with

  1722.       optimization (&quot;on&quot;).</td>

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

  1724.   </tr>

  1725.   <tr>

  1726.     <td valign="top">deprecation</td>

  1727.     <td valign="top">indicates whether there should be compiled with deprecation

  1728.       information (&quot;on&quot;).</td>

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

  1730.   </tr>

  1731.   <tr>

  1732.     <td valign="top">filtering</td>

  1733.     <td valign="top">indicates whether token filtering should take place</td>

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

  1735.   </tr>

  1736.   <tr>

  1737.     <td valign="top">target</td>

  1738.     <td valign="top">Generate class files for specific VM version, e.g. "1.1" or "1.2".</td>

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

  1740.   </tr>

  1741. </table>

  1742. 

  1743. <h3>Parameters specified as nested elements</h3>

  1744. Being a directory based task, Javac supports the <code>&lt;include&gt;</code> and 

  1745. <code>&lt;exclude&gt;</code> nested elements common to a number of Ant tasks. Javac also supports a 

  1746. nested <code>&lt;src&gt;</code> element. This is used to specify multiple source paths. 

  1747. Multiple <code>src</code> elements may be present and each specifies a source path which will be 

  1748. searched by Javac for classes to compile.

  1749. 

  1750. <h4>src</h4>

  1751. Define a source path to be search for source files.

  1752. <H4>Parameters</h4>

  1753. <table width="60%" border="1" cellpadding="2" cellspacing="0">

  1754.   <tr>

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

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

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

  1758.   </tr>

  1759.   <tr>

  1760.     <td valign="top">src</td>

  1761.     <td valign="top">A source path. It may contain multiple elements separated with either a ';' or a ':'</td>

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

  1763.   </tr>

  1764. </table>

  1765. 

  1766. <h3>Examples</h3>

  1767. <pre>  &lt;javac srcdir=&quot;${src}&quot;

  1768.          destdir=&quot;${build}&quot;

  1769.          classpath=&quot;xyz.jar&quot;

  1770.          debug=&quot;on&quot;

  1771.   /&gt;</pre>

  1772. <p>compiles all .java files under the directory <code>${src}</code>, and stores

  1773. the .class files in the directory <code>${build}</code>. It also copies the non-java

  1774. files from the tree under <code>${src}</code> to the tree under <code>${build}</code>.

  1775. The classpath used contains <code>xyz.jar</code>, and debug information is on.</p>

  1776. <pre>  &lt;javac srcdir=&quot;${src}&quot;

  1777.          destdir=&quot;${build}&quot;

  1778.          includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;

  1779.          excludes=&quot;mypackage/p1/testpackage/**&quot;

  1780.          classpath=&quot;xyz.jar&quot;

  1781.          debug=&quot;on&quot;

  1782.   /&gt;</pre>

  1783. <p>compiles .java files under the directory <code>${src}</code>, and stores the

  1784. .class files in the directory <code>${build}</code>. It also copies the non-java

  1785. files from the tree under <code>${src}</code> to the tree under <code>${build}</code>.

  1786. The classpath used contains <code>xyz.jar</code>, and debug information is on.

  1787. Only files under <code>mypackage/p1</code> and <code>mypackage/p2</code> are

  1788. used. Files in the <code>mypackage/p1/testpackage</code> directory are excluded

  1789. form compilation and copy.</p>

  1790. 

  1791. <pre>  &lt;javac srcdir=&quot;${src}:${src2}&quot;

  1792.          destdir=&quot;${build}&quot;

  1793.          includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;

  1794.          excludes=&quot;mypackage/p1/testpackage/**&quot;

  1795.          classpath=&quot;xyz.jar&quot;

  1796.          debug=&quot;on&quot;

  1797.   /&gt;</pre>

  1798. 

  1799. <p>is the same as the previous example with the addition of a second source path, defined by

  1800. the propery <code>src2</code>. This can also be represented using nested elements as follows

  1801. 

  1802. <pre>  &lt;javac destdir=&quot;${build}&quot;

  1803.          classpath=&quot;xyz.jar&quot;

  1804.          debug=&quot;on&quot;&gt;

  1805.     &lt;src path=&quot;${src}&quot; /&gt;

  1806.     &lt;src path=&quot;${src2}&quot; /&gt;

  1807.     &lt;include name=&quot;mypackage/p1/**,mypackage/p2/**&quot; /&gt;

  1808.     &lt;exclude name=&quot;mypackage/p1/testpackage/**&quot; /&gt;

  1809.   &lt;/javac&gt;</pre>

  1810. 

  1811. <hr>

  1812. <h2><a name="javadoc">Javadoc/Javadoc2</a></h2>

  1813. <h3>Description</h3>

  1814. <p>Generates code documentation using the javadoc tool.</p>

  1815. <p>The source directory will be recursively scanned for Java source files to process

  1816. but only those matching the inclusion rules will be passed to the javadoc tool. This

  1817. allows wildcards to be used to choose between package names, reducing verbosity

  1818. and management costs over time. This task, however, has no notion of

  1819. &quot;changed&quot; files, unlike the <a href="#javac">javac</a> task. This means

  1820. all packages will be processed each time this task is run. In general, however,

  1821. this task is used much less frequently.</p>

  1822. <p>This task works seamlessly between different javadoc versions (1.1 and 1.2),

  1823. with the obvious restriction that the 1.2 attributes will be ignored if run in a

  1824. 1.1 VM.</p>

  1825. <p>NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the

  1826. same VM as ant without breaking functionality. For this reason, this task 

  1827. always forks the VM. This overhead is not significant since javadoc is normally a heavy

  1828. application and will be called infrequently.</p>

  1829. <p>NOTE: the packagelist attribute allows you to specify the list of packages to 

  1830. document outside of the Ant file. It's a much better practice to include everything 

  1831. inside the build.xml file. This option was added in order to make it easier to 

  1832. migrate from regular makefiles, where you would use this option of javadoc. 

  1833. The packages listed in packagelist are not checked, so the task performs even 

  1834. if some packages are missing or broken. Use this option if you wish to convert from 

  1835. an existing makefile. Once things are running you should then switch to the regular 

  1836. notation. 

  1837. 

  1838. <p>DEPRECATION: the javadoc2 task simply points to the javadoc task and it's

  1839. there for back compatibility reasons. Since this task will be removed in future

  1840. versions, you are strongly encouraged to use <a href="#javadoc">javadoc</a>

  1841. instead.</p>

  1842. <h3>Parameters</h3>

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

  1844.   <tr>

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

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

  1847.     <td align="center" valign="top"><b>Availability</b></td>

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

  1849.   </tr>

  1850.   <tr>

  1851.     <td valign="top">sourcepath</td>

  1852.     <td valign="top">Specify where to find source files</td>

  1853.     <td align="center" valign="top">all</td>

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

  1855.   </tr>

  1856.   <tr>

  1857.     <td valign="top">destdir</td>

  1858.     <td valign="top">Destination directory for output files</td>

  1859.     <td align="center" valign="top">all</td>

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

  1861.   </tr>

  1862.   <tr>

  1863.     <td valign="top">maxmemory</td>

  1864.     <td valign="top">Max amount of memory to allocate to the javadoc VM</td>

  1865.     <td align="center" valign="top">all</td>

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

  1867.   </tr>

  1868.   <tr>

  1869.     <td valign="top">sourcefiles</td>

  1870.     <td valign="top">Space separated list of source files</td>

  1871.     <td align="center" valign="top">all</td>

  1872.     <td align="center" valign="middle" rowspan="2">at least one of the two</td>

  1873.   </tr>

  1874.   <tr>

  1875.     <td valign="top">packagenames</td>

  1876.     <td valign="top">Space separated list of package files (with terminating

  1877.       wildcard)</td>

  1878.     <td align="center" valign="top">all</td>

  1879.   </tr>

  1880.   <tr>

  1881.     <td valign="top">packageList</td>

  1882.     <td valign="top">The name of a file containing the packages to process</td>

  1883.     <td align="center" valign="top">all</td>

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

  1885.   </tr>

  1886.   <tr>

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

  1888.     <td valign="top">Specify where to find user class files</td>

  1889.     <td align="center" valign="top">all</td>

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

  1891.   </tr>

  1892.   <tr>

  1893.     <td valign="top">Bootclasspath</td>

  1894.     <td valign="top">Override location of class files loaded by the bootstrap

  1895.       class loader</td>

  1896.     <td align="center" valign="top">1.2</td>

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

  1898.   </tr>

  1899.   <tr>

  1900.     <td valign="top">Extdirs</td>

  1901.     <td valign="top">Override location of installed extensions</td>

  1902.     <td align="center" valign="top">1.2</td>

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

  1904.   </tr>

  1905.   <tr>

  1906.     <td valign="top">Overview</td>

  1907.     <td valign="top">Read overview documentation from HTML file</td>

  1908.     <td align="center" valign="top">1.2</td>

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

  1910.   </tr>

  1911.   <tr>

  1912.     <td valign="top">Public</td>

  1913.     <td valign="top">Show only public classes and members</td>

  1914.     <td align="center" valign="top">all</td>

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

  1916.   </tr>

  1917.   <tr>

  1918.     <td valign="top">Protected</td>

  1919.     <td valign="top">Show protected/public classes and members (default)</td>

  1920.     <td align="center" valign="top">all</td>

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

  1922.   </tr>

  1923.   <tr>

  1924.     <td valign="top">Package</td>

  1925.     <td valign="top">Show package/protected/public classes and members</td>

  1926.     <td align="center" valign="top">all</td>

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

  1928.   </tr>

  1929.   <tr>

  1930.     <td valign="top">Private</td>

  1931.     <td valign="top">Show all classes and members</td>

  1932.     <td align="center" valign="top">all</td>

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

  1934.   </tr>

  1935.   <tr>

  1936.     <td valign="top">Old</td>

  1937.     <td valign="top">Generate output using JDK 1.1 emulating doclet</td>

  1938.     <td align="center" valign="top">1.2</td>

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

  1940.   </tr>

  1941.   <tr>

  1942.     <td valign="top">Verbose</td>

  1943.     <td valign="top">Output messages about what Javadoc is doing</td>

  1944.     <td align="center" valign="top">1.2</td>

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

  1946.   </tr>

  1947.   <tr>

  1948.     <td valign="top">Locale</td>

  1949.     <td valign="top">Locale to be used, e.g. en_US or en_US_WIN</td>

  1950.     <td align="center" valign="top">1.2</td>

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

  1952.   </tr>

  1953.   <tr>

  1954.     <td valign="top">Encoding</td>

  1955.     <td valign="top">Source file encoding name</td>

  1956.     <td align="center" valign="top">all</td>

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

  1958.   </tr>

  1959.   <tr>

  1960.     <td valign="top">Version</td>

  1961.     <td valign="top">Include @version paragraphs</td>

  1962.     <td align="center" valign="top">all</td>

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

  1964.   </tr>

  1965.   <tr>

  1966.     <td valign="top">Use</td>

  1967.     <td valign="top">Create class and package usage pages</td>

  1968.     <td align="center" valign="top">1.2</td>

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

  1970.   </tr>

  1971.   <tr>

  1972.     <td valign="top">Author</td>

  1973.     <td valign="top">Include @author paragraphs</td>

  1974.     <td align="center" valign="top">all</td>

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

  1976.   </tr>

  1977.   <tr>

  1978.     <td valign="top">Splitindex</td>

  1979.     <td valign="top">Split index into one file per letter</td>

  1980.     <td align="center" valign="top">1.2</td>

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

  1982.   </tr>

  1983.   <tr>

  1984.     <td valign="top">Windowtitle</td>

  1985.     <td valign="top">Browser window title for the documenation (text)</td>

  1986.     <td align="center" valign="top">1.2</td>

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

  1988.   </tr>

  1989.   <tr>

  1990.     <td valign="top">Doctitle</td>

  1991.     <td valign="top">Include title for the package index(first) page (html-code)</td>

  1992.     <td align="center" valign="top">1.2</td>

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

  1994.   </tr>

  1995.   <tr>

  1996.     <td valign="top">Header</td>

  1997.     <td valign="top">Include header text for each page (html-code)</td>

  1998.     <td align="center" valign="top">1.2</td>

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

  2000.   </tr>

  2001.   <tr>

  2002.     <td valign="top">Footer</td>

  2003.     <td valign="top">Include footer text for each page (html-code)</td>

  2004.     <td align="center" valign="top">1.2</td>

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

  2006.   </tr>

  2007.   <tr>

  2008.     <td valign="top">bottom</td>

  2009.     <td valign="top">Include bottom text for each page (html-code)</td>

  2010.     <td align="center" valign="top">1.2</td>

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

  2012.   </tr>

  2013.   <tr>

  2014.     <td valign="top">link</td>

  2015.     <td valign="top">Create links to javadoc output at the given URL</td>

  2016.     <td align="center" valign="top">1.2</td>

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

  2018.   </tr>

  2019.   <tr>

  2020.     <td valign="top">linkoffline</td>

  2021.     <td valign="top">Link to docs at &lt;url&gt; using package list at

  2022.       &lt;url2&gt;</td>

  2023.     <td align="center" valign="top">1.2</td>

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

  2025.   </tr>

  2026.   <tr>

  2027.     <td valign="top">group</td>

  2028.     <td valign="top">Group specified packages together in overview page</td>

  2029.     <td align="center" valign="top">1.2</td>

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

  2031.   </tr>

  2032.   <tr>

  2033.     <td valign="top">nodeprecated</td>

  2034.     <td valign="top">Do not include @deprecated information</td>

  2035.     <td align="center" valign="top">all</td>

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

  2037.   </tr>

  2038.   <tr>

  2039.     <td valign="top">nodeprecatedlist</td>

  2040.     <td valign="top">Do not generate deprecated list</td>

  2041.     <td align="center" valign="top">1.2</td>

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

  2043.   </tr>

  2044.   <tr>

  2045.     <td valign="top">notree</td>

  2046.     <td valign="top">Do not generate class hierarchy</td>

  2047.     <td align="center" valign="top">all</td>

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

  2049.   </tr>

  2050.   <tr>

  2051.     <td valign="top">noindex</td>

  2052.     <td valign="top">Do not generate index</td>

  2053.     <td align="center" valign="top">all</td>

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

  2055.   </tr>

  2056.   <tr>

  2057.     <td valign="top">nohelp</td>

  2058.     <td valign="top">Do not generate help link</td>

  2059.     <td align="center" valign="top">1.2</td>

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

  2061.   </tr>

  2062.   <tr>

  2063.     <td valign="top">nonavbar</td>

  2064.     <td valign="top">Do not generate navigation bar</td>

  2065.     <td align="center" valign="top">1.2</td>

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

  2067.   </tr>

  2068.   <tr>

  2069.     <td valign="top">serialwarn</td>

  2070.     <td valign="top">FUTURE: Generate warning about @serial tag</td>

  2071.     <td align="center" valign="top">1.2</td>

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

  2073.   </tr>

  2074.   <tr>

  2075.     <td valign="top">helpfile</td>

  2076.     <td valign="top">FUTURE: Specifies the HTML help file to use</td>

  2077.     <td align="center" valign="top">1.2</td>

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

  2079.   </tr>

  2080.   <tr>

  2081.     <td valign="top">stylesheetfile</td>

  2082.     <td valign="top">Specifies the CSS stylesheet to use</td>

  2083.     <td align="center" valign="top">1.2</td>

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

  2085.   </tr>

  2086.   <tr>

  2087.     <td valign="top">charset</td>

  2088.     <td valign="top">FUTURE: Charset for cross-platform viewing of generated

  2089.       documentation</td>

  2090.     <td align="center" valign="top">1.2</td>

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

  2092.   </tr>

  2093.   <tr>

  2094.     <td valign="top">docencoding</td>

  2095.     <td valign="top">Output file encoding name</td>

  2096.     <td align="center" valign="top">1.1</td>

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

  2098.   </tr>

  2099.   <tr>

  2100.     <td valign="top">doclet</td>

  2101.     <td valign="top">Specifies the class file that starts the doclet used in generating the documentation.</td>

  2102.     <td align="center" valign="top">1.2</td>

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

  2104.   </tr>

  2105.   <tr>

  2106.     <td valign="top">docletpath</td>

  2107.     <td valign="top">Specifies the path to the doclet class file that is specified with the -doclet option.</td>

  2108.     <td align="center" valign="top">1.2</td>

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

  2110.   </tr>

  2111.   <tr>

  2112.     <td valign="top">additionalparam</td>

  2113.     <td valign="top">Lets you add additional parameters to the javadoc command line. Useful for doclets</td>

  2114.     <td align="center" valign="top">1.2</td>

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

  2116.   </tr>

  2117.   <tr>

  2118.     <td valign="top">failonerror</td>

  2119.     <td valign="top">Stop the buildprocess if the command exits with a

  2120.       returncode other than 0.</td>

  2121.     <td align="center" valign="top">all</td>

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

  2123.   </tr>

  2124. </table>

  2125. 

  2126. <h3>Parameters specified as nested elements</h3>

  2127. Two parameters of the Javadoc task may be specified as nested elements of the

  2128. Javadoc task element: link and group.

  2129. When present, there can be any number of each of these elements.

  2130. They perform the same role as the link, linkoffline and

  2131. group attributes. You can use either syntax (or both at once), but with the  nested 

  2132. elements you can easily specify multiple occurrences of the arguments.

  2133. <h4>link</h4>

  2134. Create link to javadoc output at the given URL

  2135. <h4>Parameters</h4>

  2136. 

  2137. <table width="60%" border="1" cellpadding="2" cellspacing="0">

  2138.   <tr>

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

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

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

  2142.   </tr>

  2143.   <tr>

  2144.     <td valign="top">href</td>

  2145.     <td valign="top">The URL for the external documentation you wish to link to</td>

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

  2147.   </tr>

  2148.   <tr>

  2149.     <td valign="top">offline</td>

  2150.     <td valign="top">True if this link is not available online at the time of 

  2151.                      generating the documentation</td>

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

  2153.   </tr>

  2154.   <tr>

  2155.     <td valign="top">packagelistLoc</td>

  2156.     <td valign="top">The location to the directory containing the package-list file for

  2157.                      the external documentation</td>

  2158.     <td align="center" valign="top">Only if the offline attribute is true</td>

  2159.   </tr>

  2160. </table>

  2161.   

  2162. <h4>groups</h4>

  2163. Separates packages on the overview page into whatever groups you specify,

  2164. one group per table.

  2165. 

  2166. <table width="60%" border="1" cellpadding="2" cellspacing="0">

  2167.   <tr>

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

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

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

  2171.   </tr>

  2172.   <tr>

  2173.     <td valign="top">title</td>

  2174.     <td valign="top">Title of the group</td>

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

  2176.   </tr>

  2177.   <tr>

  2178.     <td valign="top">packages</td>

  2179.     <td valign="top">List of packages to include in that group</td>

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

  2181.   </tr>

  2182. </table>

  2183. 

  2184. <h3>Example</h3>

  2185. <pre>  &lt;javadoc packagenames=&quot;com.dummy.test.*&quot;

  2186.            sourcepath=&quot;src&quot;

  2187.            destdir=&quot;docs/api&quot;

  2188.            author=&quot;true&quot;

  2189.            version=&quot;true&quot;

  2190.            use=&quot;true&quot;

  2191.            windowtitle=&quot;Test API&quot;

  2192.            doctitle=&quot;&lt;h1&gt;Test&lt;/h1&gt;&quot;

  2193.            bottom=&quot;&lt;i&gt;Copyright &amp;#169; 2000 Dummy Corp. All Rights Reserved.&lt;/i&gt;&quot;&gt;

  2194.     &lt;group title=&quot;Group 1 Packages&quot; packages=&quot;com.dummy.test.a*&quot;/&gt;

  2195.     &lt;group title=&quot;Group 2 Packages&quot; packages=&quot;com.dummy.test.b*&quot;/&gt;

  2196.     &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;

  2197.     &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;

  2198.   &lt/javadoc&gt;</pre>

  2199.   

  2200. <hr>

  2201. <h2><a name="keysubst">KeySubst</a></h2>

  2202. <h3>Description</h3>

  2203. <p>Performs keyword substitution in the source file, and writes the result to

  2204. the destination file.</p>

  2205. <p>Keys in the source file are of the form ${keyname}. The <i>keys</i> attribute

  2206. contains key/value pairs. When a key is found in the <i>keys</i> attribute, then

  2207. &quot;${keyname}&quot; is replaced by the corresponding value.</p>

  2208. <p>The <i>keys</i> attribute is of the form

  2209. &quot;name1=value1*name2=value2*name3=value3&quot;. The '*' is called the

  2210. separator, which might we changed with the <i>sep</i> attribute.</p>

  2211. <p>Note: the source file and destination file may not be the same.</p>

  2212. <h3>Parameters</h3>

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

  2214.   <tr>

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

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

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

  2218.   </tr>

  2219.   <tr>

  2220.     <td valign="top">src</td>

  2221.     <td valign="top">the source file.</td>

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

  2223.   </tr>

  2224.   <tr>

  2225.     <td valign="top">dest</td>

  2226.     <td valign="top">the destination file.</td>

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

  2228.   </tr>

  2229.   <tr>

  2230.     <td valign="top">sep</td>

  2231.     <td valign="top">the separator for the name/value pairs.</td>

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

  2233.   </tr>

  2234.   <tr>

  2235.     <td valign="top">keys</td>

  2236.     <td valign="top">name/value pairs for replacement.</td>

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

  2238.   </tr>

  2239. </table>

  2240. <h3>Examples</h3>

  2241. <pre>  &lt;keysubst src=&quot;abc.txt&quot; dest=&quot;def.txt&quot; keys=&quot;VERSION=1.0.3*DATE=2000-01-10&quot; /&gt;</pre>

  2242. <hr>

  2243. <h2><a name="mkdir">Mkdir</a></h2>

  2244. <h3>Description</h3>

  2245. <p>Creates a directory. Also non-existent parent directories are created, when

  2246. necessary.</p>

  2247. <h3>Parameters</h3>

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

  2249.   <tr>

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

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

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

  2253.   </tr>

  2254.   <tr>

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

  2256.     <td valign="top">the directory to create.</td>

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

  2258.   </tr>

  2259. </table>

  2260. <h3>Examples</h3>

  2261. <pre>&lt;mkdir dir=&quot;${dist}&quot; /&gt;</pre>

  2262. <p>creates a directory <code>${dist}</code>.</p>

  2263. <pre>&lt;mkdir dir=&quot;${dist}/lib&quot; /&gt;</pre>

  2264. <p>creates a directory <code>${dist}/lib</code>.</p>

  2265. <hr>

  2266. <h2><a name="patch">Patch</a></h2>

  2267. <h3>Description</h3>

  2268. <p>Applies a diff file to originals.

  2269. <h3>Parameters</h3>

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

  2271.   <tr>

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

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

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

  2275.   </tr>

  2276.   <tr>

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

  2278.     <td valign="top">the directory in which the command should be executed.</td>

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

  2280.   </tr>

  2281.   <tr>

  2282.     <td valign="top">os</td>

  2283.     <td valign="top">list of Operating Systems on which the command may be

  2284.       executed.</td>

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

  2286.   </tr>

  2287.   <tr>

  2288.     <td valign="top">output</td> 

  2289.     <td valign="top">the file to which the output of the patch command 

  2290.       should be redirected.</td> 

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

  2292.   </tr>

  2293.   <tr>

  2294.     <td valign="top">patchfile</td> 

  2295.     <td valign="top">the file that includes the diff output</td>

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

  2297.   </tr>

  2298.   <tr>

  2299.     <td valign="top">originalfile</td> 

  2300.     <td valign="top">the file to patch</td>

  2301.     <td align="center" valign="top">No, tries to guess it from the diff 

  2302.       file</td>

  2303.   </tr>

  2304.   <tr>

  2305.     <td valign="top">backups</td> 

  2306.     <td valign="top">Keep backups of the unpatched files</td>

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

  2308.   </tr>

  2309.   <tr>

  2310.     <td valign="top">quiet</td> 

  2311.     <td valign="top">Work silently unless an error occurs</td>

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

  2313.   </tr>

  2314.   <tr>

  2315.     <td valign="top">reverse</td> 

  2316.     <td valign="top">Assume patch was created with old and new files 

  2317.       swapped.</td>

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

  2319.   </tr>

  2320.   <tr>

  2321.     <td valign="top">ignorewhitespace</td> 

  2322.     <td valign="top">Ignore whitespace differences.</td>

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

  2324.   </tr>

  2325.   <tr>

  2326.     <td valign="top">strip</td> 

  2327.     <td valign="top">Strip the smallest prefix containing <i>num</i> leading 

  2328.       slashes from filenames.</td>

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

  2330.   </tr>

  2331.   <tr>

  2332.     <td valign="top">failonerror</td>

  2333.     <td valign="top">Stop the buildprocess if the command exits with a

  2334.       returncode other than 0.</td>

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

  2336.   </tr>

  2337. </table>

  2338. <h3>Examples</h3>

  2339. <pre>  &lt;patch patchfile=&quot;module.1.0-1.1.patch&quot; /&gt;</pre>

  2340. <p>applies the diff included in <i>module.1.0-1.1.patch</i> to the

  2341. files in base directory guessing the filename(s) from the diff output.

  2342. <pre>  &lt;patch patchfile=&quot;module.1.0-1.1.patch&quot; strip="1" /&gt;</pre>

  2343. <p>like above but one leading directory part will be removed. i.e. if

  2344. the diff output looked like

  2345. <pre>

  2346. --- a/mod1.0/A	Mon Jun  5 17:28:41 2000

  2347. +++ a/mod1.1/A	Mon Jun  5 17:28:49 2000

  2348. </pre> 

  2349. the leading <i>a/</i> will be stripped.

  2350. <h2><a name="property">Property</a></h2>

  2351. <h3>Description</h3>

  2352. <p>Sets a property (by name and value), or set of properties (from file or

  2353. resource) in the project.</p>

  2354. <p>When a property was set by the user, or was a property in a parent project

  2355. (that started this project with the <a href="#ant">ant task</a>), then this

  2356. property cannot be set, and will be ignored. This means that properties set

  2357. outside the current project always override the properties of the current

  2358. project.</p>

  2359. <p>There are three ways to set properties:</p>

  2360. <ul>

  2361.   <li>By supplying both the <i>name</i> and <i>value</i> attribute.</li>

  2362.   <li>By setting the <i>file</i> attribute with the filename of the property

  2363.     file to load. This property file has the format as defined by the file used

  2364.     in the class java.util.Properties.</li>

  2365.   <li>By setting the <i>resource</i> attribute with the resource name of the

  2366.     property file to load. This property file has the format as defined by the

  2367.     file used in the class java.util.Properties.</li>

  2368. </ul>

  2369. <p>Although combinations of the three ways are possible, only one should be used

  2370. at a time. Problems might occur with the order in which properties are set, for

  2371. instance.</p>

  2372. <p>The value part of the properties being set, might contain references to other

  2373. properties. These references are resolved at the time these properties are set.

  2374. This also holds for properties loaded from a property file.</p>

  2375. <h3>Parameters</h3>

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

  2377.   <tr>

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

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

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

  2381.   </tr>

  2382.   <tr>

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

  2384.     <td valign="top">the name of the property to set.</td>

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

  2386.   </tr>

  2387.   <tr>

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

  2389.     <td valign="top">the value of the property.</td>

  2390.     <td valign="middle" align="center" rowspan="3">Yes</td>

  2391.   </tr>

  2392.   <tr>

  2393.     <td valign="top">resource</td>

  2394.     <td valign="top">the resource name of the property file.</td>

  2395.   </tr>

  2396.   <tr>

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

  2398.     <td valign="top">the filename of the property file .</td>

  2399.   </tr>

  2400. </table>

  2401. <h3>Examples</h3>

  2402. <pre>  &lt;property name=&quot;foo.dist&quot; value=&quot;dist&quot; /&gt;</pre>

  2403. <p>sets the property <code>foo.dist</code> to the value &quot;dist&quot;.</p>

  2404. <pre>  &lt;property file=&quot;foo.properties&quot; /&gt;</pre>

  2405. <p>reads a set of properties from a file called &quot;foo.properties&quot;.</p>

  2406. <pre>  &lt;property resource=&quot;foo.properties&quot; /&gt;</pre>

  2407. <p>reads a set of properties from a resource called &quot;foo.properties&quot;.</p>

  2408. <p>Note that you can reference a global properties file for all of your Ant

  2409. builds using the following:

  2410. <pre>  &lt;property file=&quot;${user.home}/.ant-global.properties&quot; /&gt;</pre>

  2411. <p>since the &quot;user.home&quot; property is defined by the Java virtual machine

  2412. to be your home directory.  This technique is more appropriate for Unix than 

  2413. Windows since the notion of a home directory doesn't exist on Windows.  On the

  2414. JVM that I tested, the home directory on Windows is &quot;C:\&quot;.  Different JVM

  2415. implementations may use other values for the home directory on Windows.

  2416. <hr>

  2417. <h2><a name="rename">Rename</a></h2>

  2418. <h3>Description</h3>

  2419. <p>Renames a given file.</p>

  2420. <h3>Parameters</h3>

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

  2422.   <tr>

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

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

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

  2426.   </tr>

  2427.   <tr>

  2428.     <td valign="top">src</td>

  2429.     <td valign="top">file to rename.</td>

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

  2431.   </tr>

  2432.   <tr>

  2433.     <td valign="top">dest</td>

  2434.     <td valign="top">new name of the file.</td>

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

  2436.   </tr>

  2437.   <tr>

  2438.     <td valign="top">replace</td>

  2439.     <td valign="top">Enable replacing of existing file (default: on).</td>

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

  2441.   </tr>

  2442. </table>

  2443. <h3>Examples</h3>

  2444. <pre>  &lt;rename src=&quot;foo.jar&quot; dest=&quot;${name}-${version}.jar&quot; /&gt;</pre> 

  2445. <p>Renames the file <code>foo.jar</code> to <code>${name}-${version}.jar</code> (assuming <code>name</code>

  2446.  and <code>version</code> being predefined properties). If a file named <code>${name}-${version}.jar</code>

  2447.  already exists, it will be removed prior to renameing <code>foo.jar</code>.</p>

  2448. <hr>

  2449. <h2><a name="replace">Replace</a></h2>

  2450. <h3>Description</h3>

  2451. <p>Replace is a directory based task for replacing the occurrence of a given string with another string 

  2452. in selected file.</p>

  2453. <h3>Parameters</h3>

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

  2455.   <tr>

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

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

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

  2459.   </tr>

  2460.   <tr>

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

  2462.     <td valign="top">file for which the token should be replaced. If not present the dir attribute 

  2463.                      must be specified</td>

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

  2465.   </tr>

  2466.   <tr>

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

  2468.     <td valign="top">The base directory to use when replacing a token in multiple files. If not present the file attribute

  2469.                      must be specified</td>

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

  2471.   </tr>

  2472.   <tr>

  2473.     <td valign="top">token</td>

  2474.     <td valign="top">the token which must be replaced.</td>

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

  2476.   </tr>

  2477.   <tr>

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

  2479.     <td valign="top">the new value for the token. When omitted, an empty string

  2480.       (&quot;&quot;) is used.</td>

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

  2482.   </tr>

  2483.   <tr>

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

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

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

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

  2488.   </tr>

  2489.   <tr>

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

  2491.     <td valign="top">the name of a file. Each line of this file is

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

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

  2494.   </tr>

  2495.   <tr>

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

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

  2498.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  2500.   </tr>

  2501.   <tr>

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

  2503.     <td valign="top">the name of a file. Each line of this file is

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

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

  2506.   </tr>

  2507.   <tr>

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

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

  2510.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  2512.   </tr>

  2513. </table>

  2514. <h3>Examples</h3>

  2515. <pre>  &lt;replace file=&quot;${src}/index.html&quot; token=&quot;@@@&quot; value=&quot;wombat&quot; /&gt;</pre>

  2516. <p>replaces occurrences of the string &quot;@@@&quot; with the string

  2517. &quot;wombat&quot;, in the file <code>${src}/index.html</code>.</p>

  2518. <hr>

  2519. <h2><a name="rmic">Rmic</a></h2>

  2520. <h3>Description</h3>

  2521. <p>Runs the rmic compiler for a certain class.</p>

  2522. <p>Rmic can be run on a single class (as specified with the classname

  2523. attribute) or a number of classes at once (all classes below base that

  2524. are neither _Stub nor _Skel classes).</p>

  2525. <p>It is possible to refine the set of files that are being rmiced. This can be

  2526. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  2527. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  2528. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  2529. the files you want to have excluded. This is also done with patterns. And

  2530. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  2531. want to use default exclusions or not. See the section on <a

  2532. href="#directorybasedtasks">directory based tasks</a>, on how the

  2533. inclusion/exclusion of files works, and how to write patterns. The patterns are

  2534. relative to the <i>base</i> directory.</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">base</td>

  2544.     <td valign="top">the location to store the compiled files.</td>

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

  2546.   </tr>

  2547.   <tr>

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

  2549.     <td valign="top">the class for which to run <code>rmic</code>.</td>

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

  2551.   </tr>

  2552.   <tr>

  2553.     <td valign="top">filtering</td>

  2554.     <td valign="top">indicates whether token filtering should take place</td>

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

  2556.   </tr>

  2557.   <tr>

  2558.     <td valign="top">sourcebase</td>

  2559.     <td valign="top">Pass the "-keepgenerated" flag to rmic and

  2560.  move the generated source file to the base directory.</td>

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

  2562.   </tr>

  2563.   <tr>

  2564.     <td valign="top">stubversion</td>

  2565.     <td valign="top">Specify the JDK version for the generated stub code.

  2566.  Specify "1.1" to pass the "-v1.1" option to rmic.</td>

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

  2568.   </tr>

  2569.   <tr>

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

  2571.     <td valign="top">The classpath to use during compilation</td>

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

  2573.   </tr>

  2574.   <tr>

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

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

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

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

  2579.   </tr>

  2580.   <tr>

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

  2582.     <td valign="top">the name of a file. Each line of this file is

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

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

  2585.   </tr>

  2586.   <tr>

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

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

  2589.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  2591.   </tr>

  2592.   <tr>

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

  2594.     <td valign="top">the name of a file. Each line of this file is

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

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

  2597.   </tr>

  2598.   <tr>

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

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

  2601.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  2603.   </tr>

  2604.   <tr>

  2605.     <td valign="top">verify</td>

  2606.     <td valign="top">check that classes implement Remote before handing them 

  2607.         to rmic (default is false)</td>

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

  2609.   </tr>

  2610. </table>

  2611. <h3>Examples</h3>

  2612. <pre>  &lt;rmic classname=&quot;com.xyz.FooBar&quot; base=&quot;${build}/classes&quot; /&gt;</pre>

  2613. <p>runs the rmic compiler for the class <code>com.xyz.FooBar</code>. The

  2614. compiled files will be stored in the directory <code>${build}/classes</code>.</p>

  2615. <pre>  &lt;rmic base=&quot;${build}/classes&quot; includes=&quot;**/Remote*.class&quot; /&gt;</pre>

  2616. <p>runs the rmic compiler for all classes with <code>.class</code>

  2617. files below <code>${build}/classes</code> whose classname starts with

  2618. <i>Remote</i>. The compiled files will be stored in the directory

  2619. <code>${build}/classes</code>.</p>

  2620. 

  2621. <hr>

  2622. <h2><a name="signjar">SignJar</a></h2>

  2623. <h3>Description</h3>

  2624. <p>Signs a jar or zip file with the javasign command line tool.</p>

  2625. 

  2626. <h3>Parameters</h3>

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

  2628.   <tr>

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

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

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

  2632.   </tr>

  2633.   <tr>

  2634.     <td valign="top">jar</td>

  2635.     <td valign="top">the jar file to sign</td>

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

  2637.   </tr>

  2638.   <tr>

  2639.     <td valign="top">alias</td>

  2640.     <td valign="top">the alias to sign under</td>

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

  2642.   </tr>

  2643.   <tr>

  2644.     <td valign="top">storepass</td>

  2645.     <td valign="top">password for keystore integrity.</td>

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

  2647.   </tr>

  2648.   <tr>

  2649.     <td valign="top">keystore</td>

  2650.     <td valign="top">keystore location</td>

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

  2652.   </tr>

  2653.   <tr>

  2654.     <td valign="top">storetype</td>

  2655.     <td valign="top">keystore type</td>

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

  2657.   </tr>

  2658.   <tr>

  2659.     <td valign="top">keypass</td>

  2660.     <td valign="top">password for private key (if different)</td>

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

  2662.   </tr>

  2663.   <tr>

  2664.     <td valign="top">sigfile</td>

  2665.     <td valign="top">name of .SF/.DSA file</td>

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

  2667.   </tr>

  2668.   <tr>

  2669.     <td valign="top">signedjar</td>

  2670.     <td valign="top">name of signed JAR file</td>

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

  2672.   </tr>

  2673.   <tr>

  2674.     <td valign="top">verbose</td>

  2675.     <td valign="top">(true | false) verbose output when signing</td>

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

  2677.   </tr>

  2678.   <tr>

  2679.     <td valign="top">internalsf</td>

  2680.     <td valign="top">(true | false) include the .SF file inside the signature

  2681. block</td>

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

  2683.   </tr>

  2684.   <tr>

  2685.     <td valign="top">sectionsonly</td>

  2686.     <td valign="top">(true | false) don't compute hash of entire manifest</td>

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

  2688.   </tr>

  2689. </table>

  2690. <h3>Examples</h3>

  2691. <blockquote>

  2692.   <p><code>&lt;signjar jar=&quot;${dist}/lib/ant.jar&quot;

  2693. alias=&quot;apache-group&quot; storepass=&quot;secret&quot; /&gt;</code></p>

  2694. </blockquote>

  2695. <p>signs the ant.jar with alias &quot;apache-group&quot; accessing the

  2696. keystore and private key via &quot;secret&quot; password.</p>

  2697. <hr>

  2698. <h2><a name="tar">Tar</a></h2>

  2699. <h3>Description</h3>

  2700. <p>Creates a tar archive.</p>

  2701. <p>The <i>basedir</i> attribute is the reference directory from where to tar.</p>

  2702. <p>It is possible to refine the set of files that are being tarred. This can be

  2703. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  2704. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  2705. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  2706. the files you want to have excluded. This is also done with patterns. And

  2707. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  2708. want to use default exclusions or not. See the section on <a

  2709. href="#directorybasedtasks">directory based tasks</a>, on how the

  2710. inclusion/exclusion of files works, and how to write patterns. The patterns are

  2711. relative to the <i>basedir</i> directory.</p>

  2712. <p>The <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i> attributes

  2713. replace the <i>items</i> and <i>ignore</i> attributes. The following explains

  2714. how the deprecated <i>items</i> and <i>ignore</i> attribute behave.</p>

  2715. <p>When &quot;*&quot; is used for <i>items</i>, all files in the basedir, and

  2716. its subdirectories, will be tarred. Otherwise all the files and directories

  2717. mentioned in the items list will tarred. When a directory is specified, then all

  2718. files within it are also tarred.</p>

  2719. <p>With the <i>ignore</i> attribute, you can specify files or directories to

  2720. ignore. These files will not be tarred. The items in the <i>ignore</i> attribute

  2721. override the items in the <i>items</i> attribute. The names specified in the <i>ignore</i>

  2722. attribute are just names, they do not contain any path information!</p>

  2723. <p>Note that this task does not perform compression. You might want to use the <a href="#gzip">GZip</a>

  2724. task to come up with a .tar.gz package.</p>

  2725. <h3>Parameters</h3>

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

  2727.   <tr>

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

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

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

  2731.   </tr>

  2732.   <tr>

  2733.     <td valign="top">tarfile</td>

  2734.     <td valign="top">the tar-file to create.</td>

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

  2736.   </tr>

  2737.   <tr>

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

  2739.     <td valign="top">the directory from which to zip the files.</td>

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

  2741.   </tr>

  2742.   <tr>

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

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

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

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

  2747.   </tr>

  2748.   <tr>

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

  2750.     <td valign="top">the name of a file. Each line of this file is

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

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

  2753.   </tr>

  2754.   <tr>

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

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

  2757.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  2759.   </tr>

  2760.   <tr>

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

  2762.     <td valign="top">the name of a file. Each line of this file is

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

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

  2765.   </tr>

  2766.   <tr>

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

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

  2769.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  2771.   </tr>

  2772. </table>

  2773. <h3>Examples</h3>

  2774. <pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot; basedir=&quot;htdocs/manual&quot; /&gt;

  2775.   &lt;gzip zipfile=&quot;${dist}/manual.tar.gz&quot; src=&quot;${dist}/manual.tar&quot; /&gt;</pre>

  2776. <p>tars all files in the <code>htdocs/manual</code> directory in a file called <code>manual.tar</code>

  2777. in the <code>${dist}</code>  directory, then applies the gzip task to compress

  2778. it.</p>

  2779. <pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot;

  2780.        basedir=&quot;htdocs/manual&quot;

  2781.        excludes=&quot;mydocs/**, **/todo.html&quot;

  2782.   /&gt;</pre>

  2783. <p>tars all files in the <code>htdocs/manual</code> directory in a file called <code>manual.tar</code>

  2784. in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,

  2785. or files with the name <code>todo.html</code> are excluded.</p>

  2786. <hr>

  2787. <h2><a name="taskdef">Taskdef</a></h2>

  2788. <h3>Description</h3>

  2789. <p>Adds a task definition to the current project, such that this new task can be

  2790. used in the current project. Two attributes are needed, the name that identifies

  2791. this task uniquely, and the full name of the class (including the packages) that

  2792. implements this task.</p>

  2793. <p>Taskdef should be used to add your own tasks to the system. See also &quot;<a

  2794. href="#writingowntask">Writing your own task</a>&quot;.</p>

  2795. <h3>Parameters</h3>

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

  2797.   <tr>

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

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

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

  2801.   </tr>

  2802.   <tr>

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

  2804.     <td valign="top">the name of the task</td>

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

  2806.   </tr>

  2807.   <tr>

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

  2809.     <td valign="top">the full class name implementing the task</td>

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

  2811.   </tr>

  2812. </table>

  2813. <h3>Examples</h3>

  2814. <pre>  &lt;taskdef name=&quot;myjavadoc&quot; classname=&quot;com.mydomain.JavadocTask&quot; /&gt;</pre>

  2815. <p>makes a task called <code>myjavadoc</code> available to Ant. The class <code>com.mydomain.JavadocTask</code>

  2816. implements the task.</p>

  2817. <hr>

  2818. <h2><a name="touch">Touch</a></h2>

  2819. <h3>Description</h3>

  2820. <p>Changes the modification time of a file and possibly creates it at

  2821. the same time.</p>

  2822. <p>For JDK 1.1 only the creation of new files with a modification time

  2823. of now works, all other cases will emit a warning.</p>

  2824. <h3>Parameters</h3>

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

  2826.   <tr>

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

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

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

  2830.   </tr>

  2831.   <tr>

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

  2833.     <td valign="top">the name of the file</td>

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

  2835.   </tr>

  2836.   <tr>

  2837.     <td valign="top">millis</td>

  2838.     <td valign="top">specifies the new modification time of the file

  2839.        in milliseconds since midnight Jan 1 1970</td>

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

  2841.   </tr>

  2842.   <tr>

  2843.     <td valign="top">datetime</td>

  2844.     <td valign="top">specifies the new modification time of the file

  2845.        in the format MM/DD/YYYY HH:MM AM_or_PM.</td>

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

  2847.   </tr>

  2848. </table>

  2849. <p>If both <code>millis</code> and <code>datetime</code> are ommited

  2850. the current time is assumed.</p>

  2851. <h3>Examples</h3>

  2852. <pre>  &lt;touch file=&quot;myfile&quot; /&gt;</pre>

  2853. <p>creates <code>myfile</code> if it doesn't exist and changes the

  2854. modification time to the current time.</p>

  2855. <pre>  &lt;touch file=&quot;myfile&quot; datetime=&quot;06/28/2000 2:02 pm&quot; /&gt;</pre>

  2856. <p>creates <code>myfile</code> if it doesn't exist and changes the

  2857. modification time to Jun, 28 2000 2:02 pm (14:02 for those used to 24

  2858. hour times).</p>

  2859. <hr>

  2860. <h2><a name="tstamp">Tstamp</a></h2>

  2861. <h3>Description</h3>

  2862. <p>Sets the DSTAMP, TSTAMP and TODAY properties in the current project. The

  2863. DSTAMP is in the &quot;yyyymmdd&quot; format, the TSTAMP is in the &quot;hhmm&quot;

  2864. format and TODAY is &quot;month day year&quot;.</p>

  2865. <p>These properties can be used in the buildfile, for instance, to create

  2866. timestamped filenames or used to replace placeholder tags inside documents to

  2867. indicate, for example, the release date. The best place for this task is in your

  2868. initialization target.</p>

  2869. <h3>Parameters</h3>

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

  2871.   <tr>

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

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

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

  2875.   </tr>

  2876. </table>

  2877. <h3>Examples</h3>

  2878. <pre>  &lt;tstamp/&gt;</pre>

  2879. <hr>

  2880. <h2><a name="style">Style</a></h2>

  2881. <h3>Description</h3>

  2882. <p>Process a set of documents via XSLT.</p>

  2883. <p>This is useful for building views of XML based documentation,

  2884. or in generating code.</p>

  2885. <p>It is possible to refine the set of files that are being copied. This can be

  2886. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  2887. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  2888. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  2889. the files you want to have excluded. This is also done with patterns. And

  2890. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  2891. want to use default exclusions or not. See the section on <a

  2892. href="#directorybasedtasks">directory based tasks</a>, on how the

  2893. inclusion/exclusion of files works, and how to write patterns. The patterns are

  2894. relative to the <i>basedir</i> directory.</p>

  2895. <h3>Parameters</h3>

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

  2897.   <tr>

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

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

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

  2901.   </tr>

  2902.   <tr>

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

  2904.     <td valign="top">where to find the source xml file.</td>

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

  2906.   </tr>

  2907.   <tr>

  2908.     <td valign="top">destdir</td>

  2909.     <td valign="top">directory where to store the results.</td>

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

  2911.   </tr>

  2912.   <tr>

  2913.     <td valign="top">extention</td>

  2914.     <td valign="top">desired file extension to be used for the targets.

  2915.         If not specified, the default is "html".</td>

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

  2917.   </tr>

  2918.   <tr>

  2919.     <td valign="top">style</td>

  2920.     <td valign="top">name of the stylesheet to use.</td>

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

  2922.   </tr>

  2923.   <tr>

  2924.     <td valign="top">processor</td>

  2925.     <td valign="top">name of the XSLT processor to use.  Permissable

  2926. values are "xslp" for the XSL:P processor, "xalan" for the Apache XML Xalan

  2927. processor, or the name of an arbitrary XSLTLiaison class.

  2928. Defaults to xslp or xalan (in that order), if one is found in your

  2929. class path</td>

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

  2931.   </tr>

  2932.   <tr>

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

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

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

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

  2937.   </tr>

  2938.   <tr>

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

  2940.     <td valign="top">the name of a file. Each line of this file is

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

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

  2943.   </tr>

  2944.   <tr>

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

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

  2947.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  2949.   </tr>

  2950.   <tr>

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

  2952.     <td valign="top">the name of a file. Each line of this file is

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

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

  2955.   </tr>

  2956.   <tr>

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

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

  2959.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  2961.   </tr>

  2962. </table>

  2963. <h3>Examples</h3>

  2964. <blockquote>

  2965.   <p><pre>

  2966. &lt;style basedir=&quot;doc&quot; destdir=&quot;build/doc&quot;

  2967.        extension=&quot;html&quot; style=&quot;style/apache.xml&quot;/&gt;

  2968. </pre></p>

  2969. </blockquote>

  2970. <hr>

  2971. <h2><a name="untar">Untar</a></h2>

  2972. <h3>Description</h3>

  2973. <p>Untars a tarfile.</p>

  2974. <p>For JDK 1.1 "last modified time" field is set to current time instead of being 

  2975. carried from tarfile.</p>

  2976. <h3>Parameters</h3>

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

  2978.   <tr>

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

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

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

  2982.   </tr>

  2983.   <tr>

  2984.     <td valign="top">src</td>

  2985.     <td valign="top">tarfile to expand.</td>

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

  2987.   </tr>

  2988.   <tr>

  2989.     <td valign="top">dest</td>

  2990.     <td valign="top">directory where to store the expanded files.</td>

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

  2992.   </tr>

  2993. </table>

  2994. <h3>Examples</h3>

  2995. <blockquote>

  2996.   <p><code>

  2997. &lt;gunzip src=&quot;tools.tar.gz&quot;/&gt;<br>

  2998. &lt;untar src=&quot;tools.tar&quot; dest=&quot;${tools.home}&quot;/&gt;

  2999. </code></p>

  3000. </blockquote>

  3001. <hr>

  3002. <h2><a name="zip">Zip</a></h2>

  3003. <h3>Description</h3>

  3004. <p>Creates a zipfile.</p>

  3005. <p>The <i>basedir</i> attribute is the reference directory from where to zip.</p>

  3006. <p>It is possible to refine the set of files that are being zipped. This can be

  3007. done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>

  3008. attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to

  3009. have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify

  3010. the files you want to have excluded. This is also done with patterns. And

  3011. finally with the <i>defaultexcludes</i> attribute, you can specify whether you

  3012. want to use default exclusions or not. See the section on <a

  3013. href="#directorybasedtasks">directory based tasks</a>, on how the

  3014. inclusion/exclusion of files works, and how to write patterns. The patterns are

  3015. relative to the <i>basedir</i> directory.</p>

  3016. <p>The <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i> attributes

  3017. replace the <i>items</i> and <i>ignore</i> attributes. The following explains

  3018. how the deprecated <i>items</i> and <i>ignore</i> attribute behave.</p>

  3019. <p>When &quot;*&quot; is used for <i>items</i>, all files in the basedir, and

  3020. its subdirectories, will be zipped. Otherwise all the files and directories

  3021. mentioned in the items list will zipped. When a directory is specified, then all

  3022. files within it are also zipped.</p>

  3023. <p>With the <i>ignore</i> attribute, you can specify files or directories to

  3024. ignore. These files will not be zipped. The items in the <i>ignore</i> attribute

  3025. override the items in the <i>items</i> attribute. The names specified in the <i>ignore</i>

  3026. attribute are just names, they do not contain any path information!</p>

  3027. <h3>Parameters</h3>

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

  3029.   <tr>

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

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

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

  3033.   </tr>

  3034.   <tr>

  3035.     <td valign="top">zipfile</td>

  3036.     <td valign="top">the zip-file to create.</td>

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

  3038.   </tr>

  3039.   <tr>

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

  3041.     <td valign="top">the directory from which to zip the files.</td>

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

  3043.   </tr>

  3044.   <tr>

  3045.     <td valign="top">compress</td>

  3046.     <td valign="top">Not only store data but also compress them, defaults to true</td>

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

  3048.   </tr>

  3049.   <tr>

  3050.     <td valign="top">items</td>

  3051.     <td valign="top">a comma separated list of the files/directories to zip. All

  3052.       files are included when omitted. (<b>deprecated</b>, use <i>includes</i>

  3053.       instead).</td>

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

  3055.   </tr>

  3056.   <tr>

  3057.     <td valign="top">ignore</td>

  3058.     <td valign="top">comma separated list of filenames/directorynames to exclude

  3059.       from the zip. No files (except default excludes) are excluded when

  3060.       omitted. (<b>deprecated</b>, use <i>excludes</i> instead).</td>

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

  3062.   </tr>

  3063.   <tr>

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

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

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

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

  3068.   </tr>

  3069.   <tr>

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

  3071.     <td valign="top">the name of a file. Each line of this file is

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

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

  3074.   </tr>

  3075.   <tr>

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

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

  3078.       excluded. No files (except default excludes) are excluded when omitted.</td>

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

  3080.   </tr>

  3081.   <tr>

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

  3083.     <td valign="top">the name of a file. Each line of this file is

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

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

  3086.   </tr>

  3087.   <tr>

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

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

  3090.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>

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

  3092.   </tr>

  3093. </table>

  3094. <h3>Examples</h3>

  3095. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;

  3096.        basedir=&quot;htdocs/manual&quot;

  3097.   /&gt;</pre>

  3098. <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>

  3099. in the <code>${dist}</code> directory.</p>

  3100. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;

  3101.        basedir=&quot;htdocs/manual&quot;

  3102.        excludes=&quot;mydocs/**, **/todo.html&quot;

  3103.   /&gt;</pre>

  3104. <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>

  3105. in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,

  3106. or files with the name <code>todo.html</code> are excluded.</p>

  3107. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;

  3108.        basedir=&quot;htdocs/manual&quot;

  3109.        includes=&quot;api/**/*.html&quot;

  3110.        excludes=&quot;**/todo.html&quot;

  3111.   /&gt;</pre>

  3112. <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>

  3113. in the <code>${dist}</code> directory. Only html files under the directory <code>api</code>

  3114. are zipped, and files with the name <code>todo.html</code> are excluded.</p>

  3115. <h3>Deprecated examples</h3>

  3116. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;

  3117.        basedir=&quot;htdocs/manual&quot;

  3118.        items=&quot;*&quot;

  3119.   /&gt;</pre>

  3120. <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>

  3121. in the <code>${dist}</code> directory.</p>

  3122. <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;

  3123.        basedir=&quot;htdocs/manual&quot;

  3124.        items=&quot;*&quot;

  3125.        ignore=&quot;mydocs, todo.html&quot;

  3126.   /&gt;</pre>

  3127. <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>

  3128. in the <code>${dist}</code> directory. Files/directories with the names <code>mydocs</code>

  3129. and <code>todo.html</code> are excluded.</p>

  3130. 

  3131. <hr>

  3132. <h2><a name="buildevents">Build Events</a></h2>

  3133. Ant is capable of generating build events as it performs the tasks necessary to build a project. 

  3134. Listeners can be attached to ant to receive these events. This capability could be used, for example,

  3135. to connect Ant to a GUI or to integrate Ant with an IDE. 

  3136. 

  3137. <p>To use build events you need to create an ant <code>Project</code> object. You can then call the 

  3138. <code>addBuildListener</code> method to add your listener to the project. Your listener must implement

  3139. the <code>org.apache.tools.antBuildListener</code> interface. The listener will receive BuildEvents 

  3140. for the following events

  3141. <ul>

  3142. <li>Build started

  3143. <li>Build finished

  3144. <li>Target started

  3145. <li>Target finished

  3146. <li>Task started

  3147. <li>Task finished

  3148. <li>Message logged

  3149. </ul>

  3150. 

  3151. If you wish to attach a listener from the command line you may use the -listener option. For example

  3152. <blockquote>

  3153.   <pre>ant -listener org.apache.tools.ant.XmlLogger</pre>

  3154. </blockquote>

  3155. will run ant with a listener which generates an XML representaion of the build progress. This 

  3156. listener is included with ant as is the default listener which generates the logging to standard

  3157. output.

  3158. 

  3159. 

  3160. <hr>

  3161. <h2><a name="writingowntask">Writing your own task</a></h2>

  3162. <p>It is very easy to write your own task:</p>

  3163. <ol>

  3164.   <li>Create a Java class that extends <code>org.apache.tools.ant.Task</code>.</li>

  3165.   <li>For each attribute, write a setter method. The setter method must be a 

  3166.     <code>public void</code> method that takes a single argument. The

  3167.     name of the method must begin with &quot;set&quot;, followed by the

  3168.     attribute name, with the first character in uppercase, and the rest in

  3169.     lowercase. The type of the attribute can be <code>String</code>, any 

  3170.     primitive type, <code>Class</code>, <code>File</code> (in which case the 

  3171.     value of the attribute is interpreted relative to the project's basedir) 

  3172.     or any other type that has a constructor with a single <code>String</code>

  3173.     argument</li>

  3174.   <li>If your task has enumerated attributes, you should consider using

  3175.     a subclass of org.apache.tools.ant.EnumeratedAttribute as argument

  3176.     to your setter method. See org.apache.tools.ant.taskdefs.FixCRLF for

  3177.     an example.</li>

  3178.   <li>If the task should support character data, write a <code>public void 

  3179.     addText(String)</code> method.</li>

  3180.   <li>For each nested element, write a create or add method. A create method 

  3181.     must be a <code>public</code> method that takes no arguments and returns 

  3182.     an Object type. The name of the create method must begin with 

  3183.     &quot;create&quot;, followed by the element name. An add method must be 

  3184.     a <code>public void</code> method that takes a single argument of an 

  3185.     Object type with a no argument constructor. The name of the add method 

  3186.     must begin with &quot;add&quot;, followed by the element name.

  3187.   <li>Write a <code>public void execute</code> method, with no arguments, that

  3188.     throws a <code>BuildException</code>. This method implements the task

  3189.     itself.</li>

  3190. </ol>

  3191. <p>It is important to know that Ant first calls the setters for the attributes

  3192. it encounters for a specific task in the buildfile, before it executes is.</p>

  3193. <p>Let's write our own task, that prints a message on the System.out stream. The

  3194. task has one attribute called &quot;message&quot;.</p>

  3195. <blockquote>

  3196.   <pre>package com.mydomain;

  3197. 

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

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

  3200. 

  3201. public class MyVeryOwnTask extends Task {

  3202.   private String msg;

  3203. 

  3204.   // The method executing the task

  3205.   public void execute() throws BuildException {

  3206.     System.out.println(msg);

  3207.   }

  3208. 

  3209.   // The setter for the &quot;message&quot; attribute

  3210.   public void setMessage(String msg) {

  3211.     this.msg = msg;

  3212.   }

  3213. }</pre>

  3214. </blockquote>

  3215. <p>It's really this simple;-)</p>

  3216. <p>Adding your task to the system is rather simple too:</p>

  3217. <ol>

  3218.   <li>Make sure the class that implements your task is in the classpath when

  3219.     starting Ant.</li>

  3220.   <li>In your initialization target, add a <i>taskdef</i> task. This actually adds

  3221.     your task to the system.</li>

  3222.   <li>Use your task in the rest of the buildfile.</li>

  3223. </ol>

  3224. <h3>Example</h3>

  3225. <blockquote>

  3226.   <pre>&lt;?xml version=&quot;1.0&quot;?&gt;

  3227. 

  3228. &lt;project name=&quot;OwnTaskExample&quot; default=&quot;main&quot; basedir=&quot;.&quot;&gt;

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

  3230.     &lt;taskdef name=&quot;mytask&quot; classname=&quot;com.mydomain.MyVeryOwnTask&quot;/&gt;

  3231.   &lt;/target&gt;

  3232. 

  3233.   &lt;target name=&quot;main&quot; depends=&quot;init&quot;&gt;

  3234.     &lt;mytask message=&quot;Hello World! MyVeryOwnTask works!&quot; /&gt;

  3235.   &lt;/target&gt;

  3236. &lt;/project&gt;

  3237. </pre>

  3238. </blockquote>

  3239. <p>Another way to add a task (more permanently), is to add the task name and

  3240. implementing class name to the <code>default.properties</code> file in the <code>org.apache.tools.ant.taskdefs</code>

  3241. package. Then you can use it as if it were a built in task.</p>

  3242. <hr>

  3243. <h2><a name="faq">FAQ, DTD, external resources</a></h2>

  3244. <p>There is an online FAQ for Ant at <a

  3245. href="http://jakarta.apache.org/jyve-faq/Turbine/screen/DisplayTopics/action/SetAll/project_id/2/faq_id/16">jakarta.apache.org</a>. This

  3246. FAQ is interactive, which means you can ask and answer questions

  3247. online.</p>

  3248. <p>One of the questions poping up quite often is "Is there a DTD for

  3249. buildfiles?". Please refer to the FAQ for an answer.</p>

  3250. <p>The FAQ contains lists of known custom tasks that don't ship with

  3251. Ant and projects that use Ant. Feel free to add your own task or project

  3252. there.</p>

  3253. <h2><a name="feedback">Feedback</a></h2>

  3254. <p>To provide feedback on this software, please subscribe to the Ant Development

  3255. Mail List <a href="mailto:(ant-dev-subscribe@jakarta.apache.org">(ant-dev-subscribe@jakarta.apache.org</a>)</p>

  3256. <hr>

  3257. <p align="center">Copyright © 2000 Apache Software Foundation. All rights

  3258. Reserved.</p>

  3259. 

  3260. <h2><a name="optionaltasks">Optional tasks</a></h2>

  3261. <ul>

  3262.   <li><a href="#netrexxc">NetRexxC</a></li>

  3263.   <li><a href="#renameexts">RenameExtensions</a></li>

  3264.   <li><a href="#script">Script</a></li>

  3265. </ul>

  3266. <hr>

  3267. <h2><a name="netrexxc">NetRexxC</a></h2>

  3268. <h3><b>Description:</b></h3>

  3269. <p>Compiles a <a href="http://www2.hursley.ibm.com/netrexx">NetRexx</a>

  3270. source tree within the running (Ant) VM.</p>

  3271. <p>The source and destination directory will be recursively scanned for

  3272. NetRexx source files to compile.  Only NetRexx files that have no corresponding

  3273. class file or where the class file is older than the java file will be compiled.</p>

  3274. <p>Files in the source tree are copied to the destination directory,

  3275. allowing support files to be located properly in the classpath. The source 

  3276. files are copied because the NetRexx compiler cannot produce class files in a

  3277. specific directory via parameters</p>

  3278. <p>The directory structure of the source tree should follow the package

  3279. hierarchy.</p>

  3280. <p>It is possible to refine the set of files that are being compiled/copied.

  3281. This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and

  3282. <i>defaultexcludes</i> attributes. With the <i>includes</i> or <i>includesfile</i> attribute you 

  3283. specify the files you want to have included by using patterns. The 

  3284. <i>exclude</i> or <i>excludesfile</i> attribute is used to specify the files you want to have 

  3285. excluded.  This is also done with patterns.  And finally with the 

  3286. <i>defaultexcludes</i> attribute, you can specify whether you

  3287. want to use default exclusions or not. See the section on <a

  3288. href="#directorybasedtasks">directory based tasks</a>, on how the

  3289. inclusion/exclusion of files works, and how to write patterns. The

  3290. patterns are relative to the <i>srcDir</i> directory.</p>

  3291. 

  3292. <h3>Parameters:</h3>

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

  3294.   <tr>

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

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

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

  3298.   </tr>

  3299.   <tr>

  3300.     <td valign="top">binary</td>

  3301.     <td valign="top">Whether literals are treated as the java binary

  3302.       type rather than the NetRexx types</td>

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

  3304.   </tr>

  3305.   <tr>

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

  3307.     <td valign="top">The classpath to use during compilation</td>

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

  3309.   </tr>

  3310.   <tr>

  3311.     <td valign="top">comments</td>

  3312.     <td valign="top">Whether comments are passed through to the

  3313.       generated java source</td>

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

  3315.   </tr>

  3316.   <tr>

  3317.     <td valign="top">compact</td>

  3318.     <td valign="top">Whether error messages come out in compact or

  3319.       verbose format</td>

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

  3321.   </tr>

  3322.   <tr>

  3323.     <td valign="top">compile</td>

  3324.     <td valign="top">Whether the NetRexx compiler should compile the

  3325.       generated java code</td>

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

  3327.   </tr>

  3328.   <tr>

  3329.     <td valign="top">console</td>

  3330.     <td valign="top">Whether or not messages should be displayed on the

  3331.       'console'</td>

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

  3333.   </tr>

  3334.   <tr>

  3335.     <td valign="top">crossref</td>

  3336.     <td valign="top">Whether variable cross references are generated</td>

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

  3338.   </tr>

  3339.   <tr>

  3340.     <td valign="top">decimal</td>

  3341.     <td valign="top">Whether decimal arithmetic should be used for the

  3342.       NetRexx code</td>

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

  3344.   </tr>

  3345.   <tr>

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

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

  3348.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when

  3349.       omitted.</td>

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

  3351.   </tr>

  3352.   <tr>

  3353.     <td valign="top">destDir</td>

  3354.     <td valign="top">the destination directory into which the NetRexx

  3355.       source files should be copied and then compiled</td>

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

  3357.   </tr>

  3358.   <tr>

  3359.     <td valign="top">diag</td>

  3360.     <td valign="top">Whether diagnostic information about the compile is

  3361.       generated</td>

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

  3363.   </tr>

  3364.   <tr>

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

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

  3367.       excluded. No files (except default excludes) are excluded when

  3368.       omitted.</td>

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

  3370.   </tr>

  3371.   <tr>

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

  3373.     <td valign="top">the name of a file. Each line of this file is

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

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

  3376.   </tr>

  3377.   <tr>

  3378.     <td valign="top">explicit</td>

  3379.     <td valign="top">Whether variables must be declared explicitly

  3380.       before use</td>

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

  3382.   </tr>

  3383.   <tr>

  3384.     <td valign="top">format</td>

  3385.     <td valign="top">Whether the generated java code is formatted nicely

  3386.       or left to match NetRexx line numbers for call stack debugging</td>

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

  3388.   </tr>

  3389.   <tr>

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

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

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

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

  3394.   </tr>

  3395.   <tr>

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

  3397.     <td valign="top">the name of a file. Each line of this file is

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

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

  3400.   </tr>

  3401.   <tr>

  3402.     <td valign="top">java</td>

  3403.     <td valign="top">Whether the generated java code is produced</td>

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

  3405.   </tr>

  3406.   <tr>

  3407.     <td valign="top">keep</td>

  3408.     <td valign="top">Sets whether the generated java source file should be kept

  3409.       after compilation. The generated files will have an extension of

  3410.       .java.keep, <b>not</b> .java</td>

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

  3412.   </tr>

  3413.   <tr>

  3414.     <td valign="top">logo</td>

  3415.     <td valign="top">Whether the compiler text logo is displayed when

  3416.       compiling</td>

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

  3418.   </tr>

  3419.   <tr>

  3420.     <td valign="top">replace</td>

  3421.     <td valign="top">Whether the generated .java file should be replaced

  3422.       when compiling</td>

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

  3424.   </tr>

  3425.   <tr>

  3426.     <td valign="top">savelog</td>

  3427.     <td valign="top">Whether the compiler messages will be written to

  3428.       NetRexxC.log as well as to the console</td>

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

  3430.   </tr>

  3431.   <tr>

  3432.     <td valign="top">sourcedir</td>

  3433.     <td valign="top">Tells the NetRexx compiler to store the class files in the

  3434.       same directory as the source files. The alternative is the working

  3435.       directory</td>

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

  3437.   </tr>

  3438.   <tr>

  3439.     <td valign="top">srcDir</td>

  3440.     <td valign="top">Set the source dir to find the source Netrexx

  3441.       files</td>

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

  3443.   </tr>

  3444.   <tr>

  3445.     <td valign="top">strictargs</td>

  3446.     <td valign="top">Tells the NetRexx compiler that method calls always

  3447.       need parentheses, even if no arguments are needed, e.g. 

  3448.       <code>aStringVar.getBytes</code> vs. 

  3449.       <code>aStringVar.getBytes()</code></td>

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

  3451.   </tr>

  3452.   <tr>

  3453.     <td valign="top">strictassign</td>

  3454.     <td valign="top">Tells the NetRexx compile that assignments must

  3455.       match exactly on type</td>

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

  3457.   </tr>

  3458.   <tr>

  3459.     <td valign="top">strictcase</td>

  3460.     <td valign="top">Specifies whether the NetRexx compiler should be

  3461.       case sensitive or not</td>

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

  3463.   </tr>

  3464.   <tr>

  3465.     <td valign="top">strictimport</td>

  3466.     <td valign="top">Whether classes need to be imported explicitly using an 

  3467.       <code>import</code> statement.  By default the NetRexx compiler will 

  3468.       import certain packages automatically</td>

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

  3470.   </tr>

  3471.   <tr>

  3472.     <td valign="top">strictprops</td>

  3473.     <td valign="top">Whether local properties need to be qualified

  3474.       explicitly using <code>this</code></td>

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

  3476.   </tr>

  3477.   <tr>

  3478.     <td valign="top">strictsignal</td>

  3479.     <td valign="top">Whether the compiler should force catching of

  3480.       exceptions by explicitly named types</td>

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

  3482.   </tr>

  3483.   <tr>

  3484.     <td valign="top">symbols</td>

  3485.     <td valign="top">Whether debug symbols should be generated into the

  3486.       class file</td>

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

  3488.   </tr>

  3489.   <tr>

  3490.     <td valign="top">time</td>

  3491.     <td valign="top">Asks the NetRexx compiler to print compilation

  3492.       times to the console</td>

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

  3494.   </tr>

  3495.   <tr>

  3496.     <td valign="top">trace</td>

  3497.     <td valign="top">Turns on or off tracing and directs the resultant

  3498.       trace output</td>

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

  3500.   </tr>

  3501.   <tr>

  3502.     <td valign="top">utf8</td>

  3503.     <td valign="top">Tells the NetRexx compiler that the source is in UTF8</td>

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

  3505.   </tr>

  3506.   <tr>

  3507.     <td valign="top">verbose</td>

  3508.     <td valign="top">Whether lots of warnings and error messages should

  3509.       be generated</td>

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

  3511.   </tr>

  3512. </table>

  3513. <h3>Examples</h3>

  3514. <blockquote>

  3515.   <p><code>&lt;netrexxc srcDir=&quot;/source/project&quot;

  3516.            includes=&quot;vnr/util/*&quot;

  3517.            destDir=&quot;/source/project/build&quot;

  3518.            classpath=&quot;/source/project2/proj.jar&quot;

  3519.            comments=&quot;true&quot;

  3520.            crossref=&quot;false&quot; replace=&quot;true&quot;

  3521.            keep=&quot;true&quot; /&gt;</code>

  3522.   </p>

  3523. </blockquote>

  3524. <hr>

  3525. <h2><a name="renameexts">RenameExtensions</a></h2>

  3526. <h3><b>Description:</b></h3>

  3527. <p>Renames files in the <code>srcDir</code> directory ending with the

  3528. <code>fromExtension</code> string so that they end with the 

  3529. <code>toExtension</code> string. Files are only replaced if 

  3530. <code>replace</code> is true

  3531. </p>

  3532. <p>See the section on 

  3533. <a href="#directorybasedtasks">directory based tasks</a>, on how the

  3534. inclusion/exclusion of files works, and how to write patterns. The

  3535. patterns are relative to the <i>srcDir</i> directory.</p>

  3536. <h3>Parameters:</h3>

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

  3538.   <tr>

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

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

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

  3542.   </tr>

  3543.   <tr>

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

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

  3546.       (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when

  3547.       omitted.</td>

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

  3549.   </tr>

  3550.   <tr>

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

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

  3553.       excluded. No files (except default excludes) are excluded when

  3554.       omitted.</td>

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

  3556.   </tr>

  3557.   <tr>

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

  3559.     <td valign="top">the name of a file. Each line of this file is

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

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

  3562.   </tr>

  3563.   <tr>

  3564.     <td valign="top">fromExtention</td>

  3565.     <td valign="top">The string that files must end in to be renamed</td>

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

  3567.   </tr>

  3568.   <tr>

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

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

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

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

  3573.   </tr>

  3574.   <tr>

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

  3576.     <td valign="top">the name of a file. Each line of this file is

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

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

  3579.   </tr>

  3580.   <tr>

  3581.     <td valign="top">replace</td>

  3582.     <td valign="top">Whether the file being renamed to should be

  3583.       replaced if it already exists</td>

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

  3585.   </tr>

  3586.   <tr>

  3587.     <td valign="top">srcDir</td>

  3588.     <td valign="top">The starting directory for files to search in</td>

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

  3590.   </tr>

  3591.   <tr>

  3592.     <td valign="top">toExtension</td>

  3593.     <td valign="top">The string that renamed files will end with on

  3594.       completion</td>

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

  3596.   </tr>

  3597. </table>

  3598. <h3>Examples</h3>

  3599. <blockquote>

  3600.   <p><code>&lt;renameext srcDir=&quot;/source/project1&quot;

  3601.               includes=&quot;**&quot;

  3602.               excludes=&quot;**/samples/*&quot;

  3603.               fromExtension=&quot;.java.keep&quot;

  3604.               toExtension=&quot;.java&quot;

  3605.               replace=&quot;true&quot; /&gt;

  3606. </code>

  3607.   </p>

  3608. </blockquote>

  3609. 

  3610. <hr>

  3611. <h2><a name="script">Script</a></h2>

  3612. <h3><b>Description:</b></h3>

  3613. <p>Execute a script in a 

  3614.   <a href="http://www.alphaworks.ibm.com/tech/bsf">BSF</a> supported language.

  3615. <p>All items (tasks, targets, etc) of the running project are accessible

  3616. from the script.

  3617. <h3>Parameters:</h3>

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

  3619.   <tr>

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

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

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

  3623.   </tr>

  3624.   <tr>

  3625.     <td valign="top">language</td>

  3626.     <td valign="top">The programming language the script is written in.

  3627.       Must be a supported BSF language</td>

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

  3629.   </tr>

  3630.   <tr>

  3631.     <td valign="top">src</td>

  3632.     <td valign="top">The location of the script as a file, if not inline</td>

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

  3634.   </tr>

  3635. </table>

  3636. <h3>Examples</h3>

  3637. <blockquote>

  3638.   <p>None yet available</p>

  3639. </blockquote>

  3640. 

  3641. </body>

  3642. 

  3643. </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