source: other-projects/trunk/realistic-books/packages/AntInstaller/web/manual1.6.2/faq.html@ 19253

Last change on this file since 19253 was 19253, checked in by davidb, 15 years ago

Establishing a source code repository for Veronica's Realistic Book's software
File size: 74.4 KB
Line 
1
2
3<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
4 <html lang="en">
5 <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
6 <head>
7 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
8 <title>Apache Ant - Frequently Asked Questions</title>
9 <link type="text/css" href="./page.css" rel="stylesheet">
10 <meta name="author" content="Stefan Bodewig">
11 <meta name="email" content="[email protected]">
12 </head>
13
14 <body>
15 <p class="navpath">
16 <script src="./breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
17 </p>
18
19 <div class="logobar">
20 <table width="100%" border="0" cellspacing="0" cellpadding="0">
21 <tr>
22 <td align="left"><img border="0" alt="Apache Ant site" src="./images/group-logo.gif"></td>
23 <td align="center" width="100%"><img alt="Apache Ant logo" border="0" src="./images/project-logo.gif"></td>
24 <td align="right">
25 <form target="_blank" onsubmit="q.value = query.value + ' site:ant.apache.org'" action="http://www.google.com/search" method="get">
26 <table summary="search" border="0" cellspacing="0" cellpadding="0" bgcolor="#4C6C8F">
27 <tr>
28 <td colspan="3"><img height="10" width="1" alt="" src="./images/spacer.gif"></td>
29 </tr>
30 <tr>
31 <td><img height="1" width="1" alt="" src="./images/spacer.gif"></td>
32 <td nowrap="nowrap" class="searchcaption">
33 <input name="q" type="hidden">
34 <input size="15" id="query" type="text">
35 <img height="1" width="5" alt="" src="./images/spacer.gif">
36 <input name="Search" value="Search" type="submit">
37 <br>
38 the Apache Ant site
39 </td>
40 <td><img height="1" width="1" alt="" src="./images/spacer.gif"></td>
41 </tr>
42 <tr>
43 <td><img alt="" border="0" height="10" width="9" src="./images/search-left.gif"></td>
44 <td><img height="1" width="1" alt="" src="./images/spacer.gif"></td>
45 <td><img alt="" border="0" height="10" width="9" src="./images/search-right.gif"></td>
46 </tr>
47 </table>
48 </form>
49 </td>
50 </tr>
51 </table>
52 </div>
53
54 <div class="tab">
55 <table summary="tab bar" border="0" cellpadding="0" cellspacing="0">
56 <tr>
57 <td width="8"><img alt="" height="5" width="8" src="./images/spacer.gif"></td><td valign="bottom">
58 <table summary="selected tab" style="height: 1.5em" border="0" cellpadding="0" cellspacing="0">
59 <tr>
60 <td valign="top" width="5" bgcolor="#4C6C8F"><img height="5" width="5" alt="" src="./images/tabSel-left.gif"></td><td valign="middle" bgcolor="#4C6C8F"><font color="#ffffff" size="2" face="Arial, Helvetica, Sans-serif"><b>Home</b></font></td><td valign="top" width="5" bgcolor="#4C6C8F"><img height="5" width="5" alt="" src="./images/tabSel-right.gif"></td>
61 </tr>
62 </table>
63 </td>
64 <td width="5"><img alt="" height="8" width="8" src="./images/spacer.gif"></td><td valign="bottom">
65 <table summary="non selected tab" style="height: 1.4em" border="0" cellpadding="0" cellspacing="0">
66 <tr>
67 <td valign="top" width="5" bgcolor="#B2C4E0"><img height="5" width="5" alt="" src="./images/tab-left.gif"></td><td valign="middle" bgcolor="#B2C4E0"><a href="./projects/index.html"><font size="2" face="Arial, Helvetica, Sans-serif">Projects</font></a></td><td valign="top" width="5" bgcolor="#B2C4E0"><img height="5" width="5" alt="" src="./images/tab-right.gif"></td>
68 </tr>
69 </table>
70 </td>
71 </tr>
72 </table>
73 </div>
74
75 <div class="bluebar"></div>
76
77 <div class="menucontainer">
78 <div class="menu">
79 <ul>
80 <li class="menuheader">Apache Ant
81 <ul>
82 <li>
83 <a href="./index.html">Welcome</a>
84 </li>
85 <li>
86 <a href="./license.html">License</a>
87 </li>
88 <li>
89 <a href="./antnews.html">News</a>
90 </li>
91 </ul>
92 </li>
93 <li class="menuheader">Documentation
94 <ul>
95 <li>
96 <a href="./manual/index.html">Manual</a>
97 </li>
98 <li>
99 <a href="./projects.html">Related Projects</a>
100 </li>
101 <li>
102 <a href="./external.html">External Tools and Tasks</a>
103 </li>
104 <li>
105 <a href="./resources.html">Resources</a>
106 </li>
107 <li>
108 <span class="sel">Frequently Asked Questions</span>
109 </li>
110 <li>
111 <a href="http://wiki.apache.org/ant/FrontPage">Wiki</a>
112 </li>
113 <li>
114 <a href="./problems.html">Having Problems?</a>
115 </li>
116 </ul>
117 </li>
118 <li class="menuheader">Download
119 <ul>
120 <li>
121 <a href="http://ant.apache.org/bindownload.cgi">Binary Distributions</a>
122 </li>
123 <li>
124 <a href="http://ant.apache.org/srcdownload.cgi">Source Distributions</a>
125 </li>
126 </ul>
127 </li>
128 <li class="menuheader">Contributing
129 <ul>
130 <li>
131 <a href="./mail.html">Mailing Lists</a>
132 </li>
133 <li>
134 <a href="./cvs.html">CVS Repositories</a>
135 </li>
136 <li>
137 <a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Ant">Bug Database</a>
138 </li>
139 <li>
140 <a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Ant&amp;bug_severity=Enhancement">Enhancement Requests</a>
141 </li>
142 <li>
143 <a href="http://www.apache.org/foundation/contributing.html">Donations</a>
144 </li>
145 </ul>
146 </li>
147 <li class="menuheader">Project Management
148 <ul>
149 <li>
150 <a href="./contributors.html">Contributors</a>
151 </li>
152 <li>
153 <a href="./mission.html">Apache Ant Mission</a>
154 </li>
155 <li>
156 <a href="./bylaws.html">Project Bylaws</a>
157 </li>
158 <li>
159 <a href="./legal.html">Legal</a>
160 </li>
161 </ul>
162 </li>
163 </ul>
164 </div>
165 <img style="float: left" height="10" width="10" border="0" alt="" src="./images/menu-left.gif">
166 <img style="float: right" height="10" width="10" border="0" alt="" src="./images/menu-right.gif">
167 </div>
168 <div class="lightbluebar">&nbsp;</div>
169 <div class="main">
170 <div class="content">
171 <h1 class="title">Frequently Asked Questions</h1>
172
173 <h3 class="section">Questions</h3>
174 <h4 class="toc">About this FAQ</h4>
175 <ul>
176 <li><a href="#latest-version">
177 Where do I find the latest version of this
178 document?
179 </a></li>
180 <li><a href="#adding-faqs">
181 How can I contribute to this FAQ?
182 </a></li>
183 <li><a href="#creating-faq">
184 How do you create the HTML version of this
185 FAQ?
186 </a></li>
187 </ul>
188 <h4 class="toc">General</h4>
189 <ul>
190 <li><a href="#what-is-ant">
191 What is Apache Ant?
192 </a></li>
193 <li><a href="#ant-name">
194 Why do you call it Ant?
195 </a></li>
196 <li><a href="#history">
197 Tell us a little bit about Ant's history.
198 </a></li>
199 </ul>
200 <h4 class="toc">Installation</h4>
201 <ul>
202 <li><a href="#no-gnu-tar">
203 I get checksum errors when I try to extract the
204 <code>tar.gz</code> distribution file. Why?
205 </a></li>
206 </ul>
207 <h4 class="toc">How do I ...</h4>
208 <ul>
209 <li><a href="#implement-os-specific-configuration">
210 How do I realize os--specific configurations?
211 </a></li>
212 <li><a href="#adding-external-tasks">
213 How do I add an external task that I've written to the
214 page "External Tools and Task"?
215 </a></li>
216 <li><a href="#passing-cli-args">
217 How do I pass parameters from the command line to my
218 build file?
219 </a></li>
220 <li><a href="#jikes-switches">
221 How can I use Jikes-specific command-line
222 switches?
223 </a></li>
224 <li><a href="#shell-redirect-1">
225 How do I include a &lt; character in my command-line arguments?
226 </a></li>
227 <li><a href="#shell-redirect-2">
228 How do I redirect standard input or standard output
229 in the <code>&lt;exec&gt;</code> task?
230 </a></li>
231 <li><a href="#batch-shell-execute">
232 How do I execute a batch file or shell script from Ant?
233 </a></li>
234 <li><a href="#multi-conditions">
235 I want to execute a particular target only if
236 multiple conditions are true.
237 </a></li>
238 <li><a href="#encoding">
239 How can I include national characters like German
240 umlauts in my build file?
241 </a></li>
242 <li><a href="#use-zip-instead-of-jar">
243 How do I use <code>jar</code>'s <code>M</code> switch?
244 I don't want a MANIFEST.
245 </a></li>
246 <li><a href="#propertyvalue-as-name-for-property">
247 How can I do something like <code>&lt;property name="prop"
248 value="${${anotherprop}}"/&gt;</code> (double expanding the property)?
249 </a></li>
250 </ul>
251 <h4 class="toc">It doesn't work (as expected)</h4>
252 <ul>
253 <li><a href="#always-recompiles">
254 Why does Ant always recompile all my Java files?
255 </a></li>
256 <li><a href="#defaultexcludes">
257 I've used a <code>&lt;delete&gt;</code> task to
258 delete unwanted SourceSafe control files (CVS files, editor
259 backup files, etc.), but it doesn't seem to work; the files
260 never get deleted. What's wrong?
261 </a></li>
262 <li><a href="#stop-dependency">
263 I have a target I want to skip if a property is set,
264 so I have <code>unless="property"</code> as an attribute
265 of the target, but all the targets this target
266 depends on are still executed. Why?
267 </a></li>
268 <li><a href="#include-order">
269 In my <code>&lt;fileset&gt;</code>, I've put in an
270 <code>&lt;exclude&gt;</code> of all files followed by an
271 <code>&lt;include&gt;</code> of just the files I want, but it
272 isn't giving me any files at all. What's wrong?
273
274 </a></li>
275 <li><a href="#properties-not-trimmed">
276 <code>ant</code> failed to build my program via javac
277 even when I put the needed jars in an external
278 <code>build.properties</code> file and reference them by
279 <code>pathelement</code> or <code>classpath refid</code>.
280 </a></li>
281 <li><a href="#winzip-lies">
282 Ant creates WAR files with a lower-case
283 <code>web-inf</code> or JAR files with a lower-case
284 <code>meta-inf</code> directory.
285 </a></li>
286 </ul>
287 <h4 class="toc">Ant and IDEs/Editors</h4>
288 <ul>
289 <li><a href="#integration">
290 Is Ant supported by my IDE/Editor?
291 </a></li>
292 <li><a href="#emacs-mode">
293 Why doesn't (X)Emacs/vi/MacOS X's project builder
294 correctly parse the error messages generated by Ant?
295 </a></li>
296 </ul>
297 <h4 class="toc">Advanced Issues</h4>
298 <ul>
299 <li><a href="#dtd">
300 Is there a DTD that I can use to validate my build
301 files?
302 </a></li>
303 <li><a href="#xml-entity-include">
304 How do I include an XML snippet in my build file?
305 </a></li>
306 <li><a href="#mail-logger">
307 How do I send an email with the result of my build
308 process?
309 </a></li>
310 <li><a href="#listener-properties">
311 How do I get at the properties that Ant was running
312 with from inside BuildListener?
313 </a></li>
314 </ul>
315 <h4 class="toc">Known Problems</h4>
316 <ul>
317 <li><a href="#remove-cr">
318 &lt;chmod&gt; or &lt;exec&gt; doesn't work in Ant
319 1.3 on Unix
320 </a></li>
321 <li><a href="#javadoc-cannot-execute">
322 JavaDoc failed: java.io.IOException: javadoc: cannot execute
323 </a></li>
324 <li><a href="#delegating-classloader">
325 &lt;style&gt; or &lt;junit&gt; ignores my
326 &lt;classpath&gt;
327 </a></li>
328 <li><a href="#winxp-jdk14-ant14">
329 When running Ant 1.4 on Windows XP and JDK 1.4, I get
330 various errors when trying to <code>&lt;exec&gt;</code>, fork
331 <code>&lt;java&gt;</code> or access environment
332 variables.
333 </a></li>
334 <li><a href="#1.5-cygwin-sh">
335 The <code>ant</code> wrapper script of Ant 1.5 fails
336 for Cygwin if <code>ANT_HOME</code> is set to a Windows style
337 path.
338 </a></li>
339 <li><a href="#1.5.2-zip-broken">
340 <code>&lt;zip&gt;</code> is broken in Ant 1.5.2.
341 </a></li>
342 <li><a href="#unknownelement.taskcontainer">
343
344 Why do my custom task containers see Unknown Elements in Ant 1.6
345 - they worked in Ant 1.5?
346
347 </a></li>
348 <li><a href="#java.exception.stacktrace">
349
350 The program I run via &lt;java&gt; throws an exception but I
351 can't seem to get the full stack trace.
352
353 </a></li>
354 <li><a href="#junit-no-runtime-xml">
355
356 Using format="xml", &lt;junit&gt; fails with a
357 <code>NoClassDefFoundError</code> if forked.
358
359 </a></li>
360 <li><a href="#xalan-jdk1.5">
361
362 <code>&lt;junitreport&gt;</code> doesn't work with JDK 1.5 but
363 worked fine with JDK 1.4.
364
365 </a></li>
366 </ul>
367
368 <h3 class="section">Answers</h3>
369 <p class="faq">
370 <a name="latest-version"></a>
371 Where do I find the latest version of this
372 document?
373 </p>
374 <p>The latest version can always be found at Ant's homepage
375 <a href="http://ant.apache.org/faq.html">http://ant.apache.org/faq.html</a>.</p>
376 <p class="faq">
377 <a name="adding-faqs"></a>
378 How can I contribute to this FAQ?
379 </p>
380 <p>The page you are looking it is generated from
381 <a href="http://cvs.apache.org/viewcvs.cgi/~checkout~/ant/xdocs/faq.xml">this</a>
382 document. If you want to add a new question, please submit
383 a patch against this document to one of Ant's mailing lists;
384 hopefully, the structure is self-explanatory.</p>
385 <p>If you don't know how to create a patch, see the patches
386 section of <a href="http://jakarta.apache.org/site/source.html">this
387 page</a>.</p>
388 <p class="faq">
389 <a name="creating-faq"></a>
390 How do you create the HTML version of this
391 FAQ?
392 </p>
393 <p>We use
394 <a href="http://jakarta.apache.org/velocity/anakia.html">Anakia</a>
395 to render the HTML version from the original XML file.</p>
396 <p>The Velocity stylesheets used to process the XML files can
397 be found in the <code>xdocs/stylesheets</code> subdirectory of
398 Ant's CVS repository - the build file
399 <code>docs.xml</code> at the top level of the ant CVS
400 module is used to drive Anakia.</p>
401 <p>This file assumes that you have the
402 <code>jakarta-site2</code> CVS module checked out as well, but
403 if you follow the instruction from Anakia's homepage, you
404 should get it to work without that. Just make sure all
405 required jars are in the task's classpath.</p>
406 <p class="faq">
407 <a name="what-is-ant"></a>
408 What is Apache Ant?
409 </p>
410 <p> Ant is a Java-based build tool. In theory, it is kind of
411 like Make, without Make's wrinkles and with the full
412 portability of pure Java code.</p>
413 <p class="faq">
414 <a name="ant-name"></a>
415 Why do you call it Ant?
416 </p>
417 <p>According to Ant's original author, James Duncan
418 Davidson, the name is an acronym for "Another Neat
419 Tool".</p>
420 <p>Later explanations go along the lines of "ants
421 do an extremely good job at building things", or
422 "ants are very small and can carry a weight dozens of times
423 their own" - describing what Ant is intended to
424 be.</p>
425 <p class="faq">
426 <a name="history"></a>
427 Tell us a little bit about Ant's history.
428 </p>
429 <p>Initially, Ant was part of the Tomcat code base, when it was
430 donated to the Apache Software Foundation. It was
431 created by James Duncan Davidson, who is also the original
432 author of Tomcat. Ant was there to build Tomcat, nothing
433 else.</p>
434 <p>Soon thereafter, several open source Java projects realized
435 that Ant could solve the problems they had with Makefiles.
436 Starting with the projects hosted at Jakarta and the old Java
437 Apache project, Ant spread like a virus and is now the build
438 tool of choice for a lot of projects.</p>
439 <p>In January 2000, Ant was moved to a separate CVS module and
440 was promoted to a project of its own, independent of
441 Tomcat, and became Apache Ant.</p>
442 <p>The first version of Ant that was exposed to a larger audience
443 was the one that shipped with Tomcat's 3.1 release on 19 April
444 2000. This version has later been referred to as Ant
445 0.3.1.</p>
446 <p>The first official release of Ant as a stand-alone product was
447 Ant 1.1, released on 19 July 2000. The complete release
448 history:</p>
449 <table class="ForrestTable" cellspacing="1" cellpadding="4">
450 <tr>
451 <th colspan="1" rowspan="1"
452 valign="top" align="left">
453 Ant Version
454 </th>
455 <th colspan="1" rowspan="1"
456 valign="top" align="left">
457 Release Date
458 </th>
459 </tr>
460 <tr>
461 <td colspan="1" rowspan="1"
462 valign="top" align="left">
463 1.1
464 </td>
465 <td colspan="1" rowspan="1"
466 valign="top" align="left">
467 19 July 2000
468 </td>
469 </tr>
470 <tr>
471 <td colspan="1" rowspan="1"
472 valign="top" align="left">
473 1.2
474 </td>
475 <td colspan="1" rowspan="1"
476 valign="top" align="left">
477 24 October 2000
478 </td>
479 </tr>
480 <tr>
481 <td colspan="1" rowspan="1"
482 valign="top" align="left">
483 1.3
484 </td>
485 <td colspan="1" rowspan="1"
486 valign="top" align="left">
487 3 March 2001
488 </td>
489 </tr>
490 <tr>
491 <td colspan="1" rowspan="1"
492 valign="top" align="left">
493 1.4
494 </td>
495 <td colspan="1" rowspan="1"
496 valign="top" align="left">
497 3 September 2001
498 </td>
499 </tr>
500 <tr>
501 <td colspan="1" rowspan="1"
502 valign="top" align="left">
503 1.4.1
504 </td>
505 <td colspan="1" rowspan="1"
506 valign="top" align="left">
507 11 October 2001
508 </td>
509 </tr>
510 <tr>
511 <td colspan="1" rowspan="1"
512 valign="top" align="left">
513 1.5
514 </td>
515 <td colspan="1" rowspan="1"
516 valign="top" align="left">
517 10 July 2002
518 </td>
519 </tr>
520 <tr>
521 <td colspan="1" rowspan="1"
522 valign="top" align="left">
523 1.5.1
524 </td>
525 <td colspan="1" rowspan="1"
526 valign="top" align="left">
527 3 October 2002
528 </td>
529 </tr>
530 <tr>
531 <td colspan="1" rowspan="1"
532 valign="top" align="left">
533 1.5.2
534 </td>
535 <td colspan="1" rowspan="1"
536 valign="top" align="left">
537 3 March 2003
538 </td>
539 </tr>
540 <tr>
541 <td colspan="1" rowspan="1"
542 valign="top" align="left">
543 1.5.3
544 </td>
545 <td colspan="1" rowspan="1"
546 valign="top" align="left">
547 9 April 2003
548 </td>
549 </tr>
550 <tr>
551 <td colspan="1" rowspan="1"
552 valign="top" align="left">
553 1.5.4
554 </td>
555 <td colspan="1" rowspan="1"
556 valign="top" align="left">
557 12 August 2003
558 </td>
559 </tr>
560 <tr>
561 <td colspan="1" rowspan="1"
562 valign="top" align="left">
563 1.6.0
564 </td>
565 <td colspan="1" rowspan="1"
566 valign="top" align="left">
567 18 December 2003
568 </td>
569 </tr>
570 <tr>
571 <td colspan="1" rowspan="1"
572 valign="top" align="left">
573 1.6.1
574 </td>
575 <td colspan="1" rowspan="1"
576 valign="top" align="left">
577 12 February 2004
578 </td>
579 </tr>
580 <tr>
581 <td colspan="1" rowspan="1"
582 valign="top" align="left">
583 1.6.2
584 </td>
585 <td colspan="1" rowspan="1"
586 valign="top" align="left">
587 16 July 2004
588 </td>
589 </tr>
590 </table>
591 <p class="faq">
592 <a name="no-gnu-tar"></a>
593 I get checksum errors when I try to extract the
594 <code>tar.gz</code> distribution file. Why?
595 </p>
596 <p>Ant's distribution contains file names that are longer
597 than 100 characters, which is not supported by the standard
598 tar file format. Several different implementations of tar use
599 different and incompatible ways to work around this
600 restriction.</p>
601 <p>Ant's &lt;tar&gt; task can create tar archives that use
602 the GNU tar extension, and this has been used when putting
603 together the distribution. If you are using a different
604 version of tar (for example, the one shipping with Solaris),
605 you cannot use it to extract the archive.</p>
606 <p>The solution is to either install GNU tar, which can be
607 found <a href="http://www.gnu.org/software/tar/tar.html">here</a>,
608 or use the zip archive instead (you can extract it using
609 <code>jar xf</code>).</p>
610 <p class="faq">
611 <a name="implement-os-specific-configuration"></a>
612 How do I realize os--specific configurations?
613 </p>
614 <p>The core idea is using property files which name accords to the
615 os-name. Then simply use the build-in property <tt>os.name</tt>.</p>
616 <p>For better use you should also provide a file with defaul values.
617 But be careful with the correct os-names. For test simply &lt;echo&gt;
618 the ${os.name} on all machines and you can be sure to use the right
619 file names.</p>
620 <pre class="code">
621 &lt;property file=&quot;${os.name}.properties&quot;/&gt;
622 &lt;property file=&quot;default.properties&quot;/&gt;
623</pre>
624 <p class="faq">
625 <a name="adding-external-tasks"></a>
626 How do I add an external task that I've written to the
627 page "External Tools and Task"?
628 </p>
629 <p>Join and post a message to the dev or user mailing
630 list (one list is enough), including the following
631 information:</p>
632 <ul>
633 <li>the name of the task/tool</li>
634 <li>a short description of the task/tool</li>
635 <li>a Compatibility: entry stating with which version(s) of
636 Ant the tool/task is compatible to</li>
637 <li>a URL: entry linking to the main page of the tool/task</li>
638 <li>a Contact: entry containing the email address or the URL
639 of a webpage for the person or list to contact for issues
640 related to the tool/task. <strong>Note that we'll add a
641 link on the page, so any email address added there is not
642 obfuscated and can (and probably will) be abused by robots
643 harvesting websites for addresses to spam.</strong></li>
644 <li>a License: entry containing the type of license for the
645 tool/task</li>
646 </ul>
647 <p>The preferred format for this information is a patch to <a href="http://cvs.apache.org/viewcvs.cgi/~checkout~/ant/xdocs/external.xml">this</a>
648 document.</p>
649 <p>If you have written something bigger than a 'simple plugin' to Ant it
650 may be better to add the link to <a href="projects.html">projects.html</a>.
651 The procedure to add it is the same. The file to patch is <a href="http://cvs.apache.org/viewcvs.cgi/~checkout~/ant/xdocs/projects.xml">this</a>
652 document. The syntax of that file is the same.</p>
653 <p class="faq">
654 <a name="passing-cli-args"></a>
655 How do I pass parameters from the command line to my
656 build file?
657 </p>
658 <p>Use properties. Using <code>ant
659 -D<em>name</em>=<em>value</em></code> lets you define values for
660 properties on the Ant command line. These properties can then be
661 used within your build file as
662 any normal property: <code>${<em>name</em>}</code> will put in
663 <code><em>value</em></code>.</p>
664 <p class="faq">
665 <a name="jikes-switches"></a>
666 How can I use Jikes-specific command-line
667 switches?
668 </p>
669 <p>A couple of switches are supported via "magic"
670 properties:</p>
671 <table class="ForrestTable" cellspacing="1" cellpadding="4">
672 <tr>
673 <th colspan="1" rowspan="1"
674 valign="top" align="left">
675 switch
676 </th>
677 <th colspan="1" rowspan="1"
678 valign="top" align="left">
679 property
680 </th>
681 <th colspan="1" rowspan="1"
682 valign="top" align="left">
683 default
684 </th>
685 </tr>
686 <tr>
687 <td colspan="1" rowspan="1"
688 valign="top" align="left">
689 +E
690 </td>
691 <td colspan="1" rowspan="1"
692 valign="top" align="left">
693 build.compiler.emacs
694 </td>
695 <td colspan="1" rowspan="1"
696 valign="top" align="left">
697 false == not set
698 </td>
699 </tr>
700 <tr>
701 <td colspan="1" rowspan="1"
702 valign="top" align="left">
703 +P
704 </td>
705 <td colspan="1" rowspan="1"
706 valign="top" align="left">
707 build.compiler.pedantic
708 </td>
709 <td colspan="1" rowspan="1"
710 valign="top" align="left">
711 false == not set
712 </td>
713 </tr>
714 <tr>
715 <td colspan="1" rowspan="1"
716 valign="top" align="left">
717 +F
718 </td>
719 <td colspan="1" rowspan="1"
720 valign="top" align="left">
721 build.compiler.fulldepend
722 </td>
723 <td colspan="1" rowspan="1"
724 valign="top" align="left">
725 false == not set
726 </td>
727 </tr>
728 <tr>
729 <td colspan="1" rowspan="1"
730 valign="top" align="left">
731 <strong>(Only for Ant &lt; 1.4; replaced by the
732 <code><strong>nowarn</strong></code>
733 attribute of the <code><strong>&lt;javac&gt;</strong></code>
734 task after that.)</strong><br />-nowarn
735 </td>
736 <td colspan="1" rowspan="1"
737 valign="top" align="left">
738 build.compiler.warnings
739 </td>
740 <td colspan="1" rowspan="1"
741 valign="top" align="left">
742 true == not set
743 </td>
744 </tr>
745 </table>
746 <p>With Ant &gt;= 1.5, you can also use nested
747 <code>&lt;compilerarg&gt;</code> elements with the
748 <code>&lt;javac&gt;</code> task.</p>
749 <p class="faq">
750 <a name="shell-redirect-1"></a>
751 How do I include a &lt; character in my command-line arguments?
752 </p>
753 <p>The short answer is "Use: <code>&amp;lt;</code>".</p>
754 <p>The long answer is that this probably won't do what you
755 want anyway (see <a href="#shell-redirect-2">the next
756 section</a>).</p>
757 <p class="faq">
758 <a name="shell-redirect-2"></a>
759 How do I redirect standard input or standard output
760 in the <code>&lt;exec&gt;</code> task?
761 </p>
762 <p>Say you want to redirect the standard output stream of the
763 <code>m4</code> command to write to a file, something
764 like:</p>
765 <pre class="code">
766shell-prompt&gt; m4 foo.m4 &gt; foo
767</pre>
768 <p>and try to translate it into</p>
769 <pre class="code">
770&lt;exec executable=&quot;m4&quot;&gt;
771 &lt;arg value=&quot;foo.m4&quot;/&gt;
772 &lt;arg value=&quot;&amp;gt;&quot;/&gt;
773 &lt;arg value=&quot;foo&quot;/&gt;
774&lt;/exec&gt;
775</pre>
776 <p>This will not do what you expect. The output redirection is
777 performed by your shell, not the command itself, so this
778 should read:</p>
779 <pre class="code">
780&lt;exec executable=&quot;/bin/sh&quot;&gt;
781 &lt;arg value=&quot;-c&quot; /&gt;
782 &lt;arg value=&quot;m4 foo.m4 &amp;gt; foo&quot; /&gt;
783&lt;/exec&gt;
784</pre>
785 <p>Note that you must use the <code>value</code> attribute of
786 <code>&lt;arg&gt;</code> in the last element, in order to have
787 the command passed as a single, quoted argument. Alternatively,
788 you can use:</p>
789 <pre class="code">
790&lt;exec executable=&quot;/bin/sh&quot;&gt;
791 &lt;arg line='-c &quot;m4 foo.m4 &amp;gt; foo&quot;'/&gt;
792&lt;/exec&gt;
793</pre>
794 <p>Note the double-quotes nested inside the single-quotes.</p>
795 <p class="faq">
796 <a name="batch-shell-execute"></a>
797 How do I execute a batch file or shell script from Ant?
798 </p>
799 <p>On native Unix systems, you should be able to run shell scripts
800 directly. On systems running a Unix-type shell (for example, Cygwin
801 on Windows) execute the (command) shell instead - <code>cmd</code>
802 for batch files, <code>sh</code> for shell scripts - then pass the
803 batch file or shell script (plus any arguments to the script)
804 as a single command, using the <code>/c</code> or
805 <code>-c</code> switch, respectively. See
806 <a href="#shell-redirect-2">the above section</a>
807 for example <code>&lt;exec&gt;</code> tasks
808 executing <code>sh</code>. For batch files, use something like:</p>
809 <pre class="code">
810&lt;exec dir=&quot;.&quot; executable=&quot;cmd&quot; os=&quot;Windows NT&quot;&gt;
811 &lt;arg line=&quot;/c test.bat&quot;/&gt;
812&lt;/exec&gt;
813</pre>
814 <p class="faq">
815 <a name="multi-conditions"></a>
816 I want to execute a particular target only if
817 multiple conditions are true.
818 </p>
819 <p>There are actually several answers to this question.</p>
820 <p>If you have only one set and one unset property to test,
821 you can specify both an <code>if</code> and an <code>unless</code>
822 attribute for the target, and they will act as if they
823 are "anded" together.</p>
824 <p>If you are using a version of Ant 1.3 or earlier, the
825 way to work with all other cases is to chain targets together
826 to determine the specific state you want to test for.</p>
827 <p>To see how this works, assume you have three properties:
828 <code>prop1</code>, <code>prop2</code>, and <code>prop3</code>.
829 You want to test that <code>prop1</code> and <code>prop2</code>
830 are set, and that <code>prop3</code> is not. If the condition
831 holds true you want to echo "yes".</p>
832 <p>Here is the implementation in Ant 1.3 and earlier:</p>
833 <pre class="code">
834&lt;target name=&quot;cond&quot; depends=&quot;cond-if&quot;/&gt;
835
836&lt;target name=&quot;cond-if&quot; if=&quot;prop1&quot;&gt;
837 &lt;antcall target=&quot;cond-if-2&quot;/&gt;
838&lt;/target&gt;
839
840&lt;target name=&quot;cond-if-2&quot; if=&quot;prop2&quot;&gt;
841 &lt;antcall target=&quot;cond-if-3&quot;/&gt;
842&lt;/target&gt;
843
844&lt;target name=&quot;cond-if-3&quot; unless=&quot;prop3&quot;&gt;
845 &lt;echo message=&quot;yes&quot;/&gt;
846&lt;/target&gt;
847</pre>
848 <p>Note: <code>&lt;antcall&gt;</code> tasks do <em>not</em> pass
849 property changes back up to the environment they were called
850 from, so you would'nt be able to, for example, set a
851 <code>result</code> property in the <code>cond-if-3</code> target,
852 then do
853 <code>&lt;echo message="result is ${result}"/&gt;</code>
854 in the <code>cond</code> target.</p>
855 <p>Starting with Ant 1.4, you can use the
856 <code>&lt;condition&gt;</code> task.</p>
857 <pre class="code">
858&lt;target name=&quot;cond&quot; depends=&quot;cond-if,cond-else&quot;/&gt;
859
860&lt;target name=&quot;check-cond&quot;&gt;
861 &lt;condition property=&quot;cond-is-true&quot;&gt;
862 &lt;and&gt;
863 &lt;not&gt;
864 &lt;equals arg1=&quot;${prop1}&quot; arg2=&quot;$${prop1}&quot; /&gt;
865 &lt;/not&gt;
866 &lt;not&gt;
867 &lt;equals arg1=&quot;${prop2}&quot; arg2=&quot;$${prop2}&quot; /&gt;
868 &lt;/not&gt;
869 &lt;equals arg1=&quot;${prop3}&quot; arg2=&quot;$${prop3}&quot; /&gt;
870 &lt;/and&gt;
871 &lt;/condition&gt;
872&lt;/target&gt;
873
874&lt;target name=&quot;cond-if&quot; depends=&quot;check-cond&quot; if=&quot;cond-is-true&quot;&gt;
875 &lt;echo message=&quot;yes&quot;/&gt;
876&lt;/target&gt;
877
878&lt;target name=&quot;cond-else&quot; depends=&quot;check-cond&quot; unless=&quot;cond-is-true&quot;&gt;
879 &lt;echo message=&quot;no&quot;/&gt;
880&lt;/target&gt;
881</pre>
882 <p>This version takes advantage of two things:</p>
883 <ul>
884 <li>If a property <code>a</code> has not been set,
885 <code>${a}</code> will evaluate to <code>${a}</code>.</li>
886
887 <li>To get a literal <code>$</code> in Ant, you have to
888 escape it with another <code>$</code> - this will also break
889 the special treatment of the <code>${</code> sequence.</li>
890 </ul>
891 <p>Because testing for a literal <code>${property}</code> string
892 isn't all that readable or easy to understand,
893 post-1.4.1 Ant introduces the <code>&lt;isset&gt;</code> element
894 to the <code>&lt;condition&gt;</code> task.</p>
895 <p>Here is the previous example done using
896 <code>&lt;isset&gt;</code>:</p>
897 <pre class="code">
898&lt;target name=&quot;check-cond&quot;&gt;
899 &lt;condition property=&quot;cond-is-true&quot;&gt;
900 &lt;and&gt;
901 &lt;isset property=&quot;prop1&quot;/&gt;
902 &lt;isset property=&quot;prop2&quot;/&gt;
903 &lt;not&gt;
904 &lt;isset property=&quot;prop3&quot;/&gt;
905 &lt;/not&gt;
906 &lt;/and&gt;
907 &lt;/condition&gt;
908&lt;/target&gt;
909</pre>
910 <p>The last option is to use a scripting language to set the
911 properties. This can be particularly handy when you need much
912 finer control than the simple conditions shown here but, of
913 course, comes with the overhead of adding JAR files to support
914 the language, to say nothing of the added maintenance in requiring
915 two languages to implement a single system. See the
916 <a href="manual/OptionalTasks/script.html">
917 <code>&lt;script&gt;</code> task documentation</a> for more
918 details.</p>
919 <p class="faq">
920 <a name="encoding"></a>
921 How can I include national characters like German
922 umlauts in my build file?
923 </p>
924 <p>You need to tell the XML parser which character encoding
925 your build file uses, this is done inside the <a href="http://www.w3.org/TR/2000/REC-xml-20001006#sec-prolog-dtd">XML
926 declaration</a>.</p>
927 <p>By default the parser assumes you are using the UTF-8
928 encoding instead of your platform's default. For most Western
929 European countries you should set the encoding to
930 <code>ISO-8859-1</code>. To do so, make the very first line
931 of you build file read like</p>
932 <pre class="code">
933&lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot; ?&gt;
934</pre>
935 <p class="faq">
936 <a name="use-zip-instead-of-jar"></a>
937 How do I use <code>jar</code>'s <code>M</code> switch?
938 I don't want a MANIFEST.
939 </p>
940 <p>A JAR archive is a ZIP file, so if you don't want a
941 MANIFEST you can simply use <code>&lt;zip&gt;</code>.</p>
942 <p>If your file names contain national characters you should
943 know that Sun's <code>jar</code> utility like Ant's
944 <code>&lt;jar&gt;</code> uses UFT8 to encode their names while
945 <code>&lt;zip&gt;</code> uses your platforms default encoding.
946 Use the encoding attribute of <code>&lt;zip&gt;</code> if
947 necessary.</p>
948 <p class="faq">
949 <a name="propertyvalue-as-name-for-property"></a>
950 How can I do something like <code>&lt;property name="prop"
951 value="${${anotherprop}}"/&gt;</code> (double expanding the property)?
952 </p>
953 <p>Without any external help you can not.</p>
954 <p>With &lt;script/&gt;, which needs external libraries, you can do</p>
955 <pre class="code">
956&lt;script language=&quot;javascript&quot;&gt;
957 propname = project.getProperty(&quot;anotherprop&quot;);
958 project.setNewProperty(&quot;prop&quot;, propname);
959&lt;/script&gt;
960</pre>
961 <p>With AntContrib (external task library) you can do <code>
962 &lt;propertycopy name="prop" from="${anotherprop}"/&gt;</code>.</p>
963 <p>With Ant 1.6 you can simulate the AntContribs &lt;propertycopy&gt;
964 and avoid the need of an external library:</p>
965 <pre class="code">
966&lt;macrodef name=&quot;propertycopy&quot;&gt;
967 &lt;attribute name=&quot;name&quot;/&gt;
968 &lt;attribute name=&quot;from&quot;/&gt;
969 &lt;sequential&gt;
970 &lt;property name=&quot;@{name}&quot; value=&quot;${@{from}}&quot;/&gt;
971 &lt;/sequential&gt;
972&lt;/macrodef&gt;
973</pre>
974 <p class="faq">
975 <a name="always-recompiles"></a>
976 Why does Ant always recompile all my Java files?
977 </p>
978 <p>In order to find out which files should be compiled, Ant
979 compares the timestamps of the source files to those of the
980 resulting <code>.class</code> files. Opening all source files
981 to find out which package they belong to would be very
982 inefficient. Instead, Ant expects you to place your
983 source files in a directory hierarchy that mirrors your
984 package hierarchy and to point Ant to the root of this
985 directory tree with the <code>srcdir</code> attribute.</p>
986 <p>Say you have <code>&lt;javac srcdir="src"
987 destdir="dest"/&gt;</code>. If Ant finds a file
988 <code>src/a/b/C.java</code>, it expects it to be in package
989 <code>a.b</code> so that the resulting <code>.class</code>
990 file is going to be <code>dest/a/b/C.class</code>.</p>
991 <p>If your source-tree directory structure does not match your
992 package structure, Ant's heuristic won't work, and
993 it will recompile classes that are up-to-date. Ant is not the
994 only tool that expects a source-tree layout like this.</p>
995 <p>If you have Java source files that aren't declared to
996 be part of any package, you can still use the <code>&lt;javac&gt;</code>
997 task to compile these files correctly - just set the
998 <code>srcdir</code> and <code>destdir</code> attributes to
999 the actual directory the source
1000 files live in and the directory the class files should go into,
1001 respectively.</p>
1002 <p class="faq">
1003 <a name="defaultexcludes"></a>
1004 I've used a <code>&lt;delete&gt;</code> task to
1005 delete unwanted SourceSafe control files (CVS files, editor
1006 backup files, etc.), but it doesn't seem to work; the files
1007 never get deleted. What's wrong?
1008 </p>
1009 <p>This is probably happening because, by default, Ant excludes
1010 SourceSafe control files (<code>vssver.scc</code>) and certain other
1011 files from FileSets.</p>
1012 <p>Here's what you probably did:</p>
1013 <pre class="code">
1014&lt;delete&gt;
1015 &lt;fileset dir=&quot;${build.src}&quot; includes=&quot;**/vssver.scc&quot;/&gt;
1016&lt;/delete&gt;
1017</pre>
1018 <p>You need to switch off the default exclusions,
1019 and it will work:</p>
1020 <pre class="code">
1021&lt;delete&gt;
1022 &lt;fileset dir=&quot;${build.src}&quot; includes=&quot;**/vssver.scc&quot;
1023 defaultexcludes=&quot;no&quot;/&gt;
1024&lt;/delete&gt;
1025</pre>
1026 <p>For a complete listing of the patterns that are excluded
1027 by default, see <a href="manual/dirtasks.html#defaultexcludes">the user
1028 manual</a>.</p>
1029 <p class="faq">
1030 <a name="stop-dependency"></a>
1031 I have a target I want to skip if a property is set,
1032 so I have <code>unless="property"</code> as an attribute
1033 of the target, but all the targets this target
1034 depends on are still executed. Why?
1035 </p>
1036 <p>The list of dependencies is generated by Ant before any of the
1037 targets are run. This allows dependent targets, such as an
1038 <code>init</code> target, to set properties that can control the
1039 execution of the targets higher in the dependency graph. This
1040 is a good thing.</p>
1041 <p>However, when your dependencies break down the
1042 higher-level task
1043 into several smaller steps, this behaviour becomes
1044 counter-intuitive. There are a couple of solutions available:
1045 </p>
1046 <ol>
1047 <li>Put the same condition on each of the dependent targets.</li>
1048
1049 <li>Execute the steps using <code>&lt;antcall&gt;</code>,
1050 instead of specifying them inside the <code>depends</code>
1051 attribute.</li>
1052 </ol>
1053 <p class="faq">
1054 <a name="include-order"></a>
1055 In my <code>&lt;fileset&gt;</code>, I've put in an
1056 <code>&lt;exclude&gt;</code> of all files followed by an
1057 <code>&lt;include&gt;</code> of just the files I want, but it
1058 isn't giving me any files at all. What's wrong?
1059
1060 </p>
1061 <p>The order of the <code>&lt;include&gt;</code> and
1062 <code>&lt;exclude&gt;</code> tags within a <code>&lt;fileset&gt;</code>
1063 is ignored when the FileSet is created. Instead, all of the
1064 <code>&lt;include&gt;</code> elements are processed together,
1065 followed by all of the <code>&lt;exclude&gt;</code>
1066 elements. This means that the <code>&lt;exclude&gt;</code>
1067 elements only apply to the file list produced by the
1068 <code>&lt;include&gt;</code> elements.</p>
1069 <p>To get the files you want, focus on just the
1070 <code>&lt;include&gt;</code> patterns that would be necessary
1071 to get them. If you find you need to trim the list that the
1072 <code>&lt;include&gt;</code> elements produce, then use
1073 <code>&lt;exclude&gt;</code> elements.</p>
1074 <p class="faq">
1075 <a name="properties-not-trimmed"></a>
1076 <code>ant</code> failed to build my program via javac
1077 even when I put the needed jars in an external
1078 <code>build.properties</code> file and reference them by
1079 <code>pathelement</code> or <code>classpath refid</code>.
1080 </p>
1081 <p>When <code>ant</code> loads properties from an external
1082 file it dosn't touch the value of properties, trailing blanks
1083 will not be trimmed for example.</p>
1084 <p>If the value represents a file path, like a jar needed to
1085 compile, the task which requires the value, javac for example
1086 would fail to compile since it can't find the file due to
1087 trailing spaces.</p>
1088 <p class="faq">
1089 <a name="winzip-lies"></a>
1090 Ant creates WAR files with a lower-case
1091 <code>web-inf</code> or JAR files with a lower-case
1092 <code>meta-inf</code> directory.
1093 </p>
1094 <p>No it doesn't.</p>
1095 <p>You may have seen these lower-case directory names in
1096 WinZIP, but WinZIP is trying to be helpful (and fails). If
1097 WinZIP encounters a filename that is all upper-case, it
1098 assumes it has come from an old DOS box and changes the case to
1099 all lower-case for you.</p>
1100 <p>If you extract (or just check) the archive with jar, you
1101 will see that the names have the correct case.</p>
1102 <p>With WinZIP (version 8.1 at least), this can be corrected in the
1103 configuration. In the Options/Configuration menu, in the View tab, General
1104 section, check the "Allow all upper case files names" box. The META-INF and
1105 WEB-INF will look correct.</p>
1106 <p class="faq">
1107 <a name="integration"></a>
1108 Is Ant supported by my IDE/Editor?
1109 </p>
1110 <p>See the <a href="external.html#IDE and Editor Integration">section
1111 on IDE integration</a> on our External Tools and Tasks page.</p>
1112 <p class="faq">
1113 <a name="emacs-mode"></a>
1114 Why doesn't (X)Emacs/vi/MacOS X's project builder
1115 correctly parse the error messages generated by Ant?
1116 </p>
1117 <p>Ant adds a "banner" with the name of the current
1118 task in front of all logging messages - and there are no built-in
1119 regular expressions in your editor that would account for
1120 this.</p>
1121 <p>You can disable this banner by invoking Ant with the
1122 <code>-emacs</code> switch. To make Ant autodetect
1123 Emacs' compile mode, put this into your
1124 <code>.antrc</code> (contributed by Ville Skyttä).</p>
1125 <pre class="code">
1126# Detect (X)Emacs compile mode
1127if [ &quot;$EMACS&quot; = &quot;t&quot; ] ; then
1128 ANT_ARGS=&quot;$ANT_ARGS -emacs&quot;
1129 ANT_OPTS=&quot;$ANT_OPTS -Dbuild.compiler.emacs=true&quot;
1130fi
1131</pre>
1132 <p>Alternatively, you can add the following snippet to your
1133 <code>.emacs</code> to make Emacs understand Ant's
1134 output.</p>
1135 <pre class="code">
1136(require 'compile)
1137(setq compilation-error-regexp-alist
1138 (append (list
1139 ;; works for jikes
1140 '(&quot;^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):\\([0-9]+\\):[0-9]+:[0-9]+:&quot; 1 2 3)
1141 ;; works for javac
1142 '(&quot;^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):&quot; 1 2))
1143 compilation-error-regexp-alist))
1144</pre>
1145 <p>Yet another alternative that preserves most of Ant's
1146 formatting is to pipe Ant's output through the following Perl
1147 script by Dirk-Willem van Gulik:</p>
1148 <pre class="code">
1149#!/usr/bin/perl
1150#
1151# May 2001 [email protected] - remove any
1152# [foo] lines from the output; keeping
1153# spacing more or less there.
1154#
1155$|=1;
1156while(&lt;STDIN&gt;) {
1157 if (s/^(\s+)\[(\w+)\]//) {
1158 if ($2 ne $last) {
1159 print &quot;$1\[$2\]&quot;;
1160 $s = ' ' x length($2);
1161 } else {
1162 print &quot;$1 $s &quot;;
1163 };
1164 $last = $2;
1165 };
1166 print;
1167};
1168</pre>
1169 <p class="faq">
1170 <a name="dtd"></a>
1171 Is there a DTD that I can use to validate my build
1172 files?
1173 </p>
1174 <p>An incomplete DTD can be created by the
1175 <code>&lt;antstructure&gt;</code> task - but this one
1176 has a few problems:</p>
1177 <ul>
1178 <li>It doesn't know about required attributes. Only
1179 manual tweaking of this file can help here.</li>
1180
1181 <li>It is not complete - if you add new tasks via
1182 <code>&lt;taskdef&gt;</code> it won't know about it. See
1183 <a href="http://www.sdv.fr/pages/casa/html/ant-dtd.en.html">this
1184 page</a> by Michel Casabianca for a solution to this
1185 problem. Note that the DTD you can download at this page
1186 is based on Ant 0.3.1.</li>
1187
1188 <li>It may even be an invalid DTD. As Ant allows tasks
1189 writers to define arbitrary elements, name collisions will
1190 happen quite frequently - if your version of Ant contains
1191 the optional <code>&lt;test&gt;</code> and
1192 <code>&lt;junit&gt;</code> tasks, there are two XML
1193 elements named <code>test</code> (the task and the nested child
1194 element of <code>&lt;junit&gt;</code>) with different attribute
1195 lists. This problem cannot be solved; DTDs don't give a
1196 syntax rich enough to support this.</li>
1197 </ul>
1198 <p class="faq">
1199 <a name="xml-entity-include"></a>
1200 How do I include an XML snippet in my build file?
1201 </p>
1202 <p>You can use XML's way of including external files and let
1203 the parser do the job for Ant:</p>
1204 <pre class="code">
1205&lt;?xml version=&quot;1.0&quot;?&gt;
1206
1207&lt;!DOCTYPE project [
1208 &lt;!ENTITY common SYSTEM &quot;file:./common.xml&quot;&gt;
1209]&gt;
1210
1211&lt;project name=&quot;test&quot; default=&quot;test&quot; basedir=&quot;.&quot;&gt;
1212
1213 &lt;target name=&quot;setup&quot;&gt;
1214 ...
1215 &lt;/target&gt;
1216
1217 &amp;common;
1218
1219 ...
1220
1221&lt;/project&gt;
1222</pre>
1223 <p>will literally include the contents of <code>common.xml</code> where
1224 you've placed the <code>&amp;common;</code> entity.</p>
1225 <p>In combination with a DTD, this would look like this:</p>
1226 <pre class="code">
1227&lt;!DOCTYPE project PUBLIC &quot;-//ANT//DTD project//EN&quot; &quot;file:./ant.dtd&quot; [
1228 &lt;!ENTITY include SYSTEM &quot;file:./header.xml&quot;&gt;
1229]&gt;
1230</pre>
1231 <p>Starting with Ant 1.6, there is a new
1232 <code>&lt;import&gt;</code> task that can (also) be used to
1233 include build file fragments. Unlike the snippets used with
1234 entity includes, the referenced files have to be complete Ant
1235 build files, though.</p>
1236 <p>The example above would become:</p>
1237 <pre class="code">
1238&lt;?xml version=&quot;1.0&quot;?&gt;
1239&lt;project name=&quot;test&quot; default=&quot;test&quot; basedir=&quot;.&quot;&gt;
1240
1241 &lt;target name=&quot;setup&quot;&gt;
1242 ...
1243 &lt;/target&gt;
1244
1245 &lt;import file=&quot;./common.xml&quot;/&gt;
1246
1247 ...
1248
1249&lt;/project&gt;
1250</pre>
1251 <p>Unlike entity includes, <code>&lt;import&gt;</code> will
1252 let you use Ant properties in the file name.</p>
1253 <p class="faq">
1254 <a name="mail-logger"></a>
1255 How do I send an email with the result of my build
1256 process?
1257 </p>
1258 <p>If you are using a nightly build of Ant 1.5 after
1259 2001-12-14, you can use the built-in MailLogger:</p>
1260 <pre class="code">
1261 ant -logger org.apache.tools.ant.listener.MailLogger
1262</pre>
1263 <p>See the <a href="http://cvs.apache.org/viewcvs/~checkout~/ant/docs/manual/listeners.html?content-type=text/html">Listeners
1264 &amp; Loggers</a> documentation for details on the properties
1265 required.</p>
1266 <p>For older versions of Ant, you can use a custom
1267 BuildListener that sends out an email
1268 in the buildFinished() method. Will Glozer
1269 &lt;[email protected]&gt; has written such a listener based
1270 on <a href="http://java.sun.com/products/javamail/">JavaMail</a>.
1271 The source is:</p>
1272 <pre class="code">
1273import java.io.*;
1274import java.util.*;
1275import javax.mail.*;
1276import javax.mail.internet.*;
1277import org.apache.tools.ant.*;
1278
1279/**
1280 * A simple listener that waits for a build to finish and sends an email
1281 * of the results. The settings are stored in &quot;monitor.properties&quot; and
1282 * are fairly self explanatory.
1283 *
1284 * @author Will Glozer
1285 * @version 1.05a 09/06/2000
1286 */
1287public class BuildMonitor implements BuildListener {
1288 protected Properties props;
1289
1290 /**
1291 * Create a new BuildMonitor.
1292 */
1293 public BuildMonitor() throws Exception {
1294 props = new Properties();
1295 InputStream is = getClass().getResourceAsStream(&quot;monitor.properties&quot;);
1296 props.load(is);
1297 is.close();
1298 }
1299
1300 public void buildStarted(BuildEvent e) {
1301 }
1302
1303 /**
1304 * Determine the status of the build and the actions to follow, now that
1305 * the build has completed.
1306 *
1307 * @param e Event describing the build status.
1308 */
1309 public void buildFinished(BuildEvent e) {
1310 Throwable th = e.getException();
1311 String status = (th != null) ? &quot;failed&quot; : &quot;succeeded&quot;;
1312
1313 try {
1314 String key = &quot;build.&quot; + status;
1315 if (props.getProperty(key + &quot;.notify&quot;).equalsIgnoreCase(&quot;false&quot;)) {
1316 return;
1317 }
1318
1319 Session session = Session.getDefaultInstance(props, null);
1320
1321 MimeMessage message = new MimeMessage(session);
1322 message.addRecipients(Message.RecipientType.TO, parseAddresses(
1323 props.getProperty(key + &quot;.email.to&quot;)));
1324 message.setSubject(props.getProperty(key + &quot;.email.subject&quot;));
1325
1326 BufferedReader br = new BufferedReader(new FileReader(
1327 props.getProperty(&quot;build.log&quot;)));
1328 StringWriter sw = new StringWriter();
1329
1330 String line = br.readLine();
1331 while (line != null) {
1332 sw.write(line);
1333 sw.write(&quot;\n&quot;);
1334 line = br.readLine();
1335 }
1336 br.close();
1337
1338 message.setText(sw.toString(), &quot;UTF-8&quot;);
1339 sw.close();
1340
1341 Transport transport = session.getTransport();
1342 transport.connect();
1343 transport.send(message);
1344 transport.close();
1345 } catch (Exception ex) {
1346 System.out.println(&quot;BuildMonitor failed to send email!&quot;);
1347 ex.printStackTrace();
1348 }
1349 }
1350
1351 /**
1352 * Parse a comma separated list of internet email addresses.
1353 *
1354 * @param s The list of addresses.
1355 * @return Array of Addresses.
1356 */
1357 protected Address[] parseAddresses(String s) throws Exception {
1358 StringTokenizer st = new StringTokenizer(s, &quot;,&quot;);
1359 Address[] addrs = new Address[st.countTokens()];
1360
1361 for (int i = 0; i &lt; addrs.length; i++) {
1362 addrs[i] = new InternetAddress(st.nextToken());
1363 }
1364 return addrs;
1365 }
1366
1367 public void messageLogged(BuildEvent e) {
1368 }
1369
1370 public void targetStarted(BuildEvent e) {
1371 }
1372
1373 public void targetFinished(BuildEvent e) {
1374 }
1375
1376 public void taskStarted(BuildEvent e) {
1377 }
1378
1379 public void taskFinished(BuildEvent e) {
1380 }
1381}
1382</pre>
1383 <p>With a <code>monitor.properties</code> like this:</p>
1384 <pre class="code">
1385# configuration for build monitor
1386
1387mail.transport.protocol=smtp
1388mail.smtp.host=&lt;host&gt;
1389mail.from=Will Glozer &lt;[email protected]&gt;
1390
1391build.log=build.log
1392
1393build.failed.notify=true
1394[email protected]
1395build.failed.email.subject=Nightly build failed!
1396
1397build.succeeded.notify=true
1398[email protected]
1399build.succeeded.email.subject=Nightly build succeeded!
1400</pre>
1401 <p><code>monitor.properties</code> should be placed right next
1402 to your compiled <code>BuildMonitor.class</code>. To use it,
1403 invoke Ant like:</p>
1404 <pre class="code">
1405ant -listener BuildMonitor -logfile build.log
1406</pre>
1407 <p>Make sure that <code>mail.jar</code> from JavaMail and
1408 <code>activation.jar</code> from the
1409 <a href="http://java.sun.com/products/javabeans/glasgow/jaf.html">Java
1410 Beans Activation Framework</a> are in your <code>CLASSPATH</code>.</p>
1411 <p class="faq">
1412 <a name="listener-properties"></a>
1413 How do I get at the properties that Ant was running
1414 with from inside BuildListener?
1415 </p>
1416 <p>You can get at a hashtable with all the properties that Ant
1417 has been using through the BuildEvent parameter. For
1418 example:</p>
1419 <pre class="code">
1420public void buildFinished(BuildEvent e) {
1421 Hashtable table = e.getProject().getProperties();
1422 String buildpath = (String)table.get(&quot;build.path&quot;);
1423 ...
1424}
1425</pre>
1426 <p>This is more accurate than just reading the same property
1427 files that your project does, since it will give the correct
1428 results for properties that were specified on the Ant command line.</p>
1429 <p class="faq">
1430 <a name="remove-cr"></a>
1431 &lt;chmod&gt; or &lt;exec&gt; doesn't work in Ant
1432 1.3 on Unix
1433 </p>
1434 <p>The <code>antRun</code> script in <code>ANT_HOME/bin</code>
1435 has DOS instead of Unix line endings; you must remove the
1436 carriage-return characters from this file. This can be done by
1437 using Ant's <code>&lt;fixcrlf&gt;</code> task
1438 or something like:</p>
1439 <pre class="code">
1440tr -d '\r' &lt; $ANT_HOME/bin/antRun &gt; /tmp/foo
1441mv /tmp/foo $ANT_HOME/bin/antRun
1442</pre>
1443 <p class="faq">
1444 <a name="javadoc-cannot-execute"></a>
1445 JavaDoc failed: java.io.IOException: javadoc: cannot execute
1446 </p>
1447 <p>There is a bug in the Solaris reference implementation of
1448 the JDK (see <a href="http://developer.java.sun.com/developer/bugParade/bugs/4230399.html">http://developer.java.sun.com/developer/bugParade/bugs/4230399.html</a>).
1449 This also appears to be true under Linux. Moving the JDK to
1450 the front of the PATH fixes the problem.</p>
1451 <p class="faq">
1452 <a name="delegating-classloader"></a>
1453 &lt;style&gt; or &lt;junit&gt; ignores my
1454 &lt;classpath&gt;
1455 </p>
1456 <p>These tasks don't ignore your classpath setting, you
1457 are facing a common problem with delegating classloaders.</p>
1458 <p>First of all let's state that Ant adds all
1459 <code>.jar</code> files from <code>ANT_HOME/lib</code> to
1460 <code>CLASSPATH</code>, therefore "in
1461 <code>CLASSPATH</code>" shall mean "either in your
1462 <code>CLASSPATH</code> environment variable or
1463 <code>ANT_HOME/lib</code>" for the rest of this
1464 answer.</p>
1465 <p>Technically the sentence above isn't true for Ant 1.6
1466 and later anymore, but the result is the same. For the sake
1467 of this discussion, <code>CLASSPATH</code> and
1468 <code>ANT_HOME/lib</code> are identical.</p>
1469 <p>This question collects a common type of problem: A task
1470 needs an external library and it has a nested classpath
1471 element so that you can point it to this external library, but
1472 that doesn't work unless you put the external library into the
1473 <code>CLASSPATH</code>.</p>
1474 <p>The root of the problem is that the class that needs the
1475 external library is on the <code>CLASSPATH</code>.</p>
1476 <p>When you specify a nested <code>&lt;classpath&gt;</code> in
1477 Ant, Ant creates a new class loader that uses the path you
1478 have specified. It then tries to load additional classes from
1479 this classloader.</p>
1480 <p>In most cases - for example the two cases above - Ant
1481 doesn't load the external library directly, it is the loaded
1482 class that does so.</p>
1483 <p>In the case of <code>&lt;junit&gt;</code> it is the task
1484 implementation itself and in the case of
1485 <code>&lt;style&gt;</code> it is the implementation of the
1486 <code>org.apache.tools.ant.taskdefs.XSLTLiaison</code>
1487 class.</p>
1488 <p>Ant's class loader implementation uses Java's
1489 delegation model, see <a href="http://java.sun.com/products/jdk/1.2/docs/api/java/lang/ClassLoader.html">http://java.sun.com/products/jdk/1.2/docs/api/java/lang/ClassLoader.html</a>
1490 the paragraph</p>
1491 <blockquote>The <code>ClassLoader</code> class uses a
1492 delegation model to search for classes and resources. Each
1493 instance of <code>ClassLoader</code> has an associated parent
1494 class loader. When called upon to find a class or resource, a
1495 <code>ClassLoader</code> instance will delegate the search for
1496 the class or resource to its parent class loader before
1497 attempting to find the class or resource itself. The virtual
1498 machine's built-in class loader, called the bootstrap
1499 class loader, does not itself have a parent but may serve as
1500 the parent of a <code>ClassLoader</code>
1501 instance.</blockquote>
1502 <p>This means, Ant's class loader will consult the
1503 bootstrap class loader first, which tries to load classes from
1504 <code>CLASSPATH</code>. The bootstrap class loader
1505 doesn't know anything about Ant's class loader or
1506 even the path you have specified.</p>
1507 <p>If the bootstrap class loader can load the class Ant has
1508 asked it to load, this class will try to load the external
1509 library from <code>CLASSPATH</code> as well - it doesn't
1510 know anything else - and will not find it unless the library
1511 is in <code>CLASSPATH</code> as well.</p>
1512 <p>To solve this, you have two major options:</p>
1513 <ol>
1514 <li>put all external libraries you need in
1515 <code>CLASSPATH</code> as well this is not what you want,
1516 otherwise you wouldn't have found this FAQ entry.</li>
1517
1518 <li>remove the class that loads the external library from
1519 the <code>CLASSPATH</code>.</li>
1520 </ol>
1521 <p><strong>Using The Second Option with Ant 1.5.4 and
1522 Earlier:</strong></p>
1523 <p>The easiest way to do this is to remove
1524 <code>optional.jar</code> from <code>ANT_HOME/lib</code>. If
1525 you do so, you will have to <code>&lt;taskdef&gt;</code> all
1526 optional tasks and use nested <code>&lt;classpath&gt;</code>
1527 elements in the <code>&lt;taskdef&gt;</code> tasks that point
1528 to the new location of <code>optional.jar</code>. Also,
1529 don't forget to add the new location of
1530 <code>optional.jar</code> to the
1531 <code>&lt;classpath&gt;</code> of your
1532 <code>&lt;style&gt;</code> or <code>&lt;junit&gt;</code>
1533 task.</p>
1534 <p>If you want to avoid to <code>&lt;taskdef&gt;</code> all
1535 optional tasks you need, the only other option is to remove
1536 the classes that should not be loaded via the bootstrap class
1537 loader from <code>optional.jar</code> and put them into a
1538 separate archive. Add this separate archive to the
1539 <code>&lt;classpath&gt;</code> of your
1540 <code>&lt;style&gt;</code> or <code>&lt;junit&gt;</code> task
1541 - and make sure the separate archive is not in
1542 <code>CLASSPATH</code>.</p>
1543 <p>In the case of <code>&lt;junit&gt;</code> you'd have
1544 to remove all classes that are in the
1545 <code>org/apache/tools/ant/taskdefs/optional/junit</code>
1546 directory, in the <code>&lt;style&gt;</code> case it is one of
1547 the <code>*Liaison</code> classes in
1548 <code>org/apache/tools/ant/taskdefs/optional</code>.</p>
1549 <p><strong>Using The Second Option with Ant 1.6 and
1550 later:</strong></p>
1551 <p>In Ant 1.6 <code>optional.jar</code> has been split into
1552 multiple jars, each one containing classes with the same
1553 dependencies on external libraries. You can move the
1554 "offending" jar out of ANT_HOME/lib. For the
1555 <code>&lt;junit&gt;</code> task it would be
1556 <code>ant-junit.jar</code> and for <code>&lt;style&gt;</code>
1557 it would be <code>ant-trax.jar</code>,
1558 <code>ant-xalan1.jar</code> or <code>ant-xslp.jar</code> -
1559 depending on the processor you use.</p>
1560 <p>If you use the option to break up <code>optional.jar</code>
1561 for <code>&lt;junit&gt;</code> or remove
1562 <code>ant-junit.jar</code>, you still have to use a
1563 <code>&lt;taskdef&gt;</code> with a nested
1564 <code>&lt;classpath&gt;</code> to define the junit task.</p>
1565 <p class="faq">
1566 <a name="winxp-jdk14-ant14"></a>
1567 When running Ant 1.4 on Windows XP and JDK 1.4, I get
1568 various errors when trying to <code>&lt;exec&gt;</code>, fork
1569 <code>&lt;java&gt;</code> or access environment
1570 variables.
1571 </p>
1572 <p>Ant &lt; 1.5 doesn't recognize Windows XP as a flavor
1573 of Windows that runs <code>CMD.EXE</code> instead of
1574 <code>COMMAND.COM</code>. JDK 1.3 will tell Ant that Windows
1575 XP is Windows 2000 so the problem doesn't show up
1576 there.</p>
1577 <p>Apart from upgrading to Ant 1.5 or better, setting the
1578 environment variable <code>ANT_OPTS</code> to
1579 <code>-Dos.name=Windows_NT</code> prior to invoking Ant has
1580 been confirmed as a workaround.</p>
1581 <p class="faq">
1582 <a name="1.5-cygwin-sh"></a>
1583 The <code>ant</code> wrapper script of Ant 1.5 fails
1584 for Cygwin if <code>ANT_HOME</code> is set to a Windows style
1585 path.
1586 </p>
1587 <p>This problem has been reported only hours after Ant 1.5 has
1588 been released, see <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=10664">Bug
1589 10664</a> and all its duplicates.</p>
1590 <p>A fixed version of the wrapper script can be found <a href="http://ant.apache.org/old-releases/v1.5/errata/">here</a>.
1591 Simply replace your script with this version.</p>
1592 <p class="faq">
1593 <a name="1.5.2-zip-broken"></a>
1594 <code>&lt;zip&gt;</code> is broken in Ant 1.5.2.
1595 </p>
1596 <p>Yes, it is.</p>
1597 <p>The problem reported by most people - see <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17648">Bug
1598 17648</a> and all its duplicates - is that Ant creates
1599 archives that a partially unreadable by WinZIP. Luckily
1600 <code>jar</code> deals with the archives and so the generated
1601 jars/wars/ears will most likely work for you anyway.</p>
1602 <p>There are additional problems, see bugs <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17780">Bug
1603 17780</a>, <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17871">Bug
1604 17871</a> and <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=18403">Bug
1605 18403</a>. All of them are supposed to be fixed with Ant
1606 1.5.3 (and only 18403 should exist in 1.5.3beta1).</p>
1607 <p class="faq">
1608 <a name="unknownelement.taskcontainer"></a>
1609
1610 Why do my custom task containers see Unknown Elements in Ant 1.6
1611 - they worked in Ant 1.5?
1612
1613 </p>
1614 <p>
1615 The objects added in TaskContainer.addTask(Task task)
1616 have changed from Tasks to UnknownElements.
1617 </p>
1618 <p>
1619 There was a number of valid reasons for this change. But the backward
1620 compatibility problems were not noticed until after Ant 1.6.0 was
1621 released.
1622 </p>
1623 <p>
1624 Your container class will need to be modified to check if the Task
1625 is an UnknownElement and call perform on it to
1626 convert it to a Task and to execute it.
1627 (see apache.tools.ant.taskdefs.Sequential)
1628 </p>
1629 <p>
1630 If you want to do more processing on the task,
1631 you need to use the techniques in apache.tools.ant.taskdefs.Antlib#execute()
1632 This does make use of one 1.6 method call (UE#getRealObject()),
1633 you need to use UE#getTask() instead - this will
1634 return null for non tasks (types like fileset id=x).
1635 </p>
1636 <p>
1637 So.. iterate over the tasks, if they are UEs, convert them to
1638 tasks, using UE#maybeConfigure and UE#getTask()
1639 </p>
1640 <pre class="code">
1641 for (Iterator i = tasks.iterator(); i.hasNext();) {
1642 Task t = (Task) i.next();
1643 if (t instanceof UnknownElement) {
1644 ((UnknownElement) t).maybeConfigure();
1645 t = ((UnknownElement) t).getTask();
1646 if (t == null) {
1647 continue;
1648 }
1649 }
1650 // .... original Custom code
1651 }
1652 </pre>
1653 <p>
1654 This approach should work for ant1.5 and ant1.6.
1655 </p>
1656 <p class="faq">
1657 <a name="java.exception.stacktrace"></a>
1658
1659 The program I run via &lt;java&gt; throws an exception but I
1660 can't seem to get the full stack trace.
1661
1662 </p>
1663 <p>This is a know bug that has been fixed after the release of
1664 Ant 1.6.1.</p>
1665 <p>As a workaround, run your &lt;java&gt; task with
1666 <code>fork="true"</code> and Ant will display the full
1667 trace.</p>
1668 <p class="faq">
1669 <a name="junit-no-runtime-xml"></a>
1670
1671 Using format="xml", &lt;junit&gt; fails with a
1672 <code>NoClassDefFoundError</code> if forked.
1673
1674 </p>
1675 <p>The XML formatter needs the <a href="http://www.w3.org/DOM/">DOM classes</a> to work. If you
1676 are using JDK 1.4 or later they are included with your Java
1677 Runtime and this problem won't occur. If you are running JDK
1678 1.3 or earlier, the DOM classes have to be on your
1679 &lt;junit&gt; task's &lt;classpath&gt;.</p>
1680 <p>Prior to Ant 1.6.0 Ant would include the DOM classes from
1681 the XML parser that is used by Ant itself if you set the
1682 includeAntRuntime attribute to true (the default). With Ant
1683 1.6.0 this has been changed as this behavior made it
1684 impossible to use a different XML parser in your tests.</p>
1685 <p>This means that you have to take care of the DOM classes
1686 explicitly starting with Ant 1.6.0. If you don't need to set
1687 up a different XML parser for your tests, the easiest solution
1688 is to add</p>
1689 <pre class="code">
1690&lt;pathelement path=&quot;${ant.home}/lib/xml-apis.jar:${ant.home}/lib/xercesImpl.jar&quot;/&gt;
1691</pre>
1692 <p>to your task's &lt;classpath&gt;.</p>
1693 <p class="faq">
1694 <a name="xalan-jdk1.5"></a>
1695
1696 <code>&lt;junitreport&gt;</code> doesn't work with JDK 1.5 but
1697 worked fine with JDK 1.4.
1698
1699 </p>
1700 <p>While JDK 1.4.x contains a version of Xalan-J 2, JDK 1.5
1701 (and later?) have <a href="http://java.sun.com/j2se/1.5.0/compatibility.html#4959783">moved
1702 to XSLTC</a>. Since this task uses Xalan's redirect
1703 extensions for its internal stylesheet, Ant doesn't support
1704 XSLTC yet. This means that you have to install <a href="http://xml.apache.org/xalan-j/">Xalan-J 2</a> in order
1705 to use this task with JDK 1.5.</p>
1706 <p>Starting with Ant 1.6.2 <code>&lt;junitreport&gt;</code>
1707 will support JDK 1.5.</p>
1708 </div>
1709 </div>
1710
1711 <p class="copyright">
1712 Copyright &copy; 2000-2004&nbsp;The Apache Software Foundation. All rights reserved.
1713 <script type="text/javascript" language="JavaScript"><!--
1714 document.write(" - "+"Last Published: " + document.lastModified);
1715 // -->
1716 </script>
1717 </p>
1718 </body>
1719 </html>
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
Note: See TracBrowser for help on using the repository browser.