youys
/
ant

<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Ant User Manual</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 can be downloaded from <a
href="http://jakarta.apache.org/builds/ant/release/v1.3/bin/">
http://jakarta.apache.org/builds/ant/release/v1.3/bin/</a>.

If you like living on the edge, you can download the latest version from <a
href="http://jakarta.apache.org/builds/ant/nightly/">http://jakarta.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://jakarta.apache.org/builds/ant/release/v1.3/src/">
http://jakarta.apache.org/builds/ant/release/v1.3/src/</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 
jakarta-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://jakarta.apache.org/cvsweb/index.cgi/jakarta-ant/" target="_top">
Ant CVS repository</a> on-line. </p>

<hr>
<h2><a name="sysrequirements">System Requirements</a></h2>
<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 reference 
implementation of JAXP 1.1. Please see 
<a href="http://java.sun.com/xml/" target="_top">http://java.sun.com/xml/</a> 
for more information. 
If you wish to use a different JAXP-compliant parser, you should remove
<code>jaxp.jar</code> and <code>crimson.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.1 or later. A future version of Ant will require
JDK 1.2 or later.
</p>
  
<hr>
<h2><a name="installing">Installing Ant</a></h2>
<p>The binary distribution of Ant consists of three directories:
<code>bin</code>,
<code>docs</code> and
<code>lib</code>

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. 

Before you can run ant there is some additional set up you 
will need to do:</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.</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>
<li>If you are using Ant's optional tasks then you may need to add additional
jars to your <code>lib</code> directory or to your CLASSPATH.
See <a href="#librarydependencies">Library Dependencies</a>
for for a list of jar requirements for various optional tasks.
</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>Windows</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><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>

<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 jakarta-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>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/optional</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.
</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="running">Running Ant</a></h2>
<p>Running Ant is simple, when you installed it as described in the previous
section. Just type <code>ant</code>.</p>
<p>When nothing is specified, Ant looks for a <code>build.xml</code>
file in the current directory. If found, it uses that file as the
buildfile. If you use the <code>-find</code> option,
Ant will search for a buildfile in 
the parent directory, and so on, until the root of the filesystem 
has been reached. To make Ant use
another buildfile, use the command-line
option <code>-buildfile <i>file</i></code>,
where <i>file</i> is the buildfile you want to use.</p>

<p>You can also set properties that override properties specified in the
buildfile (see the <a href="CoreTasks/property.html">property</a> task). 
This can be done with
the <nobr><code>-D<i>property</i>=<i>value</i></code></nobr> option,
where <i>property</i> is the name of the property,
and <i>value</i> is the value for that property.
This can also be used to pass in the value of some environment variables.
You can also access environment variables using the <a href="CoreTasks/property.html">
property</a> task.

Just pass <nobr><code>-DMYVAR=%MYVAR%</code></nobr> (Windows) or
<nobr><code>-DMYVAR=$MYVAR</code></nobr> (Unix)
to Ant - you can then access
these variables inside your buildfile as <code>${MYVAR}</code>.</p>

<p>Two more options are: <nobr><code>-quiet</code></nobr>,
which instructs Ant to print less
information on the console when running, and
<nobr><code>-verbose</code></nobr>, which causes Ant to print
additional information to the console.</p>

<p>It is also possible to specify one or more targets that should be executed.
When omitted, the target that is specified in the
<code>default</code> attribute of the <code>&lt;project&gt;</code> tag is
used.</p>

<p>The <nobr><code>-projecthelp</code></nobr>
option gives a list of this project's
targets. First those with a description, then those without one.</p>

<p>Command-line option summary:</p>
<pre>ant [options] [target [target2 [target3] ...]]
Options:
-help                  print this message
-projecthelp           print project help information
-version               print the version information and exit
-quiet                 be extra quiet
-verbose               be extra verbose
-debug                 print debugging information
-emacs                 produce logging information without adornments
-logfile <i>file</i>          use given file for log output
-logger <i>classname</i>      the class that is to perform logging
-listener <i>classname</i>    add an instance of class as a project listener
-buildfile <i>file</i>        use specified buildfile
-find <i>file</i>             search for buildfile towards the root of the filesystem and use the first one found
-D<i>property</i>=<i>value</i>       set <i>property</i> to <i>value</i>
</pre>
<h3>Examples</h3>
<blockquote>
  <pre>ant</pre>
