youys
/
ant

<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
<title>Installing Ant</title>
</head>

<body>
<h1>Installing Ant</h1>
<h2><a name="getting">Getting Ant</a></h2>
<h3>Binary Edition</h3>
<p>The latest stable version of Ant is available from the Ant web page <a
href="http://ant.apache.org/">http://ant.apache.org/</a>.

If you like living on the edge, you can download the latest version from <a
href="http://cvs.apache.org/builds/ant/nightly/">http://cvs.apache.org/builds/ant/nightly/</a>.</p>
<h3>Source Edition</h3>

<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>.

Again, if you prefer the edge, you can access
the code as it is being developed via CVS. The Jakarta website has details on
<a href="http://jakarta.apache.org/site/cvsindex.html" target="_top">accessing CVS</a>. Please checkout the
ant module.

See the section <a href="#buildingant">Building Ant</a> on how to
build Ant from the source code.
You can also access the
<a href="http://cvs.apache.org/viewcvs/ant/" target="_top">
Ant CVS repository</a> on-line. </p>

<hr>
<h2><a name="sysrequirements">System Requirements</a></h2>
Ant has been used successfully on many platforms, including Linux,
commercial flavours of Unix such as Solaris and HP-UX,
Windows 9x and NT, OS/2 Warp, Novell Netware 6 and MacOS X.
<p>
To build and use Ant, you must have a JAXP-compliant XML parser installed and
available on your classpath.</p>
<p>
The binary distribution of Ant includes the latest version of the
<a href="http://xml.apache.org/xerces2-j/index.html">Apache Xerces2</a> XML parser.
Please see
<a href="http://java.sun.com/xml/" target="_top">http://java.sun.com/xml/</a>
for more information about JAXP.
If you wish to use a different JAXP-compliant parser, you should remove
<code>xercesImpl.jar</code> and <code>xml-apis.jar</code>
from Ant's <code>lib</code> directory.

You can then either put the jars from your preferred parser into Ant's
<code>lib</code> directory or put the jars on the system classpath.</p>

<p>
For the current version of Ant, you will also need a JDK installed on
your system, version 1.2 or later.
</p><p>
<strong>Note: </strong>The Microsoft JVM/JDK is not supported.
</p>
<p>
<strong>Note #2: </strong>If a JDK is not present, only the JRE runtime, then many tasks will not work.
</p>
<hr>
<h2><a name="installing">Installing Ant</a></h2>
<p>The binary distribution of Ant consists of the following directory layout:
<pre>
  ant
   +--- bin  // contains launcher scripts
   |
   +--- lib  // contains Ant jars plus necessary dependencies
   |
   +--- docs // contains documentation
   |      +--- ant2    // a brief description of ant2 requirements
   |      |
   |      +--- images  // various logos for html documentation
   |      |
   |      +--- manual  // Ant documentation (a must read ;-)
   |
   +--- etc // contains xsl goodies to:
            //   - create an enhanced report from xml output of various tasks.
            //   - migrate your build files and get rid of 'deprecated' warning
            //   - ... and more ;-)
</pre>

Only the <code>bin</code> and <code>lib</code> directories are
required to run Ant.

To install Ant, choose a directory and copy the distribution
file there. This directory will be known as ANT_HOME.
</p>

<table width="80%">
<tr>
  <td colspan="2">
    <b>Windows 95, Windows 98 &amp; Windows ME Note:</b>
  </td>
</tr>
<tr>
  <td width="5%">&nbsp;</td>
  <td><i>
On these systems, the script used to launch Ant will have
problems if ANT_HOME is a long filename (i.e. a filename which is not
of the format known as &quot;8.3&quot;). This is due to
limitations in the OS's handling of the <code>&quot;for&quot;</code>
batch-file statement. It is recommended, therefore, that Ant be
installed in a <b>short</b>, 8.3 path, such as C:\Ant. </i>
  </td>
