You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

faq.html 73 KiB

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