source: other-projects/trunk/realistic-books/packages/AntInstaller/web/manual1.6.2/manual/install.html@ 19253

Last change on this file since 19253 was 19253, checked in by davidb, 15 years ago

Establishing a source code repository for Veronica's Realistic Book's software
File size: 18.9 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>Make sure you have downloaded any auxiliary jars required to
214build tasks you are interested in. These should either be available
215on the CLASSPATH or added to the <code>lib</code>
216directory.
217See <a href="#librarydependencies">Library Dependencies</a>
218for a list of jar requirements for various features.
219Note that this will make the auxiliary jars
220available for the building of Ant only. For running Ant you will
221still need to
222make the jars available as described under
223<a href="#installing">Installing Ant</a>.</p>
224
225<p>Your are now ready to build Ant:</p>
226<blockquote>
227 <p><code>build -Ddist.dir=&lt;<i>directory_to_contain_Ant_distribution</i>&gt; dist</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>
228 <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>
229</blockquote>
230
231<p>This will create a binary distribution of Ant in the directory you specified.</p>
232
233<p>The above action does the following:</p>
234<ul>
235
236<li>If necessary it will bootstrap the Ant code. Bootstrapping involves the manual
237compilation of enough Ant code to be able to run Ant. The bootstrapped Ant is
238used for the remainder of the build steps. </li>
239
240<li>Invokes the bootstrapped Ant with the parameters passed to the build script. In
241this case, these parameters define an Ant property value and specify the &quot;dist&quot; target
242in Ant's own <code>build.xml</code> file.</li>
243</ul>
244
245<p>On most occasions you will not need to explicitly bootstrap Ant since the build
246scripts do that for you. If however, the build file you are using makes use of features
247not yet compiled into the bootstrapped Ant, you will need to manually bootstrap.
248Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX)
249to build a new bootstrap version of Ant.</p>
250
251If you wish to install the build into the current <code>ANT_HOME</code>
252directory, you can use:
253<blockquote>
254 <p><code>build install</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>
255 <p><code>build.sh install</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>
256</blockquote>
257
258You can avoid the lengthy Javadoc step, if desired, with:
259<blockquote>
260 <p><code>build install-lite</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>
261 <p><code>build.sh install-lite</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>
262</blockquote>
263This will only install the <code>bin</code> and <code>lib</code> directories.
264<p>Both the <code>install</code> and
265<code>install-lite</code> targets will overwrite
266the current Ant version in <code>ANT_HOME</code>.</p>
267
268<hr>
269<h2><a name="librarydependencies">Library Dependencies</a></h2>
270<p>The following libraries are needed in your CLASSPATH or in the
271install directory's <code>lib</code> directory if you are using the
272indicated feature. Note that only one of the regexp libraries is
273needed for use with the mappers
274(and Java 1.4 and higher includes a regexp implementation which
275Ant will find automatically).
276You will also need to install the
277Ant optional jar containing the task definitions to make these
278tasks available. Please refer to the <a href="#optionalTasks">
279Installing Ant / Optional Tasks</a> section above.</p>
280
281<table border="1" cellpadding="2" cellspacing="0">
282 <tr>
283 <td><b>Jar Name</b></td>
284 <td><b>Needed For</b></td>
285 <td><b>Available At</b></td>
286 </tr>
287 <tr>
288 <td>An XSL transformer like Xalan or XSL:P</td>
289 <td>style task</td>
290 <td>
291 <b>If you use JDK 1.4, an XSL transformer is already included, so you need not do anything special.</b><br>
292 <ul><li>XALAN : <a href="http://xml.apache.org/xalan-j/index.html"
293 target="_top">http://xml.apache.org/xalan-j/index.html</a></li>
294 <li>XSL:P : used to live at <a href="http://www.clc-marketing.com/xslp/"
295 target="_top">http://www.clc-marketing.com/xslp/</a>, but the link
296 doesn't work any longer and we are not aware of a replacement site.</li></ul>
297 </td>
298 </tr>
299 <tr>
300 <td>jakarta-regexp-1.3.jar</td>
301 <td>regexp type with mappers</td>
302 <td><a href="http://jakarta.apache.org/regexp/" target="_top">http://jakarta.apache.org/regexp/</a></td>
303 </tr>
304 <tr>
305 <td>jakarta-oro-2.0.7.jar</td>
306 <td>regexp type with mappers and the perforce tasks<br>
307 To use the FTP task,
308you need jakarta-oro 2.0.1 or later, and <a href="#commons-net">commons-net</a></td>
309 <td><a href="http://jakarta.apache.org/oro/" target="_top">http://jakarta.apache.org/oro/</a></td>
310 </tr>
311 <tr>
312 <td>junit.jar</td>
313 <td>junit tasks</td>
314 <td><a href="http://www.junit.org/" target="_top">http://www.junit.org/</a></td>
315 </tr>
316 <tr>
317 <td>xalan.jar</td>
318 <td>junitreport task</td>
319 <td><a href="http://xml.apache.org/xalan-j/" target="_top">http://xml.apache.org/xalan-j/</a></td>
320 </tr>
321 <tr>
322 <td>stylebook.jar</td>
323 <td>stylebook task</td>
324 <td>CVS repository of <a href="http://xml.apache.org/" target="_top">http://xml.apache.org/</a></td>
325 </tr>
326 <tr>
327 <td>testlet.jar</td>
328 <td><strong>deprecated</strong> test task</td>
329 <td>Build from the gzip compress tar archive in <a
330 href="http://avalon.apache.org/historiccvs/testlet/"
331 target="_top">http://avalon.apache.org/historiccvs/testlet/</a></td>
332 </tr>
333 <tr>
334 <td>antlr.jar</td>
335 <td>antlr task</td>
336 <td><a href="http://www.antlr.org/" target="_top">http://www.antlr.org/</a></td>
337 </tr>
338 <tr>
339 <td >bsf.jar</td>
340 <td>script task<br/>
341 <strong>Note</strong>: Ant 1.6 and later require Apache BSF, not
342 the IBM version. I.e. you need BSF 2.3.0-rc1 or later.</td>
343 <td><a href="http://jakarta.apache.org/bsf/" target="_top">http://jakarta.apache.org/bsf/</a></td>
344 </tr>
345 <tr>
346 <td>netrexx.jar</td>
347 <td>netrexx task, Rexx with the script task</td>
348 <td><a href="http://www2.hursley.ibm.com/netrexx/" target="_top">
349 http://www2.hursley.ibm.com/netrexx/</a></td>
350 </tr>
351 <tr>
352 <td>js.jar</td>
353 <td>Javascript with script task<br/>
354 If you use Apache BSF 2.3.0-rc1, you must use rhino 1.5R3 - later
355 versions of BSF work with 1.5R4 as well.</td>
356 <td><a href="http://www.mozilla.org/rhino/" target="_top">http://www.mozilla.org/rhino/</a></td>
357 </tr>
358 <tr>
359 <td>jython.jar</td>
360 <td>Python with script task</td>
361 <td><a href="http://jython.sourceforge.net/" target="_top">http://jython.sourceforge.net/</a></td>
362 </tr>
363 <tr>
364 <td>jpython.jar</td>
365 <td>Python with script task <b>deprecated, jython is the prefered engine</b></td>
366 <td><a href="http://www.jpython.org/" target="_top">http://www.jpython.org/</a></td>
367 </tr>
368 <tr>
369 <td>jacl.jar and tcljava.jar</td>
370 <td>TCL with script task</td>
371 <td><a href="http://www.scriptics.com/software/java/" target="_top">http://www.scriptics.com/software/java/</a></td>
372 </tr>
373 <tr>
374 <td>BeanShell JAR(s)</td>
375 <td>BeanShell with script task.
376 <br/>
377 <strong>Note</strong>: Ant 1.6 and later require BeanShell version 1.3 or
378 later</td>
379 <td><a href="http://www.beanshell.org/" target="_top">http://www.beanshell.org/</a></td>
380 </tr>
381 <tr>
382 <td>jruby.jar</td>
383 <td>Ruby with script task</td>
384 <td><a href="http://jruby.sourceforge.net/" target="_top">http://jruby.sourceforge.net/</a></td>
385 </tr>
386 <tr>
387 <td>judo.jar</td>
388 <td>Judoscript with script task</td>
389 <td><a href="http://www.judoscript.com/index.html" target="_top">http://www.judoscript.com/index.html</a></td>
390 </tr>
391 <tr>
392 <td>commons-logging.jar</td>
393 <td>CommonsLoggingListener</td>
394 <td><a href="http://jakarta.apache.org/commons/logging/index.html"
395 target="_top">http://jakarta.apache.org/commons/logging/index.html</a></td>
396 </tr>
397 <tr>
398 <td>log4j.jar</td>
399 <td>Log4jListener</td>
400 <td><a href="http://jakarta.apache.org/log4j/docs/index.html"
401 target="_top">http://jakarta.apache.org/log4j/docs/index.html</a></td>
402 </tr>
403 <tr>
404 <td><a name="commons-net">commons-net.jar</td>
405 <td>ftp, rexec and telnet tasks<br>
406 jakarta-oro 2.0.1 or later is required in any case together with commons-net.<br>
407 For all users, a minimum version of commons-net of 1.2.2 is recommended. Earlier
408 versions did not support autodetection of system type or had significant bugs.
409 </td>
410 <td><a href="http://jakarta.apache.org/commons/net/index.html"
411 target="_top">http://jakarta.apache.org/commons/net/index.html</a></td>
412 </tr>
413 <tr>
414 <td>bcel.jar</td>
415 <td>classfileset data type,
416 JavaClassHelper used by the ClassConstants filter reader and
417 optionally used by ejbjar for dependency determination
418 </td>
419 <td><a href="http://jakarta.apache.org/bcel/" target="_top">http://jakarta.apache.org/bcel/</a></td>
420 </tr>
421 <tr>
422 <td>mail.jar</td>
423 <td>Mail task with Mime encoding, and the MimeMail task</td>
424 <td><a href="http://java.sun.com/products/javamail/"
425 target="_top">http://java.sun.com/products/javamail/</a></td>
426 </tr>
427 <tr>
428 <td>jsse.jar</td>
429 <td>
430Support for SMTP over TLS/SSL <br/>
431in the Mail task<br/>
432Already included in jdk 1.4</td>
433 <td><a href="http://java.sun.com/products/jsse/"
434 target="_top">http://java.sun.com/products/jsse/</a></td>
435 </tr>
436 <tr>
437 <td>activation.jar</td>
438 <td>Mail task with Mime encoding, and the MimeMail task</td>
439 <td><a href="http://java.sun.com/products/javabeans/glasgow/jaf.html"
440 target="_top">http://java.sun.com/products/javabeans/glasgow/jaf.html</a></td>
441 </tr>
442 <tr>
443 <td>jdepend.jar</td>
444 <td>jdepend task</td>
445 <td><a href="http://www.clarkware.com/software/JDepend.html"
446 target="_top">http://www.clarkware.com/software/JDepend.html</a></td>
447 </tr>
448 <tr>
449 <td>resolver.jar <b>1.1beta or later</b></td>
450 <td>xmlcatalog datatype <em>only if support for external catalog files is desired</em></td>
451 <td><a href="http://xml.apache.org/commons/"
452 target="_top">http://xml.apache.org/commons/</a>.</td>
453 </tr>
454 <tr>
455 <td>jsch.jar</td>
456 <td>sshexec and scp tasks</td>
457 <td><a href="http://www.jcraft.com/jsch/index.html"
458 target="_top">http://www.jcraft.com/jsch/index.html</a></td>
459 </tr>
460 <tr>
461 <td>JAI - Java Advanded Imaging</td>
462 <td>image task</td>
463 <td><a href="http://java.sun.com/products/java-media/jai/"
464 target="_top">http://java.sun.com/products/java-media/jai/</a></td>
465 </tr>
466 <tr>
467 <td>IContract</td>
468 <td>icontract task<br/>
469 Warning : the icontract jar file contains also antlr classes.<br/>
470 To make the antlr task work properly, remove antlr/ANTLRGrammarParseBehavior.class
471 from the icontract jar file installed under $ANT_HOME/lib.</td>
472 <td><a href="http://www.reliable-systems.com/tools/"
473 target="_top">http://www.reliable-systems.com/tools/</a></td>
474 </tr>
475</table>
476<br>
477<hr>
478<p align="center">Copyright &copy; 2000-2004 The Apache Software Foundation. All rights
479Reserved.</p>
480
481</body>
482</html>
483
Note: See TracBrowser for help on using the repository browser.