</blockquote>
<p>runs Ant using the <code>build.xml</code> file in the current directory, on
the default target.</p>
<blockquote>
  <pre>ant -buildfile test.xml</pre>
</blockquote>
<p>runs Ant using the <code>test.xml</code> file in the current directory, on
the default target.</p>
<blockquote>
  <pre>ant -buildfile test.xml dist</pre>
</blockquote>
<p>runs Ant using the <code>test.xml</code> file in the current directory, on a
target called <code>dist</code>.</p>
<blockquote>
  <pre>ant -buildfile test.xml -Dbuild=build/classes dist</pre>
</blockquote>
<p>runs Ant using the <code>test.xml</code> file in the current directory, on a
target called <code>dist</code>, setting the <code>build</code> property to the
value <code>build/classes</code>.</p>

<h3>Running Ant by Hand</h3>
<p>If you have installed Ant in the do-it-yourself way, Ant can be started
with:</p>
<blockquote>
  <pre>java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre>
</blockquote>

<p>These instructions actually do exactly the same as the <code>ant</code>
command. The options and target are the same as when running Ant with the <code>ant</code>
command. This example assumes you have set your classpath to include:</p>
<ul>
<li><code>ant.jar</code></li>
<li>jars/classes for your XML parser</li>
<li>the JDK's required jar/zip files</li>
</ul>
<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.</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>jakarta-regexp-1.2.jar</td>
    <td>regexp type with mappers</td>
    <td><a href="http://jakarta.apache.org/regexp/" target="_top">jakarta.apache.org/regexp/</a></td>
  </tr>
  <tr>
    <td>jakarta-oro-2.0.1.jar</td>
    <td>regexp type with mappers and the perforce tasks</td>
    <td><a href="http://jakarta.apache.org/oro/" target="_top">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">www.junit.org</a></td>
  </tr>
  <tr>
    <td>stylebook.jar</td>
    <td>stylebook task</td>
    <td>CVS repository of <a href="http://xml.apache.org" target="_top">xml.apache.org</a></td>
  </tr>
  <tr>
    <td>testlet.jar</td>
    <td>test task</td>
    <td><a href="http://java.apache.org/framework" target="_top">java.apache.org/framework</a></td>
  </tr>
  <tr>
    <td>antlr.jar</td>
    <td>antlr task</td>
    <td><a href="http://www.antlr.org/" target="_top">www.antlr.org</a></td>
  </tr>
  <tr>
    <td >bsf.jar</td>
    <td>script task</td>
    <td><a href="http://oss.software.ibm.com/developerworks/projects/bsf" target="_top">
        oss.software.ibm.com/developerworks/projects/bsf</a></td>
  </tr>
  <tr>
    <td>netrexx.jar</td>
    <td>netrexx task</td>
    <td><a href="http://www2.hursley.ibm.com/netrexx" target="_top">
        www2.hursley.ibm.com/netrexx</a></td>
  </tr>
  <tr>
    <td>rhino.jar</td>
    <td>javascript with script task</td>
    <td><a href="http://www.mozilla.org/" target="_top">www.mozilla.org</a></td>
  </tr>
  <tr>
    <td>jpython.jar</td>
    <td>python with script task</td>
    <td><a href="http://www.jpython.org/" target="_top">www.jpython.org</a></td>
  </tr>
  <tr>
    <td>netcomponents.jar</td>
    <td>ftp and telnet tasks</td>
    <td><a href="http://www.savarese.org/oro/downloads/index.html#NetComponents"
           target="_top">www.savarese.org/oro/downloads</a></td>
  </tr>
</table>
<br>
<hr>
<p align="center">Copyright &copy; 2000,2001 Apache Software Foundation. All rights
Reserved.</p>

</body>
</html>