</tr>
<tr>
  <td width="5%">&nbsp;</td>
  <td>
    <p>On these systems you will also need to configure more environment
       space to cater for the environment variables used in the Ant lauch script.
       To do this, you will need to add or update the following line in
       the <code>config.sys</code> file
    </p>
    <p><code>shell=c:\command.com c:\ /p /e:32768</code></p>
  </td>
</tr>
</table>

<h3>Setup</h3>
<p>
Before you can run ant there is some additional set up you
will need to do unless you are installing the <a href="#jpackage">RPM 
version from jpackage.org</a>:</p>
<ul>
<li>Add the <code>bin</code> directory to your path.</li>
<li>Set the <code>ANT_HOME</code> environment variable to the
directory where you installed Ant.  On some operating systems the ant
wrapper scripts can guess <code>ANT_HOME</code> (Unix dialects and
Windows NT/2000), but it is better to not rely on this behavior.</li>
<li>Optionally, set the <code>JAVA_HOME</code> environment variable
(see the <a href="#advanced">Advanced</a> section below).
This should be set to the directory where your JDK is installed.</li>
</ul>
<p><strong>Note:</strong> Do not install Ant's ant.jar file into the lib/ext
directory of the JDK/JRE. Ant is an application, whilst the extension
directory is intended for JDK extensions. In particular there are security
restrictions on the classes which may be loaded by an extension.</p>

<h3><a name="optionalTasks">Optional Tasks</a></h3>
<p>Ant supports a number of optional tasks. An optional task is a task which
typically requires an external library to function. The optional tasks are
packaged together with the core Ant tasks.</p>

<p>The external libraries required by each of the optional tasks is detailed
in the <a href="#librarydependencies">Library Dependencies</a> section. These external
libraries may either be placed in Ant's lib directory, where they will be picked up
automatically, or made available on the system CLASSPATH environment variable.
</p>

<h3>Windows and OS/2</h3>
<p>Assume Ant is installed in <code>c:\ant\</code>. The following sets up the
environment:</p>
<pre>set ANT_HOME=c:\ant
set JAVA_HOME=c:\jdk1.2.2
set PATH=%PATH%;%ANT_HOME%\bin</pre>

<h3>Unix (bash)</h3>
<p>Assume Ant is installed in <code>/usr/local/ant</code>. The following sets up
the environment:</p>
<pre>export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/local/jdk-1.2.2
export PATH=${PATH}:${ANT_HOME}/bin</pre>

<h3>Unix (csh)</h3>
<pre>setenv ANT_HOME /usr/local/ant
setenv JAVA_HOME /usr/local/jdk-1.2.2
set path=( $path $ANT_HOME/bin )</pre>

