1 | <!--
|
---|
2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
---|
3 | contributor license agreements. See the NOTICE file distributed with
|
---|
4 | this work for additional information regarding copyright ownership.
|
---|
5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
---|
6 | (the "License"); you may not use this file except in compliance with
|
---|
7 | the License. You may obtain a copy of the License at
|
---|
8 |
|
---|
9 | http://www.apache.org/licenses/LICENSE-2.0
|
---|
10 |
|
---|
11 | Unless required by applicable law or agreed to in writing, software
|
---|
12 | distributed under the License is distributed on an "AS IS" BASIS,
|
---|
13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
14 | See the License for the specific language governing permissions and
|
---|
15 | limitations under the License.
|
---|
16 | -->
|
---|
17 | <html>
|
---|
18 |
|
---|
19 | <head>
|
---|
20 | <meta http-equiv="Content-Language" content="en-us">
|
---|
21 | <link rel="stylesheet" type="text/css" href="stylesheets/style.css">
|
---|
22 | <title>Installing Ant</title>
|
---|
23 | </head>
|
---|
24 |
|
---|
25 | <body>
|
---|
26 | <h1>Installing Ant</h1>
|
---|
27 | <h2><a name="getting">Getting Ant</a></h2>
|
---|
28 | <h3>Binary Edition</h3>
|
---|
29 | <p>The latest stable version of Ant is available from the Ant web page <a
|
---|
30 | href="http://ant.apache.org/">http://ant.apache.org/</a>.
|
---|
31 |
|
---|
32 | <h3>As a binary in an RPM Package</h3>
|
---|
33 |
|
---|
34 | <p>Consult the <a href="#jpackage">jpackage</a> section below.</p>
|
---|
35 |
|
---|
36 | <h3>Bundled in IDEs</h3>
|
---|
37 | <p>
|
---|
38 | All the main Java IDEs ship with Ant, products such as Eclipse, NetBeans
|
---|
39 | and IntelliJ IDEA. If you install Ant this way you usually get the most recent
|
---|
40 | release of Ant at the time the IDE was released. Some of the IDEs (Eclipse
|
---|
41 | and NetBeans in particular) ship with extra tasks that only work if
|
---|
42 | IDE-specific tools are on Ant's path. To use these on command-line versions
|
---|
43 | of Ant, the relevant JARs need to be added to the command-line Ant as
|
---|
44 | extra libraries/tasks. Note that if it is an IDE task or extension that is
|
---|
45 | not behaving, the Ant team is unable to field bug reports. Try the IDE mailing
|
---|
46 | lists first, who will cross-file bugs if appropriate.
|
---|
47 | </p>
|
---|
48 | <p>
|
---|
49 | IDE's can invariably be pointed at different Ant installations. This lets
|
---|
50 | developers upgrade to a new release of Ant, and eliminate inconsistencies
|
---|
51 | between command-line and IDE Ant.
|
---|
52 | </p>
|
---|
53 |
|
---|
54 | <h3>Bundled in Java applications</h3>
|
---|
55 |
|
---|
56 | <p>
|
---|
57 | Many Java applications, most particularly application servers, ship with
|
---|
58 | a version of Ant. These are primarily for internal use by the application,
|
---|
59 | using the Java APIs to delegate tasks such as JSP page compilation to the Ant
|
---|
60 | runtime. Such distributions are usually unsupported by everyone. Particularly
|
---|
61 | troublesome are those products that non only ship with their own Ant release,
|
---|
62 | they add their own version of ANT.BAT or ant.sh to the PATH. If Ant starts
|
---|
63 | behaving wierdly after installing something, try the
|
---|
64 | <a href="#diagnostics">diagnostics</a> advice.
|
---|
65 | </p>
|
---|
66 |
|
---|
67 | <h3>Source Edition</h3>
|
---|
68 |
|
---|
69 | <p>If you prefer the source edition, you can download the source for the latest
|
---|
70 | Ant release from
|
---|
71 | <a href="http://ant.apache.org/srcdownload.cgi">http://ant.apache.org/srcdownload.cgi</a>.
|
---|
72 |
|
---|
73 | If you prefer the leading-edge code, you can access
|
---|
74 | the code as it is being developed via SVN. The Ant website has details on
|
---|
75 | <a href="http://ant.apache.org/svn.html" target="_top">accessing SVN</a>.
|
---|
76 | All bug fixes will go in against the HEAD of the source tree, and the first
|
---|
77 | response to many bugreps will be "have you tried the latest version".
|
---|
78 | Don't be afraid to download and build a prererelease edition, as everything
|
---|
79 | other than new features are usually stable.
|
---|
80 | </p>
|
---|
81 | <p>
|
---|
82 |
|
---|
83 |
|
---|
84 | See the section <a href="#buildingant">Building Ant</a> on how to
|
---|
85 | build Ant from the source code.
|
---|
86 | You can also access the
|
---|
87 | <a href="http://svn.apache.org/viewcvs.cgi/ant/" target="_top">
|
---|
88 | Ant SVN repository</a> on-line. </p>
|
---|
89 |
|
---|
90 | <hr>
|
---|
91 | <h2><a name="sysrequirements">System Requirements</a></h2>
|
---|
92 | Ant has been used successfully on many platforms, including Linux,
|
---|
93 | commercial flavours of Unix such as Solaris and HP-UX,
|
---|
94 | Windows NT-platforms, OS/2 Warp, Novell Netware 6, OpenVMS and MacOS X.
|
---|
95 | The platforms used most for development are, in no particular order,
|
---|
96 | Linux, MacOS X, Windows XP and Unix; these are therefore that platforms
|
---|
97 | that tend to work best. As of Ant1.7, Windows 9x is no longer supported.
|
---|
98 | <p>
|
---|
99 | To build and use Ant, you must have a JAXP-compliant XML parser installed and
|
---|
100 | available on your classpath, such as Xerces.</p>
|
---|
101 | <p>
|
---|
102 | The binary distribution of Ant includes the latest version of the
|
---|
103 | <a href="http://xml.apache.org/xerces2-j/index.html">Apache Xerces2</a> XML parser.
|
---|
104 | Please see
|
---|
105 | <a href="http://java.sun.com/xml/" target="_top">http://java.sun.com/xml/</a>
|
---|
106 | for more information about JAXP.
|
---|
107 | If you wish to use a different JAXP-compliant parser, you should remove
|
---|
108 | <code>xercesImpl.jar</code> and <code>xml-apis.jar</code>
|
---|
109 | from Ant's <code>lib</code> directory.
|
---|
110 | <p>
|
---|
111 | You can then either put the JARs of your preferred parser into Ant's
|
---|
112 | <code>lib</code> directory or put the jars on the system classpath.
|
---|
113 | Some parts of Ant will fail if you use an old parser, especially one
|
---|
114 | that is not namespace-aware. In particular, avoid the Crimson parser.</p>
|
---|
115 |
|
---|
116 | <p>Tip: "ant -diagnostics" will list the XML parser used and its location.</p>
|
---|
117 |
|
---|
118 | <p>
|
---|
119 | For the current version of Ant, you will also need a JDK installed on
|
---|
120 | your system, version 1.2 or later required, 1.5 or later strongly recommended.
|
---|
121 | The later the version of Java , the more Ant tasks you get.
|
---|
122 | </p>
|
---|
123 | <p>
|
---|
124 | <strong>Note #2: </strong>If a JDK is not present, only the JRE runtime, then many tasks will not work.
|
---|
125 | </p>
|
---|
126 |
|
---|
127 | <h3>Open Source Java Runtimes</h3>
|
---|
128 | <p>
|
---|
129 | The Ant team strongly supports users running Ant on Kaffe and other
|
---|
130 | open source Java runtimes, and so strives to have a product that works
|
---|
131 | well on those platforms. What appears to work well is Kaffe with
|
---|
132 | Gnu Classpath and the Xerces and Xalan libraries.
|
---|
133 | </p>
|
---|
134 |
|
---|
135 | <hr>
|
---|
136 | <h2><a name="installing">Installing Ant</a></h2>
|
---|
137 | <p>The binary distribution of Ant consists of the following directory layout:
|
---|
138 | <pre>
|
---|
139 | ant
|
---|
140 | +--- README, LICENSE, fetch.xml, other text files. //basic information
|
---|
141 | +--- bin // contains launcher scripts
|
---|
142 | |
|
---|
143 | +--- lib // contains Ant jars plus necessary dependencies
|
---|
144 | |
|
---|
145 | +--- docs // contains documentation
|
---|
146 | | |
|
---|
147 | | +--- images // various logos for html documentation
|
---|
148 | | |
|
---|
149 | | +--- manual // Ant documentation (a must read ;-)
|
---|
150 | |
|
---|
151 | +--- etc // contains xsl goodies to:
|
---|
152 | // - create an enhanced report from xml output of various tasks.
|
---|
153 | // - migrate your build files and get rid of 'deprecated' warning
|
---|
154 | // - ... and more ;-)
|
---|
155 | </pre>
|
---|
156 |
|
---|
157 | Only the <code>bin</code> and <code>lib</code> directories are
|
---|
158 | required to run Ant.
|
---|
159 |
|
---|
160 | To install Ant, choose a directory and copy the distribution
|
---|
161 | files there. This directory will be known as ANT_HOME.
|
---|
162 | </p>
|
---|
163 |
|
---|
164 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
165 | <tr>
|
---|
166 | <td colspan="2">
|
---|
167 | <b>Windows 95, Windows 98 & Windows ME Note:</b>
|
---|
168 | </td>
|
---|
169 | </tr>
|
---|
170 | <tr>
|
---|
171 | <td width="5%"> </td>
|
---|
172 | <td><i>
|
---|
173 | On these systems, the script used to launch Ant will have
|
---|
174 | problems if ANT_HOME is a long filename (i.e. a filename which is not
|
---|
175 | of the format known as "8.3"). This is due to
|
---|
176 | limitations in the OS's handling of the <code>"for"</code>
|
---|
177 | batch-file statement. It is recommended, therefore, that Ant be
|
---|
178 | installed in a <b>short</b>, 8.3 path, such as C:\Ant. </i>
|
---|
179 | </td>
|
---|
180 | </tr>
|
---|
181 | <tr>
|
---|
182 | <td width="5%"> </td>
|
---|
183 | <td>
|
---|
184 | <p>On these systems you will also need to configure more environment
|
---|
185 | space to cater for the environment variables used in the Ant lauch script.
|
---|
186 | To do this, you will need to add or update the following line in
|
---|
187 | the <code>config.sys</code> file
|
---|
188 | </p>
|
---|
189 | <p><code>shell=c:\command.com c:\ /p /e:32768</code></p>
|
---|
190 | </td>
|
---|
191 | </tr>
|
---|
192 | </table>
|
---|
193 |
|
---|
194 | <h3>Setup</h3>
|
---|
195 | <p>
|
---|
196 | Before you can run Ant there is some additional set up you
|
---|
197 | will need to do unless you are installing the <a href="#jpackage">RPM
|
---|
198 | version from jpackage.org</a>:</p>
|
---|
199 | <ul>
|
---|
200 | <li>Add the <code>bin</code> directory to your path.</li>
|
---|
201 | <li>Set the <code>ANT_HOME</code> environment variable to the
|
---|
202 | directory where you installed Ant. On some operating systems, Ant's
|
---|
203 | startup scripts can guess <code>ANT_HOME</code> (Unix dialects and
|
---|
204 | Windows NT/2000), but it is better to not rely on this behavior.</li>
|
---|
205 | <li>Optionally, set the <code>JAVA_HOME</code> environment variable
|
---|
206 | (see the <a href="#advanced">Advanced</a> section below).
|
---|
207 | This should be set to the directory where your JDK is installed.</li>
|
---|
208 | </ul>
|
---|
209 | <p><strong>Note:</strong> Do not install Ant's ant.jar file into the lib/ext
|
---|
210 | directory of the JDK/JRE. Ant is an application, whilst the extension
|
---|
211 | directory is intended for JDK extensions. In particular there are security
|
---|
212 | restrictions on the classes which may be loaded by an extension.</p>
|
---|
213 |
|
---|
214 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
215 | <tr>
|
---|
216 | <td colspan="2">
|
---|
217 | <b>Windows Note:</b>
|
---|
218 | </td>
|
---|
219 | </tr>
|
---|
220 | <tr>
|
---|
221 | <td width="5%"> </td>
|
---|
222 | <td>
|
---|
223 | The ant.bat script makes use of three environment variables -
|
---|
224 | ANT_HOME, CLASSPATH and JAVA_HOME. <b>Ensure</b> that if
|
---|
225 | these variables are set, they do <b><u>not</u></b> have quotes (either
|
---|
226 | ' or ") and they do <b><u>not</u></b> end with \ or with /.
|
---|
227 | </td>
|
---|
228 | </tr>
|
---|
229 | </table>
|
---|
230 |
|
---|
231 | <h3><a name="optionalTasks">Optional Tasks</a></h3>
|
---|
232 | <p>Ant supports a number of optional tasks. An optional task is a task which
|
---|
233 | typically requires an external library to function. The optional tasks are
|
---|
234 | packaged together with the core Ant tasks.</p>
|
---|
235 |
|
---|
236 | <p>The external libraries required by each of the optional tasks is detailed
|
---|
237 | in the <a href="#librarydependencies">Library Dependencies</a> section. These external
|
---|
238 | libraries must be added to Ant's classpath, in any of the following ways
|
---|
239 | </p>
|
---|
240 | <ul>
|
---|
241 | <li>In ANT_HOME/lib. This makes the JAR files available to all
|
---|
242 | Ant users and builds</li>
|
---|
243 |
|
---|
244 | <li>
|
---|
245 | In ${user.home}/.ant/lib . This is a new feature since Ant1.6,
|
---|
246 | and allows different users to add new libraries to Ant. All JAR files
|
---|
247 | added to this directory are available to command-line Ant.
|
---|
248 | </li>
|
---|
249 |
|
---|
250 | <li>
|
---|
251 | On the command line with a <code>-lib</code> parameter. This lets
|
---|
252 | you add new JAR files on a case-by-case basis.
|
---|
253 | </li>
|
---|
254 |
|
---|
255 | <li>In the CLASSPATH environment variable. Avoid this; it makes
|
---|
256 | the JAR files visible to <i>all</i> Java applications, and causes
|
---|
257 | no end of support calls.
|
---|
258 | </li>
|
---|
259 | </ul>
|
---|
260 |
|
---|
261 | <p>
|
---|
262 | IDEs have different ways of adding external JAR files and third-party tasks
|
---|
263 | to Ant. Usually it is done by some configuration dialog. Sometimes JAR files
|
---|
264 | added to a project are automatically added to ant's classpath.
|
---|
265 | </p>
|
---|
266 |
|
---|
267 | <h3><a name="classpath">The CLASSPATH environment variable</a></h3>
|
---|
268 | <p>
|
---|
269 |
|
---|
270 | The CLASSPATH environment variable is a source of many Ant support queries. As
|
---|
271 | the round trip time for diagnosis on the Ant user mailing list can be slow, and
|
---|
272 | because filing bug reports complaining about 'ant.bat' not working will be
|
---|
273 | rejected by the developers as WORKSFORME "this is a configuration problem, not a
|
---|
274 | bug", you can save yourself a lot of time and frustration by following some
|
---|
275 | simple steps.
|
---|
276 |
|
---|
277 | </p>
|
---|
278 | <ol>
|
---|
279 |
|
---|
280 | <li>Do not ever set CLASSPATH. Ant does not need it, it only causes confusion
|
---|
281 | and breaks things.
|
---|
282 |
|
---|
283 | </li>
|
---|
284 |
|
---|
285 | <li>If you ignore the previous rule, do not ever, ever, put quotes in the
|
---|
286 | CLASSPATH, even if there is a space in a directory. This will break Ant, and it
|
---|
287 | is not needed. </li>
|
---|
288 |
|
---|
289 | <li>If you ignore the first rule, do not ever, ever, have a trailing backslash
|
---|
290 | in a CLASSPATH, as it breaks Ant's ability to quote the string. Again, this is
|
---|
291 | not needed for the correct operation of the CLASSPATH environment variable, even
|
---|
292 | if a DOS directory is to be added to the path. </li>
|
---|
293 |
|
---|
294 | <li>You can stop Ant using the CLASSPATH environment variable by setting the
|
---|
295 | <code>-noclasspath</code> option on the command line. This is an easy way
|
---|
296 | to test for classpath-related problems.</li>
|
---|
297 |
|
---|
298 | </ol>
|
---|
299 |
|
---|
300 | <p>
|
---|
301 |
|
---|
302 | The usual symptom of CLASSPATH problems is that ant will not run with some error
|
---|
303 | about not being able to find <code>org.apache.tools.Ant.main</code>, or, if you have got the
|
---|
304 | quotes/backslashes wrong, some very weird Java startup error. To see if this is
|
---|
305 | the case, run <code>ant -noclasspath</code> or unset the CLASSPATH environment
|
---|
306 | variable.
|
---|
307 |
|
---|
308 | </p>
|
---|
309 |
|
---|
310 |
|
---|
311 | <h3><a name="proxy">Proxy Configuration</a></h3>
|
---|
312 |
|
---|
313 | <p> Many Ant built-in and third-party tasks use network connections to retrieve
|
---|
314 | files from HTTP servers. If you are behind a firewall with a proxy server, then
|
---|
315 | Ant needs to be configured with the proxy. Here are the different ways to do
|
---|
316 | this. </p>
|
---|
317 |
|
---|
318 | <ul>
|
---|
319 |
|
---|
320 | <li><b>With Java1.5</b><br>.
|
---|
321 |
|
---|
322 | When you run Ant on Java1.5, it tries to use the automatic proxy setup
|
---|
323 | mechanism. If this works -and it is a big if, as we see little evidence of it
|
---|
324 | doing so on Linux or WinXP-, then your proxy is set up without you doing
|
---|
325 | anything. You can disable this feature with the <code>-noproxy</code> option.
|
---|
326 |
|
---|
327 | </li>
|
---|
328 |
|
---|
329 | <li><b>With explicit JVM properties.</b><br>.
|
---|
330 |
|
---|
331 | These are documented <a
|
---|
332 | href="http://java.sun.com/j2se/1.5.0/docs/guide/net/properties.html">by Sun</a>,
|
---|
333 | and control the proxy behaviour of the entire JVM. To set them in Ant, declare
|
---|
334 | them in the <code>ANT_OPTS</code> environment variable. This is the best option
|
---|
335 | for a non-mobile system. For a laptop, you have to change these settings as you
|
---|
336 | roam.
|
---|
337 |
|
---|
338 | </li>
|
---|
339 |
|
---|
340 | <li><b>In the build file itself</b><br>
|
---|
341 |
|
---|
342 | If you are writing an build file that is always to be used behind the firewall,
|
---|
343 | the <setproxy> task lets you configure the proxy (which it does by setting
|
---|
344 | the JVM properties). If you do this, we strongly recommend using ant properties
|
---|
345 | to define the proxy host, port, etc, so that individuals can override the
|
---|
346 | defaults.</li>
|
---|
347 |
|
---|
348 | </ul>
|
---|
349 |
|
---|
350 | <p> The Ant team acknowledges that this is unsatisfactory. Until the JVM
|
---|
351 | automatic proxy setup works properly everywhere, explicit JVM options via
|
---|
352 | ANT_ARGS are probably the best solution. Setting properties on Ant's
|
---|
353 | command line do not work, because those are <i>Ant properties</i> being set, not
|
---|
354 | JVM options. This means the following does not set up the command line:
|
---|
355 |
|
---|
356 | </p>
|
---|
357 |
|
---|
358 | <pre>ant -Dhttp.proxyHost=proxy -Dhttp.proxyPort=81</pre>
|
---|
359 |
|
---|
360 | <p> All it does is set up two Ant properties.</p>
|
---|
361 |
|
---|
362 | <p>One other troublespot with
|
---|
363 | proxies is with authenticating proxies. Ant cannot go beyond what the JVM does
|
---|
364 | here, and as it is very hard to remotely diagnose, test and fix proxy-related
|
---|
365 | problems, users who work behind a secure proxy will have to spend much time
|
---|
366 | configuring the JVM properties until they are happy. </p>
|
---|
367 |
|
---|
368 |
|
---|
369 | <h3><a name="windows">Windows and OS/2</a></h3>
|
---|
370 | <p>Assume Ant is installed in <code>c:\ant\</code>. The following sets up the
|
---|
371 | environment:</p>
|
---|
372 | <pre>set ANT_HOME=c:\ant
|
---|
373 | set JAVA_HOME=c:\jdk-1.5.0.05
|
---|
374 | set PATH=%PATH%;%ANT_HOME%\bin</pre>
|
---|
375 |
|
---|
376 | <h3>Linux/Unix (bash)</h3>
|
---|
377 | <p>Assume Ant is installed in <code>/usr/local/ant</code>. The following sets up
|
---|
378 | the environment:</p>
|
---|
379 | <pre>export ANT_HOME=/usr/local/ant
|
---|
380 | export JAVA_HOME=/usr/local/jdk-1.5.0.05
|
---|
381 | export PATH=${PATH}:${ANT_HOME}/bin</pre>
|
---|
382 |
|
---|
383 | <h3>Linux/Unix (csh)</h3>
|
---|
384 | <pre>setenv ANT_HOME /usr/local/ant
|
---|
385 | setenv JAVA_HOME /usr/local/jdk/jdk-1.5.0.05
|
---|
386 | set path=( $path $ANT_HOME/bin )</pre>
|
---|
387 |
|
---|
388 | <p>
|
---|
389 | Having a symbolic link set up to point to the JVM/JSK version makes updates more seamless. </p>
|
---|
390 | <a name="jpackage"></a>
|
---|
391 | <h3>RPM version from jpackage.org</h3>
|
---|
392 | <p>
|
---|
393 | The <a href="http://www.jpackage.org">JPackage project</a> distributes an RPM version of Ant.
|
---|
394 | With this version, it is not necessary to set <code> JAVA_HOME </code>or
|
---|
395 | <code> ANT_HOME </code>environment variables and the RPM installer will correctly
|
---|
396 | place the Ant executable on your path.
|
---|
397 | </p>
|
---|
398 | <p>
|
---|
399 | <b>NOTE:</b> <em>Since Ant 1.7.0</em>, if the <code>ANT_HOME</code>
|
---|
400 | environment variable is set, the jpackage distribution will be
|
---|
401 | ignored.
|
---|
402 | </p>
|
---|
403 | <p>
|
---|
404 | Optional jars for the JPackage version are handled in two ways. The easiest, and
|
---|
405 | best way is to get these external libraries from JPackage if JPackage has them
|
---|
406 | available. (Note: for each such library, you will have to get both the external
|
---|
407 | package itself (e.g. <code>oro-2.0.8-2jpp.noarch.rpm</code>) and the small library that links
|
---|
408 | ant and the external package (e.g. <code>ant-apache-oro-1.6.2-3jpp.noarch.rpm</code>).
|
---|
409 | </p><p>
|
---|
410 | However, JPackage does not package proprietary software, and since some of the
|
---|
411 | optional packages depend on proprietary jars, they must be handled as follows.
|
---|
412 | This may violate the spirit of JPackage, but it is necessary if you need these proprietary packages.
|
---|
413 | For example, suppose you want to install support for starteam, which jpackage does not
|
---|
414 | support:
|
---|
415 | <ol>
|
---|
416 | <li>Decide where you want to deploy the extra jars. One option is in <code>$ANT_HOME/lib</code>,
|
---|
417 | which, for JPackage is usually <code>/usr/share/ant/lib</code>. Another, less messy option
|
---|
418 | is to create an <code>.ant/lib</code> subdirectory of your home directory and place your
|
---|
419 | non-jpackage ant jars there, thereby avoiding mixing jpackage
|
---|
420 | libraries with non-jpacakge stuff in the same folder.
|
---|
421 | More information on where Ant finds its libraries is available
|
---|
422 | <a href="http://ant.apache.org/manual/running.html#libs">here</a></li>
|
---|
423 | <li>Download a non-jpackage binary distribution from the regular
|
---|
424 | <a href="http://ant.apache.org/bindownload.cgi">Apache Ant site</a></li>
|
---|
425 | <li>Unzip or untar the distribution into a temporary directory</li>
|
---|
426 | <li>Copy the linking jar, in this case <code>ant-starteam.jar</code>, into the library directory you
|
---|
427 | chose in step 1 above.</li>
|
---|
428 | <li>Copy the proprietary jar itself into the same directory.</li>
|
---|
429 | </ol>
|
---|
430 | Finally, if for some reason you are running on a system with both the JPackage and Apache versions of Ant
|
---|
431 | available, if you should want to run the Apache version (which will have to be specified with an absolute file name,
|
---|
432 | not found on the path), you should use Ant's <code>--noconfig</code> command-line switch to avoid JPackage's classpath mechanism.
|
---|
433 |
|
---|
434 |
|
---|
435 | <h3><a name="advanced">Advanced</a></h3>
|
---|
436 |
|
---|
437 | <p>There are lots of variants that can be used to run Ant. What you need is at
|
---|
438 | least the following:</p>
|
---|
439 | <ul>
|
---|
440 | <li>The classpath for Ant must contain <code>ant.jar</code> and any jars/classes
|
---|
441 | needed for your chosen JAXP-compliant XML parser.</li>
|
---|
442 | <li>When you need JDK functionality
|
---|
443 | (such as for the <a href="CoreTasks/javac.html">javac</a> task or the
|
---|
444 | <a href="CoreTasks/rmic.html">rmic</a> task), then <code>tools.jar</code>
|
---|
445 | must be added. The scripts supplied with Ant,
|
---|
446 | in the <code>bin</code> directory, will add
|
---|
447 | the required JDK classes automatically, if the <code>JAVA_HOME</code>
|
---|
448 | environment variable is set.</li>
|
---|
449 |
|
---|
450 | <li>When you are executing platform-specific applications, such as the
|
---|
451 | <a href="CoreTasks/exec.html">exec</a> task or the
|
---|
452 | <a href="CoreTasks/cvs.html">cvs</a> task, the property <code>ant.home</code>
|
---|
453 | must be set to the directory containing where you installed Ant. Again
|
---|
454 | this is set by the Ant scripts to the value of the ANT_HOME environment
|
---|
455 | variable.</li>
|
---|
456 | </ul>
|
---|
457 | The supplied ant shell scripts all support an <tt>ANT_OPTS</tt>
|
---|
458 | environment variable which can be used to supply extra options
|
---|
459 | to ant. Some of the scripts also read in an extra script stored
|
---|
460 | in the users home directory, which can be used to set such options. Look
|
---|
461 | at the source for your platform's invocation script for details.
|
---|
462 |
|
---|
463 | <hr>
|
---|
464 | <h2><a name="buildingant">Building Ant</a></h2>
|
---|
465 | <p>To build Ant from source, you can either install the Ant source distribution
|
---|
466 | or checkout the ant module from SVN.</p>
|
---|
467 | <p>Once you have installed the source, change into the installation
|
---|
468 | directory.</p>
|
---|
469 |
|
---|
470 | <p>Set the <code>JAVA_HOME</code> environment variable
|
---|
471 | to the directory where the JDK is installed.
|
---|
472 | See <a href="#installing">Installing Ant</a>
|
---|
473 | for examples on how to do this for your operating system. </p>
|
---|
474 |
|
---|
475 | <p><b>Note</b>: The bootstrap process of Ant requires a greedy
|
---|
476 | compiler like Sun's javac or jikes. It does not work with gcj or
|
---|
477 | kjc.</p>
|
---|
478 |
|
---|
479 | <p>Make sure you have downloaded any auxiliary jars required to
|
---|
480 | build tasks you are interested in. These should be
|
---|
481 | added to the <code>lib/optional</code>
|
---|
482 | directory of the source tree.
|
---|
483 | See <a href="#librarydependencies">Library Dependencies</a>
|
---|
484 | for a list of JAR requirements for various features.
|
---|
485 | Note that this will make the auxiliary JAR
|
---|
486 | available for the building of Ant only. For running Ant you will
|
---|
487 | still need to
|
---|
488 | make the JARs available as described under
|
---|
489 | <a href="#installing">Installing Ant</a>.</p>
|
---|
490 |
|
---|
491 | <p>Your are now ready to build Ant:</p>
|
---|
492 | <blockquote>
|
---|
493 | <p><code>build -Ddist.dir=<<i>directory_to_contain_Ant_distribution</i>> dist</code> (<i>Windows</i>)</p>
|
---|
494 | <p><code>sh build.sh -Ddist.dir=<<i>directory_to_contain_Ant_distribution</i>> dist</code> (<i>Unix</i>)</p>
|
---|
495 | </blockquote>
|
---|
496 |
|
---|
497 | <p>This will create a binary distribution of Ant in the directory you specified.</p>
|
---|
498 |
|
---|
499 | <p>The above action does the following:</p>
|
---|
500 | <ul>
|
---|
501 |
|
---|
502 | <li>If necessary it will bootstrap the Ant code. Bootstrapping involves the manual
|
---|
503 | compilation of enough Ant code to be able to run Ant. The bootstrapped Ant is
|
---|
504 | used for the remainder of the build steps. </li>
|
---|
505 |
|
---|
506 | <li>Invokes the bootstrapped Ant with the parameters passed to the build script. In
|
---|
507 | this case, these parameters define an Ant property value and specify the "dist" target
|
---|
508 | in Ant's own <code>build.xml</code> file.</li>
|
---|
509 |
|
---|
510 | <li>Create the ant.jar and ant-launcher.jar JAR files</li>
|
---|
511 |
|
---|
512 | <li>Create optional JARs for which the build had the relevant libraries. If
|
---|
513 | a particular library is missing from ANT_HOME/lib/optional, then the matching
|
---|
514 | ant- JAR file will not be created. For example, ant-junit.jar is only built
|
---|
515 | if there is a junit.jar in the optional directory.</li>
|
---|
516 | </ul>
|
---|
517 |
|
---|
518 | <p>On most occasions you will not need to explicitly bootstrap Ant since the build
|
---|
519 | scripts do that for you. If however, the build file you are using makes use of features
|
---|
520 | not yet compiled into the bootstrapped Ant, you will need to manually bootstrap.
|
---|
521 | Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX)
|
---|
522 | to build a new bootstrap version of Ant.</p>
|
---|
523 |
|
---|
524 | If you wish to install the build into the current <code>ANT_HOME</code>
|
---|
525 | directory, you can use:
|
---|
526 | <blockquote>
|
---|
527 | <p><code>build install</code> (<i>Windows</i>)</p>
|
---|
528 | <p><code>sh build.sh install</code> (<i>Unix</i>)</p>
|
---|
529 | </blockquote>
|
---|
530 |
|
---|
531 | You can avoid the lengthy Javadoc step, if desired, with:
|
---|
532 | <blockquote>
|
---|
533 | <p><code>build install-lite</code> (<i>Windows</i>)</p>
|
---|
534 | <p><code>sh build.sh install-lite</code> (<i>Unix</i>)</p>
|
---|
535 | </blockquote>
|
---|
536 | This will only install the <code>bin</code> and <code>lib</code> directories.
|
---|
537 | <p>Both the <code>install</code> and
|
---|
538 | <code>install-lite</code> targets will overwrite
|
---|
539 | the current Ant version in <code>ANT_HOME</code>.</p>
|
---|
540 |
|
---|
541 | <hr>
|
---|
542 | <h2><a name="librarydependencies">Library Dependencies</a></h2>
|
---|
543 | <p>The following libraries are needed in Ant's classpath
|
---|
544 | if you are using the
|
---|
545 | indicated feature. Note that only one of the regexp libraries is
|
---|
546 | needed for use with the mappers
|
---|
547 | (and Java 1.4 and higher includes a regexp implementation which
|
---|
548 | Ant will find automatically).
|
---|
549 | You will also need to install the particular
|
---|
550 | Ant optional jar containing the task definitions to make these
|
---|
551 | tasks available. Please refer to the <a href="#optionalTasks">
|
---|
552 | Installing Ant / Optional Tasks</a> section above.</p>
|
---|
553 |
|
---|
554 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
555 | <tr>
|
---|
556 | <td><b>Jar Name</b></td>
|
---|
557 | <td><b>Needed For</b></td>
|
---|
558 | <td><b>Available At</b></td>
|
---|
559 | </tr>
|
---|
560 | <tr>
|
---|
561 | <td>An XSL transformer like Xalan</td>
|
---|
562 | <td>style task</td>
|
---|
563 | <td>
|
---|
564 | <b>If you use JDK 1.4+, an XSL transformer is already included, so you need not do anything special.</b><br>
|
---|
565 | <ul><li>XALAN : <a href="http://xml.apache.org/xalan-j/index.html"
|
---|
566 | target="_top">http://xml.apache.org/xalan-j/index.html</a></li>
|
---|
567 | </ul>
|
---|
568 | </td>
|
---|
569 | </tr>
|
---|
570 | <tr>
|
---|
571 | <td>jakarta-regexp-1.3.jar</td>
|
---|
572 | <td>regexp type with mappers</td>
|
---|
573 | <td><a href="http://jakarta.apache.org/regexp/" target="_top">http://jakarta.apache.org/regexp/</a></td>
|
---|
574 | </tr>
|
---|
575 | <tr>
|
---|
576 | <td>jakarta-oro-2.0.8.jar</td>
|
---|
577 | <td>regexp type with mappers and the perforce tasks<br>
|
---|
578 | To use the FTP task,
|
---|
579 | you need jakarta-oro 2.0.8 or later, and <a href="#commons-net">commons-net</a></td>
|
---|
580 | <td><a href="http://jakarta.apache.org/oro/" target="_top">http://jakarta.apache.org/oro/</a></td>
|
---|
581 | </tr>
|
---|
582 | <tr>
|
---|
583 | <td>junit.jar</td>
|
---|
584 | <td><code><junit></code> task. May be in classpath passed to task rather than Ant's classpath.</td>
|
---|
585 | <td><a href="http://www.junit.org/" target="_top">http://www.junit.org/</a></td>
|
---|
586 | </tr>
|
---|
587 | <tr>
|
---|
588 | <td>xalan.jar</td>
|
---|
589 | <td>junitreport task</td>
|
---|
590 | <td><a href="http://xml.apache.org/xalan-j/" target="_top">http://xml.apache.org/xalan-j/</a></td>
|
---|
591 | </tr>
|
---|
592 | <tr>
|
---|
593 | <td>stylebook.jar</td>
|
---|
594 | <td>stylebook task</td>
|
---|
595 | <td>CVS repository of <a href="http://xml.apache.org/cvs.html" target="_top">http://xml.apache.org/cvs.html</a></td>
|
---|
596 | </tr>
|
---|
597 | <tr>
|
---|
598 | <td>antlr.jar</td>
|
---|
599 | <td>antlr task</td>
|
---|
600 | <td><a href="http://www.antlr.org/" target="_top">http://www.antlr.org/</a></td>
|
---|
601 | </tr>
|
---|
602 | <tr>
|
---|
603 | <td>bsf.jar</td>
|
---|
604 | <td>script task
|
---|
605 | <p>
|
---|
606 | <strong>Note</strong>: Ant 1.6 and later require Apache BSF, not
|
---|
607 | the IBM version. I.e. you need BSF 2.3.0-rc1 or later.
|
---|
608 | </p>
|
---|
609 | <p>
|
---|
610 | <strong>Note</strong>: BSF 2.4.0 is needed to use a post 1.5R3 version
|
---|
611 | of rhino's javascript.
|
---|
612 | </p>
|
---|
613 | <p>
|
---|
614 | <strong>Note</strong>: BSF 2.4.0 uses jakarata-commons-logging
|
---|
615 | so it needs the commons-logging.jar.
|
---|
616 | </p>
|
---|
617 | </td>
|
---|
618 | <td><a href="http://jakarta.apache.org/bsf/" target="_top">http://jakarta.apache.org/bsf/</a></td>
|
---|
619 | </tr>
|
---|
620 | <tr>
|
---|
621 | <td>Groovy jars</td>
|
---|
622 | <td>Groovy with script and scriptdef tasks<br>
|
---|
623 | You need to get the groovy jar and two asm jars from a groovy
|
---|
624 | installation. The jars are groovy-[version].jar, asm-[vesion].jar and
|
---|
625 | asm-util-[version].jar and antlr-[version].jar.
|
---|
626 | As of groovy version 1.0-JSR-06, the jars are
|
---|
627 | groovy-1.0-JSR-06.jar, antlr-2.7.5.jar, asm-2.2.jar and asm-util-2.2.jar.
|
---|
628 | Alternatively one may use the embedded groovy jar file.
|
---|
629 | This is located in the embedded directory of the groovy distribution.
|
---|
630 | This bundles all the needed jar files into one jar file.
|
---|
631 | It is called groovy-all-[version].jar.
|
---|
632 | </td>
|
---|
633 | <td>
|
---|
634 | <a href="http://groovy.codehaus.org/">http://groovy.codehaus.org/</a>
|
---|
635 | <br>
|
---|
636 | The asm jars are also available from the creators of asm -
|
---|
637 | <a href="http://asm.objectweb.org/">http://asm.objectweb.org/</a>
|
---|
638 | </td>
|
---|
639 | </tr>
|
---|
640 | <tr>
|
---|
641 | <td>netrexx.jar</td>
|
---|
642 | <td>netrexx task, Rexx with the script task</td>
|
---|
643 | <td><a href="http://www.ibm.com/software/awdtools/netrexx/download.html" target="_top">
|
---|
644 | http://www.ibm.com/software/awdtools/netrexx/download.html</a></td>
|
---|
645 | </tr>
|
---|
646 | <tr>
|
---|
647 | <td>js.jar</td>
|
---|
648 | <td>Javascript with script task<br>
|
---|
649 | If you use Apache BSF 2.3.0-rc1, you must use rhino 1.5R3 (later
|
---|
650 | versions of BSF (e.g. version 2.4.0) work with 1.5R4 and higher).</td>
|
---|
651 | <td><a href="http://www.mozilla.org/rhino/" target="_top">http://www.mozilla.org/rhino/</a></td>
|
---|
652 | </tr>
|
---|
653 | <tr>
|
---|
654 | <td>jython.jar</td>
|
---|
655 | <td>Python with script task<br>
|
---|
656 | Warning : jython.jar also contains classes from jakarta-oro.
|
---|
657 | Remove these classes if you are also using jakarta-oro.</td>
|
---|
658 | <td><a href="http://jython.sourceforge.net/" target="_top">http://jython.sourceforge.net/</a></td>
|
---|
659 | </tr>
|
---|
660 | <tr>
|
---|
661 | <td>jpython.jar</td>
|
---|
662 | <td>Python with script task <b>deprecated, jython is the prefered engine</b></td>
|
---|
663 | <td><a href="http://www.jpython.org/" target="_top">http://www.jpython.org/</a></td>
|
---|
664 | </tr>
|
---|
665 | <tr>
|
---|
666 | <td>jacl.jar and tcljava.jar</td>
|
---|
667 | <td>TCL with script task</td>
|
---|
668 | <td><a href="http://www.scriptics.com/software/java/" target="_top">http://www.scriptics.com/software/java/</a></td>
|
---|
669 | </tr>
|
---|
670 | <tr>
|
---|
671 | <td>BeanShell JAR(s)</td>
|
---|
672 | <td>BeanShell with script task.
|
---|
673 | <br>
|
---|
674 | <strong>Note</strong>: Ant requires BeanShell version 1.3 or
|
---|
675 | later</td>
|
---|
676 | <td><a href="http://www.beanshell.org/" target="_top">http://www.beanshell.org/</a></td>
|
---|
677 | </tr>
|
---|
678 | <tr>
|
---|
679 | <td>jruby.jar</td>
|
---|
680 | <td>Ruby with script task</td>
|
---|
681 | <td><a href="http://jruby.sourceforge.net/" target="_top">http://jruby.sourceforge.net/</a></td>
|
---|
682 | </tr>
|
---|
683 | <tr>
|
---|
684 | <td>judo.jar</td>
|
---|
685 | <td>Judoscript with script task</td>
|
---|
686 | <td><a href="http://www.judoscript.com/index.html" target="_top">http://www.judoscript.com/index.html</a></td>
|
---|
687 | </tr>
|
---|
688 | <tr>
|
---|
689 | <td>commons-logging.jar</td>
|
---|
690 | <td>CommonsLoggingListener</td>
|
---|
691 | <td><a href="http://jakarta.apache.org/commons/logging/index.html"
|
---|
692 | target="_top">http://jakarta.apache.org/commons/logging/index.html</a></td>
|
---|
693 | </tr>
|
---|
694 | <tr>
|
---|
695 | <td>log4j.jar</td>
|
---|
696 | <td>Log4jListener</td>
|
---|
697 | <td><a href="http://jakarta.apache.org/log4j/docs/index.html"
|
---|
698 | target="_top">http://jakarta.apache.org/log4j/docs/index.html</a></td>
|
---|
699 | </tr>
|
---|
700 | <tr>
|
---|
701 | <td><a name="commons-net">commons-net.jar</a></td>
|
---|
702 | <td>ftp, rexec and telnet tasks<br>
|
---|
703 | jakarta-oro 2.0.8 or later is required together with commons-net 1.4.0.<br>
|
---|
704 | For all users, a minimum version of commons-net of 1.4.0 is recommended. Earlier
|
---|
705 | versions did not support the full range of configuration options, and 1.4.0 is needed
|
---|
706 | to compile Ant.
|
---|
707 | </td>
|
---|
708 | <td><a href="http://jakarta.apache.org/commons/net/index.html"
|
---|
709 | target="_top">http://jakarta.apache.org/commons/net/index.html</a></td>
|
---|
710 | </tr>
|
---|
711 | <tr>
|
---|
712 | <td>bcel.jar</td>
|
---|
713 | <td>classfileset data type,
|
---|
714 | JavaClassHelper used by the ClassConstants filter reader and
|
---|
715 | optionally used by ejbjar for dependency determination
|
---|
716 | </td>
|
---|
717 | <td><a href="http://jakarta.apache.org/bcel/" target="_top">http://jakarta.apache.org/bcel/</a></td>
|
---|
718 | </tr>
|
---|
719 | <tr>
|
---|
720 | <td>mail.jar</td>
|
---|
721 | <td>Mail task with Mime encoding, and the MimeMail task</td>
|
---|
722 | <td><a href="http://java.sun.com/products/javamail/"
|
---|
723 | target="_top">http://java.sun.com/products/javamail/</a></td>
|
---|
724 | </tr>
|
---|
725 | <tr>
|
---|
726 | <td>jsse.jar</td>
|
---|
727 | <td>
|
---|
728 | Support for SMTP over TLS/SSL <br>
|
---|
729 | in the Mail task<br>
|
---|
730 | Already included Java 1.4+</td>
|
---|
731 | <td><a href="http://java.sun.com/products/jsse/"
|
---|
732 | target="_top">http://java.sun.com/products/jsse/</a></td>
|
---|
733 | </tr>
|
---|
734 | <tr>
|
---|
735 | <td>activation.jar</td>
|
---|
736 | <td>Mail task with Mime encoding, and the MimeMail task</td>
|
---|
737 | <td><a href="http://java.sun.com/products/javabeans/glasgow/jaf.html"
|
---|
738 | target="_top">http://java.sun.com/products/javabeans/glasgow/jaf.html</a></td>
|
---|
739 | </tr>
|
---|
740 | <tr>
|
---|
741 | <td>jdepend.jar</td>
|
---|
742 | <td>jdepend task</td>
|
---|
743 | <td><a href="http://www.clarkware.com/software/JDepend.html"
|
---|
744 | target="_top">http://www.clarkware.com/software/JDepend.html</a></td>
|
---|
745 | </tr>
|
---|
746 | <tr>
|
---|
747 | <td>resolver.jar <b>1.1beta or later</b></td>
|
---|
748 | <td>xmlcatalog datatype <em>only if support for external catalog files is desired</em></td>
|
---|
749 | <td><a href="http://xml.apache.org/commons/"
|
---|
750 | target="_top">http://xml.apache.org/commons/</a>.</td>
|
---|
751 | </tr>
|
---|
752 | <tr>
|
---|
753 | <td>jsch.jar <b>0.1.29 or later</b></td>
|
---|
754 | <td>sshexec and scp tasks</td>
|
---|
755 | <td><a href="http://www.jcraft.com/jsch/index.html"
|
---|
756 | target="_top">http://www.jcraft.com/jsch/index.html</a></td>
|
---|
757 | </tr>
|
---|
758 | <tr>
|
---|
759 | <td>JAI - Java Advanced Imaging</td>
|
---|
760 | <td>image task</td>
|
---|
761 | <td><a href="http://java.sun.com/products/java-media/jai/"
|
---|
762 | target="_top">http://java.sun.com/products/java-media/jai/</a></td>
|
---|
763 | </tr>
|
---|
764 | <tr>
|
---|
765 | <td>Starteam SDK</td>
|
---|
766 | <td>Starteam version management tasks</td>
|
---|
767 | <td><a href="http://www.borland.com/downloads/download_starteam.html"
|
---|
768 | target="_top">http://www.borland.com/downloads/download_starteam.html</a></td>
|
---|
769 | </tr>
|
---|
770 | </table>
|
---|
771 | <br>
|
---|
772 | <h2><a name="Troubleshooting">Troubleshooting</a></h2>
|
---|
773 |
|
---|
774 |
|
---|
775 | <h3><a name="diagnostics">Diagnostics</a></h3>
|
---|
776 |
|
---|
777 | <p> Ant has a built in diagnostics feature. If you run <code>ant
|
---|
778 | -diagnostics</code> ant will look at its internal state and print it out. This
|
---|
779 | code will check and print the following things. </p>
|
---|
780 |
|
---|
781 | <ul>
|
---|
782 |
|
---|
783 | <li>Where Ant is running from. Sometimes you can be surprised.</li>
|
---|
784 |
|
---|
785 | <li>The version of ant.jar and of the ant-*.jar containing the optional tasks -
|
---|
786 | and whether they match</li>
|
---|
787 |
|
---|
788 | <li>Which JAR files are int ANT_HOME/lib
|
---|
789 |
|
---|
790 | <li>Which optional tasks are available. If a task is not listed as being
|
---|
791 | available, either it is not present, or libraries that it depends on are
|
---|
792 | absent.</li>
|
---|
793 |
|
---|
794 |
|
---|
795 | <li>XML Parser information</li>
|
---|
796 |
|
---|
797 | <li>JVM system properties
|
---|
798 | </li>
|
---|
799 |
|
---|
800 | <li>The status of the temp directory. If this is not writeable, or its clock is
|
---|
801 | horribly wrong (possible if it is on a network drive), a lot of tasks will fail
|
---|
802 | with obscure error messages.</li>
|
---|
803 |
|
---|
804 | <li>The current time zone as Java sees it. If this is not what it should be for
|
---|
805 | your location, then dependency logic may get confused.
|
---|
806 |
|
---|
807 | </ul>
|
---|
808 |
|
---|
809 | <p>
|
---|
810 | Running <code>ant -diagnostics</code> is a good way to check that ant is
|
---|
811 | installed. It is also a first step towards self-diagnosis of any problem.
|
---|
812 | Any configuration problem reported to the user mailing list will probably
|
---|
813 | result ins someone asking you to run the command and show the results, so
|
---|
814 | save time by using it yourself.
|
---|
815 | </p>
|
---|
816 |
|
---|
817 | <p>
|
---|
818 | For under-IDE diagostics, use the <diagnostics> task to run the same
|
---|
819 | tests as an ant task. This can be added to a diagnostics target in a build
|
---|
820 | file to see what tasks are available under the IDE, what the XML parser and
|
---|
821 | classpath is, etc.
|
---|
822 | </p>
|
---|
823 |
|
---|
824 | <h3><a name="ant-user">user mailing list</a></h3>
|
---|
825 |
|
---|
826 | <p> If you cannot get Ant installed or working, the Ant user mailing list is the
|
---|
827 | best place to start with any problem. Please do your homework first, make sure
|
---|
828 | that it is not a <a href="#classpath">CLASSPATH</a> problem, and run a <a
|
---|
829 | href="#diagnostics">diagnostics check</a> to see what Ant thinks of its own
|
---|
830 | state. Why the user list, and not the developer list?
|
---|
831 | Because there are more users than developers, so more people who can help you. </p>
|
---|
832 |
|
---|
833 | <p>
|
---|
834 |
|
---|
835 | Please only file a bug report against Ant for a configuration/startup problem if
|
---|
836 | there really is a fixable bug in Ant related to configuration, such as it not
|
---|
837 | working on a particular platform, with a certain JVM version, etc, or if you are
|
---|
838 | advised to do it by the user mailing list.
|
---|
839 | </p>
|
---|
840 |
|
---|
841 |
|
---|
842 |
|
---|
843 |
|
---|
844 | </body>
|
---|
845 | </html>
|
---|