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 99 KiB

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