<a name="jpackage"></a>
<h3>RPM version from jpackage.org</h3>
<p>
The <a href="www.jpackage.org">JPackage project</a> distributes an RPM version of Ant.  
With this version, it is not necessary to set <code> JAVA_HOME </code>or 
<code> ANT_HOME </code>environment variables and the RPM installer will correctly
place the Ant executable on your path.  The <code> ANT_HOME </code>environment variable will
be ignored, if set, when running the JPackage version of Ant.
</p><p>
Optional jars for the JPackage version are handled in two ways.  The easiest, and
best way is to get these external libraries from JPackage if JPackage has them 
available.  (Note: for each such library, you will have to get both the external 
package itself (e.g. <code>oro-2.0.8-2jpp.noarch.rpm</code>) and the small library that links 
ant and the external package (e.g. <code>ant-apache-oro-1.6.2-3jpp.noarch.rpm</code>).
</p><p>
However, JPackage does not package proprietary software, and since some of the
optional packages depend on proprietary jars, they must be handled as follows.  
This may violate the spirit of JPackage, but it is necessary if you need these proprietary packages.
For example, suppose you want to install support for starteam, which jpackage does not 
support:
<ol>
<li>Decide where you want to deploy the extra jars.  One option is in <code>$ANT_HOME/lib</code>, 
which, for JPackage is usually <code>/usr/share/ant/lib</code>.  Another, less messy option
is to create an <code>.ant/lib</code> subdirectory of your home directory and place your 
non-jpackage ant jars there, thereby avoiding mixing jpackage
libraries with non-jpacakge stuff in the same folder.  More information on where Ant finds its libraries is available 
<a href="http://ant.apache.org/manual/running.html#libs">here</a></li>
<li>Download a non-jpackage binary distribution from the regular <a href="http://ant.apache.org/bindownload.cgi">Apache Ant site</a></li>
<li>Unzip or untar the distribution into a temporary directory</li>
<li>Copy the linking jar, in this case <code>ant-starteam.jar</code>, into the library directory you 
chose in step 1 above.</li>
<li>Copy the proprietary jar itself into the same directory.</li>
</ol>
Finally, if for some reason you are running on a system with both the JPackage and Apache versions of Ant
available, if you should want to run the Apache version (which will have to be specified with an absolute file name,
not found on the path), you should use Ant's <code>--noconfig</code> command-line switch to avoid JPackage's classpath mechanism.

<h3><a name="advanced">Advanced</a></h3>

<p>There are lots of variants that can be used to run Ant. What you need is at
least the following:</p>
<ul>
<li>The classpath for Ant must contain <code>ant.jar</code> and any jars/classes
needed for your chosen JAXP-compliant XML parser.</li>
<li>When you need JDK functionality
(such as for the <a href="CoreTasks/javac.html">javac</a> task or the
<a href="CoreTasks/rmic.html">rmic</a> task), then for JDK 1.1, the <code>classes.zip</code>
file of the JDK must be added to the classpath; for JDK 1.2 or JDK 1.3, <code>tools.jar</code>
must be added. The scripts supplied with Ant,
in the <code>bin</code> directory, will add
the required JDK classes automatically, if the <code>JAVA_HOME</code>
environment variable is set.</li>

<li>When you are executing platform-specific applications, such as the
<a href="CoreTasks/exec.html">exec</a> task or the
<a href="CoreTasks/cvs.html">cvs</a> task, the property <code>ant.home</code>
must be set to the directory containing where you installed Ant. Again
this is set by the Ant scripts to the value of the ANT_HOME environment
variable.</li>
</ul>
The supplied ant shell scripts all support an <tt>ANT_OPTS</tt>
environment variable which can be used to supply extra options
to ant. Some of the scripts also read in an extra script stored
in the users home directory, which can be used to set such options. Look
at the source for your platform's invocation script for details.

<hr>
<h2><a name="buildingant">Building Ant</a></h2>
<p>To build Ant from source, you can either install the Ant source distribution
or checkout the ant module from CVS.</p>
<p>Once you have installed the source, change into the installation
directory.</p>

<p>Set the <code>JAVA_HOME</code> environment variable
to the directory where the JDK is installed.
See <a href="#installing">Installing Ant</a>
for examples on how to do this for your operating system. </p>

<p><b>Note</b>: The bootstrap process of Ant requires a greedy
compiler like Sun's javac or jikes.  It does not work with gcj or
kjc.</b>

<p>Make sure you have downloaded any auxiliary jars required to
build tasks you are interested in. These should either be available
on the CLASSPATH or added to the <code>lib</code>
directory.
See <a href="#librarydependencies">Library Dependencies</a>
for a list of jar requirements for various features.
Note that this will make the auxiliary jars
available for the building of Ant only. For running Ant you will
still need to
make the jars available as described under
<a href="#installing">Installing Ant</a>.</p>

<p>Your are now ready to build Ant:</p>
<blockquote>
  <p><code>build -Ddist.dir=&lt;<i>directory_to_contain_Ant_distribution</i>&gt; dist</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>
  <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>
</blockquote>

<p>This will create a binary distribution of Ant in the directory you specified.</p>

<p>The above action does the following:</p>
<ul>

<li>If necessary it will bootstrap the Ant code. Bootstrapping involves the manual
compilation of enough Ant code to be able to run Ant. The bootstrapped Ant is
used for the remainder of the build steps. </li>

<li>Invokes the bootstrapped Ant with the parameters passed to the build script. In
this case, these parameters define an Ant property value and specify the &quot;dist&quot; target
in Ant's own <code>build.xml</code> file.</li>
</ul>

<p>On most occasions you will not need to explicitly bootstrap Ant since the build
scripts do that for you. If however, the build file you are using makes use of features
not yet compiled into the bootstrapped Ant, you will need to manually bootstrap.
Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX)
to build a new bootstrap version of Ant.</p>

