conor 01/02/08 06:48:45
Modified: docs/manual Tag: ANT_13_BRANCH install.html Log: Update build and installation instructions Revision Changes Path No revision No revision 1.1.2.2 +94 -50 jakarta-ant/docs/manual/Attic/install.html Index: install.html =================================================================== RCS file: /home/cvs/jakarta-ant/docs/manual/Attic/install.html,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -r1.1.2.1 -r1.1.2.2 --- install.html 2001/02/08 13:36:14 1.1.2.1 +++ install.html 2001/02/08 14:48:43 1.1.2.2 @@ -22,31 +22,43 @@ <p>The latest stable version of Ant can be downloaded from <a href="http://jakarta.apache.org/builds/ant/release/v1.2/bin/";> http://jakarta.apache.org/builds/ant/release/v1.2/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.2/src/";> -http://jakarta.apache.org/builds/ant/release/v1.2/src/</a>. Again, if you prefer the edge, you can access +http://jakarta.apache.org/builds/ant/release/v1.2/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> +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. +To build and use Ant, you must have a JAXP-compliant XML parser installed and +available on your classpath. <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. +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/core</code> directory. +from Ant's <code>lib</code> directory. + You can then either put the jars from your preferred parser into Ant's -<code>lib/core</code> directory or put the jars on the system classpath. +<code>lib</code> directory or put the jars on the system classpath. + <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 @@ -55,34 +67,46 @@ <hr> <h2><a name="installing">Installing Ant</a></h2> -<p>The binary distribution of Ant consists of four directories: +<p>The binary distribution of Ant consists of three directories: <code>bin</code>, -<code>docs</code>, -<code>lib</code> and -<code>src</code>. Only the <code>bin</code> -and <code>lib</code> directories are required for running Ant. To run Ant, the -following must be done:</p> +<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: <ul> <li>Add the <code>bin</code> directory to your path.</li> -<li>Set the <code>ANT_HOME</code> environment variable. -This should be set to the directory -that contains the <code>bin</code> and <code>lib</code> directories.</li> -<li>(Optionally) Set the <code>JAVA_HOME</code> environment variable. +<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 the JDK is installed.</li> +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. + <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> + <a name="advanced"> <h3>Advanced</h3> </a> @@ -99,40 +123,59 @@ in the <code>bin</code> directory, will add the required JDK classes automatically, if the <code>JAVA_HOME</code> environment variable is set.</p> -<p>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 -the <code>antRun</code> shell script necessary to run exec's on Unix.</p> + +<p>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. </blockquote> + + <hr> <h2><a name="buildingant">Building Ant</a></h2> -<p>To build Ant, you should install the Ant source distribution. -While the binary distribution -includes the Ant source code, it is intended for reference purposes only. -The bootstrap and build scripts used to build Ant itself are not included -in the binary distribution. -<p> -<p>Once you have installed the source distribution, go to the -<code>jakarta-ant</code> directory.</p> +<p>To build Ant from source, you can either install the Ant source distribution +or checkout the jakarta-ant module from CVS. +<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 auxilliary jars required to build tasks you are interested in. These should either be available -on the classpath or added to Ant's <code>lib</code> +on the classpath or added to <code>lib/optional</code> directory. The list of auxilliary tasks and requirements is in <code>lib/README</code>.</p> -<p>Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX) -to build a bootstrap version of Ant.</p> -<p>When finished, use:</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>to create a binary distribution of Ant. This distribution can be -found in the directory you specified.</p> + +<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>Invokes the bootstrapped Ant with the parameters passed to the build script. In +this case, these paramaters 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: @@ -143,12 +186,12 @@ You can avoid the lengthy Javadoc step, if desired, with: <blockquote> - <p><code>build mininstall</code> (<i>Windows</i>)</p> - <p><code>build.sh mininstall</code> (<i>Unix</i>)</p> + <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>mininstall</code> targets will overwrite +<code>install-lite</code> targets will overwrite the current Ant version in <code>ANT_HOME</code>. <hr> @@ -164,30 +207,37 @@ 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">property</a> task). +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 have access to your environment variables -(and is the only way, since Java cannot access them). +This can also be used to pass in the value of some environment variables. +You can also access environment valiables 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: @@ -244,12 +294,6 @@ <li>the JDK's required jar/zip files </ul> <hr> -<p align="center">Copyright © 2000,2001 Apache Software Foundation. All rights -Reserved.</p> - -</body> -</html> - <p align="center">Copyright © 2000,2001 Apache Software Foundation. All rights Reserved.</p>
