source: other-projects/trunk/gs3-release-maker/apache-ant-1.6.5/docs/manual/install.html@ 14627

Last change on this file since 14627 was 14627, checked in by oranfry, 17 years ago

initial import of the gs3-release-maker
File size: 19.8 KB
Line 
1<html>
2
3<head>
4<meta http-equiv="Content-Language" content="en-us">
5<title>Installing Ant</title>
6<link rel="stylesheet" type="text/css" href="stylesheets/antmanual.css">
7</head>
8
9<body>
10<h1>Installing Ant</h1>
11<h2><a name="getting">Getting Ant</a></h2>
12<h3>Binary Edition</h3>
13<p>The latest stable version of Ant is available from the Ant web page <a
14href="http://ant.apache.org/">http://ant.apache.org/</a>.
15
16If you like living on the edge, you can download the latest version from <a
17href="http://cvs.apache.org/builds/ant/nightly/">http://cvs.apache.org/builds/ant/nightly/</a>.</p>
18<h3>Source Edition</h3>
19
20<p>If you prefer the source edition, you can download the source for the latest Ant release from <a href="http://ant.apache.org/srcdownload.cgi">http://ant.apache.org/srcdownload.cgi</a>.
21
22Again, if you prefer the edge, you can access
23the code as it is being developed via CVS. The Jakarta website has details on
24<a href="http://jakarta.apache.org/site/cvsindex.html" target="_top">accessing CVS</a>. Please checkout the
25ant module.
26
27See the section <a href="#buildingant">Building Ant</a> on how to
28build Ant from the source code.
29You can also access the
30<a href="http://cvs.apache.org/viewcvs/ant/" target="_top">
31Ant CVS repository</a> on-line. </p>
32
33<hr>
34<h2><a name="sysrequirements">System Requirements</a></h2>
35Ant has been used successfully on many platforms, including Linux,
36commercial flavours of Unix such as Solaris and HP-UX,
37Windows 9x and NT, OS/2 Warp, Novell Netware 6 and MacOS X.
38<p>
39To build and use Ant, you must have a JAXP-compliant XML parser installed and
40available on your classpath.</p>
41<p>
42The binary distribution of Ant includes the latest version of the
43<a href="http://xml.apache.org/xerces2-j/index.html">Apache Xerces2</a> XML parser.
44Please see
45<a href="http://java.sun.com/xml/" target="_top">http://java.sun.com/xml/</a>
46for more information about JAXP.
47If you wish to use a different JAXP-compliant parser, you should remove
48<code>xercesImpl.jar</code> and <code>xml-apis.jar</code>
49from Ant's <code>lib</code> directory.
50
51You can then either put the jars from your preferred parser into Ant's
52<code>lib</code> directory or put the jars on the system classpath.</p>
53
54<p>
55For the current version of Ant, you will also need a JDK installed on
56your system, version 1.2 or later.
57</p><p>
58<strong>Note: </strong>The Microsoft JVM/JDK is not supported.
59</p>
60<p>
61<strong>Note #2: </strong>If a JDK is not present, only the JRE runtime, then many tasks will not work.
62</p>
63<hr>
64<h2><a name="installing">Installing Ant</a></h2>
65<p>The binary distribution of Ant consists of the following directory layout:
66<pre>
67 ant
68 +--- bin // contains launcher scripts
69 |
70 +--- lib // contains Ant jars plus necessary dependencies
71 |
72 +--- docs // contains documentation
73 | +--- ant2 // a brief description of ant2 requirements
74 | |
75 | +--- images // various logos for html documentation
76 | |
77 | +--- manual // Ant documentation (a must read ;-)
78 |
79 +--- etc // contains xsl goodies to:
80 // - create an enhanced report from xml output of various tasks.
81 // - migrate your build files and get rid of 'deprecated' warning
82 // - ... and more ;-)
83</pre>
84
85Only the <code>bin</code> and <code>lib</code> directories are
86required to run Ant.
87
88To install Ant, choose a directory and copy the distribution
89file there. This directory will be known as ANT_HOME.
90</p>
91
92<table width="80%">
93<tr>
94 <td colspan="2">
95 <b>Windows 95, Windows 98 &amp; Windows ME Note:</b>
96 </td>
97</tr>
98<tr>
99 <td width="5%">&nbsp;</td>
100 <td><i>
101On these systems, the script used to launch Ant will have
102problems if ANT_HOME is a long filename (i.e. a filename which is not
103of the format known as &quot;8.3&quot;). This is due to
104limitations in the OS's handling of the <code>&quot;for&quot;</code>
105batch-file statement. It is recommended, therefore, that Ant be
106installed in a <b>short</b>, 8.3 path, such as C:\Ant. </i>
107 </td>
108</tr>
109<tr>
110 <td width="5%">&nbsp;</td>
111 <td>
112 <p>On these systems you will also need to configure more environment
113 space to cater for the environment variables used in the Ant lauch script.
114 To do this, you will need to add or update the following line in
115 the <code>config.sys</code> file
116 </p>
117 <p><code>shell=c:\command.com c:\ /p /e:32768</code></p>
118 </td>
119</tr>
120</table>
121
122<h3>Setup</h3>
123<p>
124Before you can run ant there is some additional set up you
125will need to do:</p>
126<ul>
127<li>Add the <code>bin</code> directory to your path.</li>
128<li>Set the <code>ANT_HOME</code> environment variable to the
129directory where you installed Ant. On some operating systems the ant
130wrapper scripts can guess <code>ANT_HOME</code> (Unix dialects and
131Windows NT/2000) - but it is better to not rely on this behavior.</li>
132<li>Optionally, set the <code>JAVA_HOME</code> environment variable
133(see the <a href="#advanced">Advanced</a> section below).
134This should be set to the directory where your JDK is installed.</li>
135</ul>
136<p><strong>Note:</strong> Do not install Ant's ant.jar file into the lib/ext
137directory of the JDK/JRE. Ant is an application, whilst the extension
138directory is intended for JDK extensions. In particular there are security
139restrictions on the classes which may be loaded by an extension.</p>
140
141<h3><a name="optionalTasks">Optional Tasks</a></h3>
142<p>Ant supports a number of optional tasks. An optional task is a task which
143typically requires an external library to function. The optional tasks are
144packaged together with the core Ant tasks.</p>
145
146<p>The external libraries required by each of the optional tasks is detailed
147in the <a href="#librarydependencies">Library Dependencies</a> section. These external
148libraries may either be placed in Ant's lib directory, where they will be picked up
149automatically, or made available on the system CLASSPATH environment variable.
150</p>
151
152<h3>Windows and OS/2</h3>
153<p>Assume Ant is installed in <code>c:\ant\</code>. The following sets up the
154environment:</p>
155<pre>set ANT_HOME=c:\ant
156set JAVA_HOME=c:\jdk1.2.2
157set PATH=%PATH%;%ANT_HOME%\bin</pre>
158
159<h3>Unix (bash)</h3>
160<p>Assume Ant is installed in <code>/usr/local/ant</code>. The following sets up
161the environment:</p>
162<pre>export ANT_HOME=/usr/local/ant
163export JAVA_HOME=/usr/local/jdk-1.2.2
164export PATH=${PATH}:${ANT_HOME}/bin</pre>
165
166<h3>Unix (csh)</h3>
167<pre>setenv ANT_HOME /usr/local/ant
168setenv JAVA_HOME /usr/local/jdk-1.2.2
169set path=( $path $ANT_HOME/bin )</pre>
170
171
172<h3><a name="advanced">Advanced</a></h3>
173
174<p>There are lots of variants that can be used to run Ant. What you need is at
175least the following:</p>
176<ul>
177<li>The classpath for Ant must contain <code>ant.jar</code> and any jars/classes
178needed for your chosen JAXP-compliant XML parser.</li>
179<li>When you need JDK functionality
180(such as for the <a href="CoreTasks/javac.html">javac</a> task or the
181<a href="CoreTasks/rmic.html">rmic</a> task), then for JDK 1.1, the <code>classes.zip</code>
182file of the JDK must be added to the classpath; for JDK 1.2 or JDK 1.3, <code>tools.jar</code>
183must be added. The scripts supplied with Ant,
184in the <code>bin</code> directory, will add
185the required JDK classes automatically, if the <code>JAVA_HOME</code>
186environment variable is set.</li>
187
188<li>When you are executing platform-specific applications, such as the
189<a href="CoreTasks/exec.html">exec</a> task or the
190<a href="CoreTasks/cvs.html">cvs</a> task, the property <code>ant.home</code>
191must be set to the directory containing where you installed Ant. Again
192this is set by the Ant scripts to the value of the ANT_HOME environment
193variable.</li>
194</ul>
195The supplied ant shell scripts all support an <tt>ANT_OPTS</tt>
196environment variable which can be used to supply extra options
197to ant. Some of the scripts also read in an extra script stored
198in the users home directory, which can be used to set such options. Look
199at the source for your platform's invocation script for details.
200
201<hr>
202<h2><a name="buildingant">Building Ant</a></h2>
203<p>To build Ant from source, you can either install the Ant source distribution
204or checkout the ant module from CVS.</p>
205<p>Once you have installed the source, change into the installation
206directory.</p>
207
208<p>Set the <code>JAVA_HOME</code> environment variable
209to the directory where the JDK is installed.
210See <a href="#installing">Installing Ant</a>
211for examples on how to do this for your operating system. </p>
212
213<p><b>Note</b>: The bootstrap process of Ant requires a greedy
214compiler like Sun's javac or jikes. It does not work with gcj or
215kjc.</b>
216
217<p>Make sure you have downloaded any auxiliary jars required to
218build tasks you are interested in. These should either be available
219on the CLASSPATH or added to the <code>lib</code>
220directory.
221See <a href="#librarydependencies">Library Dependencies</a>
222for a list of jar requirements for various features.
223Note that this will make the auxiliary jars
224available for the building of Ant only. For running Ant you will
225still need to
226make the jars available as described under
227<a href="#installing">Installing Ant</a>.</p>
228
229<p>Your are now ready to build Ant:</p>
230<blockquote>
231 <p><code>build -Ddist.dir=&lt;<i>directory_to_contain_Ant_distribution</i>&gt; dist</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>
232 <p><code>build.sh -Ddist.dir=&lt;<i>directory_to_contain_Ant_distribution</i>&gt; dist</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>
233</blockquote>
234
235<p>This will create a binary distribution of Ant in the directory you specified.</p>
236
237<p>The above action does the following:</p>
238<ul>
239
240<li>If necessary it will bootstrap the Ant code. Bootstrapping involves the manual
241compilation of enough Ant code to be able to run Ant. The bootstrapped Ant is
242used for the remainder of the build steps. </li>
243
244<li>Invokes the bootstrapped Ant with the parameters passed to the build script. In
245this case, these parameters define an Ant property value and specify the &quot;dist&quot; target
246in Ant's own <code>build.xml</code> file.</li>
247</ul>
248
249<p>On most occasions you will not need to explicitly bootstrap Ant since the build
250scripts do that for you. If however, the build file you are using makes use of features
251not yet compiled into the bootstrapped Ant, you will need to manually bootstrap.
252Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX)
253to build a new bootstrap version of Ant.</p>
254
255If you wish to install the build into the current <code>ANT_HOME</code>
256directory, you can use:
257<blockquote>
258 <p><code>build install</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>
259 <p><code>build.sh install</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>
260</blockquote>
261
262You can avoid the lengthy Javadoc step, if desired, with:
263<blockquote>
264 <p><code>build install-lite</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>
265 <p><code>build.sh install-lite</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>
266</blockquote>
267This will only install the <code>bin</code> and <code>lib</code> directories.
268<p>Both the <code>install</code> and
269<code>install-lite</code> targets will overwrite
270the current Ant version in <code>ANT_HOME</code>.</p>
271
272<hr>
273<h2><a name="librarydependencies">Library Dependencies</a></h2>
274<p>The following libraries are needed in your CLASSPATH or in the
275install directory's <code>lib</code> directory if you are using the
276indicated feature. Note that only one of the regexp libraries is
277needed for use with the mappers
278(and Java 1.4 and higher includes a regexp implementation which
279Ant will find automatically).
280You will also need to install the
281Ant optional jar containing the task definitions to make these
282tasks available. Please refer to the <a href="#optionalTasks">
283Installing Ant / Optional Tasks</a> section above.</p>
284
285<table border="1" cellpadding="2" cellspacing="0">
286 <tr>
287 <td><b>Jar Name</b></td>
288 <td><b>Needed For</b></td>
289 <td><b>Available At</b></td>
290 </tr>
291 <tr>
292 <td>An XSL transformer like Xalan or XSL:P</td>
293 <td>style task</td>
294 <td>
295 <b>If you use JDK 1.4, an XSL transformer is already included, so you need not do anything special.</b><br>
296 <ul><li>XALAN : <a href="http://xml.apache.org/xalan-j/index.html"
297 target="_top">http://xml.apache.org/xalan-j/index.html</a></li>
298 <li>XSL:P : used to live at <a href="http://www.clc-marketing.com/xslp/"
299 target="_top">http://www.clc-marketing.com/xslp/</a>, but the link
300 doesn't work any longer and we are not aware of a replacement site.</li></ul>
301 </td>
302 </tr>
303 <tr>
304 <td>jakarta-regexp-1.3.jar</td>
305 <td>regexp type with mappers</td>
306 <td><a href="http://jakarta.apache.org/regexp/" target="_top">http://jakarta.apache.org/regexp/</a></td>
307 </tr>
308 <tr>
309 <td>jakarta-oro-2.0.7.jar</td>
310 <td>regexp type with mappers and the perforce tasks<br>
311 To use the FTP task,
312you need jakarta-oro 2.0.1 or later, and <a href="#commons-net">commons-net</a></td>
313 <td><a href="http://jakarta.apache.org/oro/" target="_top">http://jakarta.apache.org/oro/</a></td>
314 </tr>
315 <tr>
316 <td>junit.jar</td>
317 <td>junit tasks</td>
318 <td><a href="http://www.junit.org/" target="_top">http://www.junit.org/</a></td>
319 </tr>
320 <tr>
321 <td>xalan.jar</td>
322 <td>junitreport task</td>
323 <td><a href="http://xml.apache.org/xalan-j/" target="_top">http://xml.apache.org/xalan-j/</a></td>
324 </tr>
325 <tr>
326 <td>stylebook.jar</td>
327 <td>stylebook task</td>
328 <td>CVS repository of <a href="http://xml.apache.org/" target="_top">http://xml.apache.org/</a></td>
329 </tr>
330 <tr>
331 <td>testlet.jar</td>
332 <td><strong>deprecated</strong> test task</td>
333 <td>Build from the gzip compress tar archive in <a
334 href="http://avalon.apache.org/historiccvs/testlet/"
335 target="_top">http://avalon.apache.org/historiccvs/testlet/</a></td>
336 </tr>
337 <tr>
338 <td>antlr.jar</td>
339 <td>antlr task</td>
340 <td><a href="http://www.antlr.org/" target="_top">http://www.antlr.org/</a></td>
341 </tr>
342 <tr>
343 <td >bsf.jar</td>
344 <td>script task<br/>
345 <strong>Note</strong>: Ant 1.6 and later require Apache BSF, not
346 the IBM version. I.e. you need BSF 2.3.0-rc1 or later.</td>
347 <td><a href="http://jakarta.apache.org/bsf/" target="_top">http://jakarta.apache.org/bsf/</a></td>
348 </tr>
349 <tr>
350 <td>Groovy jars</td>
351 <td>Groovy with script and scriptdef tasks<br/>
352 You need to get the groovy jar and two asm jars from a groovy
353 installation. The jars are groovy-[version].jar, asm-[vesion].jar and
354 asm-util-[version].jar. As of groovy version 1.0-beta-7, the jars are
355 groovy-1.0-beta-7.jar, asm-1.4.3.jar and asm-util-1.4.3.jar.
356 </td>
357 <td>
358 <a href="http://groovy.codehaus.org/">http://groovy.codehaus.org/</a>
359 <br/>
360 The asm jars are also available from the creators of asm -
361 <a href="http://asm.objectweb.org/">http://asm.objectweb.org/</a>
362 </td>
363 </tr>
364 <tr>
365 <td>netrexx.jar</td>
366 <td>netrexx task, Rexx with the script task</td>
367 <td><a href="http://www2.hursley.ibm.com/netrexx/" target="_top">
368 http://www2.hursley.ibm.com/netrexx/</a></td>
369 </tr>
370 <tr>
371 <td>js.jar</td>
372 <td>Javascript with script task<br/>
373 If you use Apache BSF 2.3.0-rc1, you must use rhino 1.5R3 - later
374 versions of BSF work with 1.5R4 as well.</td>
375 <td><a href="http://www.mozilla.org/rhino/" target="_top">http://www.mozilla.org/rhino/</a></td>
376 </tr>
377 <tr>
378 <td>jython.jar</td>
379 <td>Python with script task<br>
380 Warning : jython.jar also contains classes from jakarta-oro.
381 Remove these classes if you are also using jakarta-oro.</td>
382 <td><a href="http://jython.sourceforge.net/" target="_top">http://jython.sourceforge.net/</a></td>
383 </tr>
384 <tr>
385 <td>jpython.jar</td>
386 <td>Python with script task <b>deprecated, jython is the prefered engine</b></td>
387 <td><a href="http://www.jpython.org/" target="_top">http://www.jpython.org/</a></td>
388 </tr>
389 <tr>
390 <td>jacl.jar and tcljava.jar</td>
391 <td>TCL with script task</td>
392 <td><a href="http://www.scriptics.com/software/java/" target="_top">http://www.scriptics.com/software/java/</a></td>
393 </tr>
394 <tr>
395 <td>BeanShell JAR(s)</td>
396 <td>BeanShell with script task.
397 <br/>
398 <strong>Note</strong>: Ant 1.6 and later require BeanShell version 1.3 or
399 later</td>
400 <td><a href="http://www.beanshell.org/" target="_top">http://www.beanshell.org/</a></td>
401 </tr>
402 <tr>
403 <td>jruby.jar</td>
404 <td>Ruby with script task</td>
405 <td><a href="http://jruby.sourceforge.net/" target="_top">http://jruby.sourceforge.net/</a></td>
406 </tr>
407 <tr>
408 <td>judo.jar</td>
409 <td>Judoscript with script task</td>
410 <td><a href="http://www.judoscript.com/index.html" target="_top">http://www.judoscript.com/index.html</a></td>
411 </tr>
412 <tr>
413 <td>commons-logging.jar</td>
414 <td>CommonsLoggingListener</td>
415 <td><a href="http://jakarta.apache.org/commons/logging/index.html"
416 target="_top">http://jakarta.apache.org/commons/logging/index.html</a></td>
417 </tr>
418 <tr>
419 <td>log4j.jar</td>
420 <td>Log4jListener</td>
421 <td><a href="http://jakarta.apache.org/log4j/docs/index.html"
422 target="_top">http://jakarta.apache.org/log4j/docs/index.html</a></td>
423 </tr>
424 <tr>
425 <td><a name="commons-net">commons-net.jar</td>
426 <td>ftp, rexec and telnet tasks<br>
427 jakarta-oro 2.0.1 or later is required in any case together with commons-net.<br>
428 For all users, a minimum version of commons-net of 1.2.2 is recommended. Earlier
429 versions did not support autodetection of system type or had significant bugs.
430 </td>
431 <td><a href="http://jakarta.apache.org/commons/net/index.html"
432 target="_top">http://jakarta.apache.org/commons/net/index.html</a></td>
433 </tr>
434 <tr>
435 <td>bcel.jar</td>
436 <td>classfileset data type,
437 JavaClassHelper used by the ClassConstants filter reader and
438 optionally used by ejbjar for dependency determination
439 </td>
440 <td><a href="http://jakarta.apache.org/bcel/" target="_top">http://jakarta.apache.org/bcel/</a></td>
441 </tr>
442 <tr>
443 <td>mail.jar</td>
444 <td>Mail task with Mime encoding, and the MimeMail task</td>
445 <td><a href="http://java.sun.com/products/javamail/"
446 target="_top">http://java.sun.com/products/javamail/</a></td>
447 </tr>
448 <tr>
449 <td>jsse.jar</td>
450 <td>
451Support for SMTP over TLS/SSL <br/>
452in the Mail task<br/>
453Already included in jdk 1.4</td>
454 <td><a href="http://java.sun.com/products/jsse/"
455 target="_top">http://java.sun.com/products/jsse/</a></td>
456 </tr>
457 <tr>
458 <td>activation.jar</td>
459 <td>Mail task with Mime encoding, and the MimeMail task</td>
460 <td><a href="http://java.sun.com/products/javabeans/glasgow/jaf.html"
461 target="_top">http://java.sun.com/products/javabeans/glasgow/jaf.html</a></td>
462 </tr>
463 <tr>
464 <td>jdepend.jar</td>
465 <td>jdepend task</td>
466 <td><a href="http://www.clarkware.com/software/JDepend.html"
467 target="_top">http://www.clarkware.com/software/JDepend.html</a></td>
468 </tr>
469 <tr>
470 <td>resolver.jar <b>1.1beta or later</b></td>
471 <td>xmlcatalog datatype <em>only if support for external catalog files is desired</em></td>
472 <td><a href="http://xml.apache.org/commons/"
473 target="_top">http://xml.apache.org/commons/</a>.</td>
474 </tr>
475 <tr>
476 <td>jsch.jar</td>
477 <td>sshexec and scp tasks</td>
478 <td><a href="http://www.jcraft.com/jsch/index.html"
479 target="_top">http://www.jcraft.com/jsch/index.html</a></td>
480 </tr>
481 <tr>
482 <td>JAI - Java Advanded Imaging</td>
483 <td>image task</td>
484 <td><a href="http://java.sun.com/products/java-media/jai/"
485 target="_top">http://java.sun.com/products/java-media/jai/</a></td>
486 </tr>
487 <tr>
488 <td>IContract</td>
489 <td>icontract task<br/>
490 Warning : the icontract jar file contains also antlr classes.<br/>
491 To make the antlr task work properly, remove antlr/ANTLRGrammarParseBehavior.class
492 from the icontract jar file installed under $ANT_HOME/lib.</td>
493 <td><a href="http://www.reliable-systems.com/tools/"
494 target="_top">http://www.reliable-systems.com/tools/</a></td>
495 </tr>
496</table>
497<br>
498<hr>
499<p align="center">Copyright &copy; 2000-2004 The Apache Software Foundation. All rights
500Reserved.</p>
501
502</body>
503</html>
504
Note: See TracBrowser for help on using the repository browser.