If you wish to install the build into the current <code>ANT_HOME</code>
directory, you can use:
<blockquote>
  <p><code>build install</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>
  <p><code>build.sh install</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>
</blockquote>

You can avoid the lengthy Javadoc step, if desired, with:
<blockquote>
  <p><code>build install-lite</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Windows</i>)</p>
  <p><code>build.sh install-lite</code>&nbsp;&nbsp;&nbsp;&nbsp;(<i>Unix</i>)</p>
</blockquote>
This will only install the <code>bin</code> and <code>lib</code> directories.
<p>Both the <code>install</code> and
<code>install-lite</code> targets will overwrite
the current Ant version in <code>ANT_HOME</code>.</p>

<hr>
<h2><a name="librarydependencies">Library Dependencies</a></h2>
<p>The following libraries are needed in your CLASSPATH or in the
install directory's <code>lib</code> directory if you are using the
indicated feature. Note that only one of the regexp libraries is
needed for use with the mappers
(and Java 1.4 and higher includes a regexp implementation which
Ant will find automatically).
You will also need to install the
Ant optional jar containing the task definitions to make these
tasks available. Please refer to the <a href="#optionalTasks">
Installing Ant / Optional Tasks</a> section above.</p>

<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td><b>Jar Name</b></td>
    <td><b>Needed For</b></td>
    <td><b>Available At</b></td>
  </tr>
  <tr>
    <td>An XSL transformer like Xalan or XSL:P</td>
    <td>style task</td>
    <td>
    <b>If you use JDK 1.4, an XSL transformer is already included, so you need not do anything special.</b><br>
    <ul><li>XALAN : <a href="http://xml.apache.org/xalan-j/index.html"
    target="_top">http://xml.apache.org/xalan-j/index.html</a></li>
    <li>XSL:P : used to live at <a href="http://www.clc-marketing.com/xslp/"
    target="_top">http://www.clc-marketing.com/xslp/</a>, but the link
    doesn't work any longer and we are not aware of a replacement site.</li></ul>
    </td>
  </tr>
  <tr>
    <td>jakarta-regexp-1.3.jar</td>
    <td>regexp type with mappers</td>
    <td><a href="http://jakarta.apache.org/regexp/" target="_top">http://jakarta.apache.org/regexp/</a></td>
  </tr>
  <tr>
    <td>jakarta-oro-2.0.7.jar</td>
    <td>regexp type with mappers and the perforce tasks<br>
    To use the FTP task,
