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