You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by co...@apache.org on 2001/02/08 15:48:46 UTC
cvs commit: jakarta-ant/docs/manual install.html
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>