you need jakarta-oro 2.0.1 or later, and <a href="#commons-net">commons-net</a></td>
    <td><a href="http://jakarta.apache.org/oro/" target="_top">http://jakarta.apache.org/oro/</a></td>
  </tr>
  <tr>
    <td>junit.jar</td>
    <td>junit tasks</td>
    <td><a href="http://www.junit.org/" target="_top">http://www.junit.org/</a></td>
  </tr>
  <tr>
    <td>xalan.jar</td>
    <td>junitreport task</td>
    <td><a href="http://xml.apache.org/xalan-j/" target="_top">http://xml.apache.org/xalan-j/</a></td>
  </tr>
  <tr>
    <td>stylebook.jar</td>
    <td>stylebook task</td>
    <td>CVS repository of <a href="http://xml.apache.org/cvs.html" target="_top">http://xml.apache.org/cvs.html</a></td>
  </tr>
  <tr>
    <td>testlet.jar</td>
    <td><strong>deprecated</strong> test task</td>
    <td>Build from the gzip compress tar archive in <a
    href="http://avalon.apache.org/historiccvs/testlet/"
    target="_top">http://avalon.apache.org/historiccvs/testlet/</a></td>
  </tr>
  <tr>
    <td>antlr.jar</td>
    <td>antlr task</td>
    <td><a href="http://www.antlr.org/" target="_top">http://www.antlr.org/</a></td>
  </tr>
  <tr>
    <td >bsf.jar</td>
    <td>script task<br>
    <strong>Note</strong>: Ant 1.6 and later require Apache BSF, not
    the IBM version.  I.e. you need BSF 2.3.0-rc1 or later.</td>
    <td><a href="http://jakarta.apache.org/bsf/" target="_top">http://jakarta.apache.org/bsf/</a></td>
  </tr>
  <tr>
    <td>Groovy jars</td>
    <td>Groovy with script and scriptdef tasks<br>
      You need to get the groovy jar and two asm jars from a groovy
      installation. The jars are groovy-[version].jar, asm-[vesion].jar and
      asm-util-[version].jar. As of groovy version 1.0-beta-7, the jars are
      groovy-1.0-beta-7.jar, asm-1.4.3.jar and asm-util-1.4.3.jar.
    </td>
    <td>
      <a href="http://groovy.codehaus.org/">http://groovy.codehaus.org/</a>
      <br>
      The asm jars are also available from the creators of asm -
      <a href="http://asm.objectweb.org/">http://asm.objectweb.org/</a>
    </td>
  </tr>
  <tr>
    <td>netrexx.jar</td>
    <td>netrexx task, Rexx with the script task</td>
    <td><a href="http://www2.hursley.ibm.com/netrexx/" target="_top">
        http://www2.hursley.ibm.com/netrexx/</a></td>
  </tr>
  <tr>
    <td>js.jar</td>
    <td>Javascript with script task<br>
    If you use Apache BSF 2.3.0-rc1, you must use rhino 1.5R3 (later
    versions of BSF work with 1.5R4 as well).</td>
    <td><a href="http://www.mozilla.org/rhino/" target="_top">http://www.mozilla.org/rhino/</a></td>
  </tr>
  <tr>
    <td>jython.jar</td>
    <td>Python with script task<br>
    Warning : jython.jar also contains classes from jakarta-oro.
    Remove these classes if you are also using jakarta-oro.</td>
    <td><a href="http://jython.sourceforge.net/" target="_top">http://jython.sourceforge.net/</a></td>
  </tr>
  <tr>
    <td>jpython.jar</td>
    <td>Python with script task <b>deprecated, jython is the prefered engine</b></td>
    <td><a href="http://www.jpython.org/" target="_top">http://www.jpython.org/</a></td>
  </tr>
  <tr>
    <td>jacl.jar and tcljava.jar</td>
    <td>TCL with script task</td>
    <td><a href="http://www.scriptics.com/software/java/" target="_top">http://www.scriptics.com/software/java/</a></td>
  </tr>
  <tr>
    <td>BeanShell JAR(s)</td>
    <td>BeanShell with script task.
      <br>
    <strong>Note</strong>: Ant 1.6 and later require BeanShell version 1.3 or
      later</td>
    <td><a href="http://www.beanshell.org/" target="_top">http://www.beanshell.org/</a></td>
  </tr>
  <tr>
    <td>jruby.jar</td>
    <td>Ruby with script task</td>
    <td><a href="http://jruby.sourceforge.net/" target="_top">http://jruby.sourceforge.net/</a></td>
  </tr>
  <tr>
    <td>judo.jar</td>
    <td>Judoscript with script task</td>
    <td><a href="http://www.judoscript.com/index.html" target="_top">http://www.judoscript.com/index.html</a></td>
  </tr>
  <tr>
    <td>commons-logging.jar</td>
    <td>CommonsLoggingListener</td>
    <td><a href="http://jakarta.apache.org/commons/logging/index.html"
           target="_top">http://jakarta.apache.org/commons/logging/index.html</a></td>
  </tr>
  <tr>
    <td>log4j.jar</td>
    <td>Log4jListener</td>
    <td><a href="http://jakarta.apache.org/log4j/docs/index.html"
           target="_top">http://jakarta.apache.org/log4j/docs/index.html</a></td>
  </tr>
  <tr>
    <td><a name="commons-net">commons-net.jar</td>
    <td>ftp, rexec and telnet tasks<br>
    jakarta-oro 2.0.1 or later is required in any case together with commons-net.<br>
    For all users, a minimum version of commons-net of 1.4.0 is recommended.  Earlier 
    versions did not support the full range of configuration options, and 1.4.0 is needed
    to compile Ant.
    </td>
    <td><a href="http://jakarta.apache.org/commons/net/index.html"
           target="_top">http://jakarta.apache.org/commons/net/index.html</a></td>
  </tr>
  <tr>
    <td>bcel.jar</td>
    <td>classfileset data type,
        JavaClassHelper used by the ClassConstants filter reader and
        optionally used by ejbjar for dependency determination
    </td>
    <td><a href="http://jakarta.apache.org/bcel/" target="_top">http://jakarta.apache.org/bcel/</a></td>
  </tr>
  <tr>
    <td>mail.jar</td>
    <td>Mail task with Mime encoding, and the MimeMail task</td>
    <td><a href="http://java.sun.com/products/javamail/"
        target="_top">http://java.sun.com/products/javamail/</a></td>
  </tr>
  <tr>
    <td>jsse.jar</td>
    <td>
