source: release-kits/lirk3/resources/gs3-release-maker/ant/docs/faq.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

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