| <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> |
| Both the binary and source distributions of Ant include the reference |
| implementation of JAXP 1.0. 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>parser.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 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=<<i>directory_to_contain_Ant_distribution</i>> dist</code> (<i>Windows</i>)</p> |
| <p><code>build.sh -Ddist.dir=<<i>directory_to_contain_Ant_distribution</i>> dist</code> (<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 "dist" 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> (<i>Windows</i>)</p> |
| <p><code>build.sh install</code> (<i>Unix</i>)</p> |
| </blockquote> |
| |
| You can avoid the lengthy Javadoc step, if desired, with: |
| <blockquote> |
| <p><code>build install-lite</code> (<i>Windows</i>)</p> |
| <p><code>build.sh install-lite</code> (<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><project></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> |
| <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 © 2000,2001 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
| |