Support for SMTP over TLS/SSL <br>
in the Mail task<br>
Already included in jdk 1.4</td>
    <td><a href="http://java.sun.com/products/jsse/"
        target="_top">http://java.sun.com/products/jsse/</a></td>
  </tr>
  <tr>
    <td>activation.jar</td>
    <td>Mail task with Mime encoding, and the MimeMail task</td>
    <td><a href="http://java.sun.com/products/javabeans/glasgow/jaf.html"
        target="_top">http://java.sun.com/products/javabeans/glasgow/jaf.html</a></td>
  </tr>
  <tr>
    <td>jdepend.jar</td>
    <td>jdepend task</td>
    <td><a href="http://www.clarkware.com/software/JDepend.html"
        target="_top">http://www.clarkware.com/software/JDepend.html</a></td>
  </tr>
  <tr>
    <td>resolver.jar <b>1.1beta or later</b></td>
    <td>xmlcatalog datatype <em>only if support for external catalog files is desired</em></td>
    <td><a href="http://xml.apache.org/commons/"
    target="_top">http://xml.apache.org/commons/</a>.</td>
  </tr>
  <tr>
    <td>jsch.jar</td>
    <td>sshexec and scp tasks</td>
    <td><a href="http://www.jcraft.com/jsch/index.html"
        target="_top">http://www.jcraft.com/jsch/index.html</a></td>
  </tr>
  <tr>
    <td>JAI - Java Advanced Imaging</td>
    <td>image task</td>
    <td><a href="http://java.sun.com/products/java-media/jai/"
        target="_top">http://java.sun.com/products/java-media/jai/</a></td>
  </tr>
  <tr>
    <td>IContract</td>
    <td>icontract task<br>
    Warning : the icontract jar file contains also antlr classes.<br>
    To make the antlr task work properly, remove antlr/ANTLRGrammarParseBehavior.class
    from the icontract jar file installed under $ANT_HOME/lib.</td>
    <td><a href="http://www.reliable-systems.com/tools/"
    target="_top">http://www.reliable-systems.com/tools/</a></td>
  </tr>
</table>
<br>
<hr>
<p align="center">Copyright &copy; 2000-2005 The Apache Software Foundation. All rights
Reserved.</p>

</body>
</html>