summaryrefslogtreecommitdiffstats
path: root/framework/src/ant/apache-ant-1.9.6/manual/install.html
diff options
context:
space:
mode:
authorAshlee Young <ashlee@onosfw.com>2015-10-23 10:00:02 -0700
committerAshlee Young <ashlee@onosfw.com>2015-10-23 10:00:02 -0700
commit753a6c60f47f3ac4f270005b65e9d6481de8eb68 (patch)
tree3d0a1ae3b4d994550f6614b417b991eee3eb8911 /framework/src/ant/apache-ant-1.9.6/manual/install.html
parentc62d20eb3b4620c06d833be06f50b2600d96dd42 (diff)
Adding maven and ant source trees
Change-Id: I0a39b9add833a31b9c3f98d193983ae2f3a5a445 Signed-off-by: Ashlee Young <ashlee@onosfw.com>
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/install.html')
-rw-r--r--framework/src/ant/apache-ant-1.9.6/manual/install.html1096
1 files changed, 1096 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/install.html b/framework/src/ant/apache-ant-1.9.6/manual/install.html
new file mode 100644
index 00000000..818b168d
--- /dev/null
+++ b/framework/src/ant/apache-ant-1.9.6/manual/install.html
@@ -0,0 +1,1096 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<html>
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
+<title>Installing Apache Ant</title>
+</head>
+
+<body>
+<h1>Installing Apache Ant</h1>
+<h2><a name="getting">Getting Apache Ant</a></h2>
+
+<h3>The Short Story</h3>
+<p>To get up and running with the binary edition of Ant quickly, follow these steps:
+<ol>
+<li>Make sure you have a Java environment installed, See <a href="#sysrequirements">System
+Requirements</a> for details.</li>
+<li>Download Ant. See <a href="#getBinary">Binary Edition</a> for details.</li>
+<li>Uncompress the downloaded file into a directory.</li>
+<li>Set environmental variables <code>JAVA_HOME</code> to your Java environment, <code>ANT_HOME</code> to
+the directory you uncompressed Ant to, and add <code>${ANT_HOME}/bin</code> (Unix) or
+<code>%ANT_HOME%/bin</code> (Windows) to your <code>PATH</code>. See <a href="#setup">Setup</a> for details.</li>
+<li>Optionally, from the <code>ANT_HOME</code> directory run <code>ant -f fetch.xml -Ddest=system</code> to get
+the library dependencies of most of the Ant tasks that require them. If you don't do this, many of the dependent
+Ant tasks will not be available. See <a href="#optionalTasks">Optional Tasks</a> for details and other options
+for the -Ddest parameter.</li>
+<li>Optionally, add any desired Antlibs. See <a href="http://ant.apache.org/antlibs/proper.html" target="_top">Ant Libraries</a> for a list.
+</ol>
+</p>
+<p>
+Note that the links in the list above will give more details about each of the steps,
+should you need them. Or you can just continue reading the rest of this document.
+</p>
+The short story for working with the Ant source code (not needed if you are working with the binary edition) is:
+<ol>
+<li>Get the source code. See <a href="#sourceEdition">Source Edition</a> for details.</li>
+<li> Build Ant. See <a href="#buildingant">Building Ant</a> for details.</li>
+</ol>
+<p>
+</p>
+<p>
+For the full story, continue reading.
+</p>
+
+<h3><a name="getBinary">Binary Edition</a></h3>
+
+<p>The latest stable version of Ant is available from the Ant web page <a
+href="http://ant.apache.org/" target="_top">http://ant.apache.org/</a>
+</p>
+
+<p>The binary edition of Ant is shipped with 3 different compression formats:
+<ol>
+<li><b>.zip</b> - Recommended compression format for Windows, can also be used on other platforms. Supported
+by many programs and some operating systems natively.</li>
+<li><b>.tar.gz</b> - Uses the tar program to gather files together, and gzip to compress and uncompress.</li>
+<li><b>.tar.bz2</b> - Uses the tar program to gather files together, and bzip2 to compress and uncompress..</li>
+</ol>
+Choose the format that is best supported for your platform.
+</p>
+
+<h3>As a binary in an RPM Package</h3>
+
+<p>Consult the <a href="#jpackage">jpackage</a> section below.</p>
+
+<h3>Bundled in IDEs</h3>
+<p>
+ All the main Java IDEs ship with Ant, products such as Eclipse, NetBeans
+ and IntelliJ IDEA. If you install Ant this way you usually get the most recent
+ release of Ant at the time the IDE was released. Some of the IDEs (Eclipse
+ and NetBeans in particular) ship with extra tasks that only work if
+ IDE-specific tools are on Ant's path. To use these on command-line versions
+ of Ant, the relevant JARs need to be added to the command-line Ant as
+ extra libraries/tasks. Note that if it is an IDE task or extension that is
+ not behaving, the Ant team is unable to field bug reports. Try the IDE mailing
+ lists first, who will cross-file bugs if appropriate.
+</p>
+<p>
+ IDE's can invariably be pointed at different Ant installations. This lets
+ developers upgrade to a new release of Ant, and eliminate inconsistencies
+ between command-line and IDE Ant.
+</p>
+
+<h3>Bundled in Java applications</h3>
+
+<p>
+ Many Java applications, most particularly application servers, ship with
+ a version of Ant. These are primarily for internal use by the application,
+ using the Java APIs to delegate tasks such as JSP page compilation to the Ant
+ runtime. Such distributions are usually unsupported by everyone. Particularly
+ troublesome are those products that not only ship with their own Ant release,
+ they add their own version of ANT.BAT or ant.sh to the PATH. If Ant starts
+ behaving weirdly after installing something, try the
+ <a href="#diagnostics">diagnostics</a> advice.
+</p>
+
+<h3><a name="sourceEdition">Source Edition</a></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" target="_top">http://ant.apache.org/srcdownload.cgi</a>.
+
+If you prefer the leading-edge code, you can access
+the code as it is being developed via git. The Ant website has details on
+<a href="http://ant.apache.org/git.html" target="_top">accessing git</a>.
+All bug fixes will go in against the HEAD of the source tree, and the first
+response to many bugreps will be "have you tried the latest version".
+Don't be afraid to download and build a prererelease edition, as everything
+other than new features are usually stable.
+ </p>
+<p>
+
+
+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="https://git-wip-us.apache.org/repos/asf?p=ant.git;a=summary" target="_top">
+Ant SVN repository</a> on-line. </p>
+
+<h3 name="archives">Archive Download Area Layout</h3>
+<p>
+Older versions of Ant are available in the archives at <a
+href="http://archive.apache.org/dist/ant/" target="_top">http://archive.apache.org/dist/ant/</a>. The
+files are organized as follows.
+</p>
+<table>
+<tr>
+ <th>Filename or Path</th>
+ <th>Description</th>
+</tr>
+<tr>
+ <td>KEYS</td>
+ <td>PGP-Keysfile. It contains the PGP-keys of Ant developers so you can 'trust' the distribution. </td>
+</tr>
+<tr>
+ <td>RELEASE-NOTES-{version}.html</td>
+ <td>
+ Release notes of the given version in HTML format. When upgrading your Ant installation you
+ should have a look at the <i>Changes that could break older environments</i> section.
+ </td>
+</tr>
+<tr>
+ <td>ant-current-bin.zip</td>
+ <td>
+ ZIP-Archive containing the compiled version of Ant in the last released version. It is recommended that
+ you do not download the latest version this way, as the standard way of downloading described above will
+ redirect you to a mirror closer to you, thus making the download faster for you and reducing the load
+ on Apache servers.
+ </td>
+</tr>
+<tr>
+ <td>ant-current-src.zip</td>
+ <td>
+ ZIP-Archive containing the sources of Ant. If you have this you could compile Ant itself.
+ If you do not have the <i>required</i> dependencies, the classes depending on them are just not
+ built. Again, it is preferred to use the standard way of getting the source package described above
+ to make your download quicker and to reduce the load on Apache servers.
+ </td>
+</tr>
+<tr>
+ <td>ant-current-*.asc</td>
+ <td>
+ Security file for checking the correctness of the zip file. This one is the
+ <a href="http://en.wikipedia.org/wiki/Pretty_Good_Privacy" target="_blank">PGP</a> key.
+ </td>
+</tr>
+<tr>
+ <td>ant-current-*.md5</td>
+ <td>
+ Security file for checking the correctness of the zip file. This one is the
+ <a href="http://en.wikipedia.org/wiki/Md5" target="_blank">MD5</a> key.
+ </td>
+</tr>
+<tr>
+ <td>ant-current-*.sha1</td>
+ <td>
+ Security file for checking the correctness of the zip file. This one is the
+ <a href="http://en.wikipedia.org/wiki/SHA-1" target="_blank">SHA1</a> key.
+ </td>
+</tr>
+<tr>
+ <td>antlibs/</td>
+ <td>
+ This directory holds the Antlibs that are made of available by the Apache Ant project.
+ Antlibs are bundles of Ant tasks that are not delivered as part of the Ant core but are
+ available as optional downloads.
+ </td>
+</tr>
+<tr>
+ <td>binaries/</td>
+ <td>
+ The binaries directory holds specific Ant releases bundled in both ZIP and tar.gz compression
+ formats. The named releases are in contrast to the ant-current-bin.zip file in the parent
+ directory, which is always guaranteed to be the most current release of Ant.
+ </td>
+</tr>
+<tr>
+ <td>common/</td>
+ <td>
+ The common directory holds various files, such as the Apache License file that Ant is licensed
+ under, that people may wish to examine without having to download the whole Ant distribution.
+ </td>
+</tr>
+<tr>
+ <td>source/</td>
+ <td>
+ The source directory holds the source code for specific Ant releases bundled in both ZIP and
+ tar.gz compression formats. The named releases are in contrast to the ant-current-src.zip file
+ in the parent directory, which is always guaranteed to hold the source code for the most current
+ release of Ant.
+ </td>
+</tr>
+</table>
+
+<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 NT-platforms, OS/2 Warp, Novell Netware 6, OpenVMS and MacOS X.
+The platforms used most for development are, in no particular order,
+Linux, MacOS X, Windows XP and Unix; these are therefore that platforms
+that tend to work best. As of Ant1.7, Windows 9x is no longer supported.
+
+<p>
+For the current version of Ant, you will also need a JDK installed on
+your system, version 1.4 or later required, 1.7 or later strongly recommended.
+The more up-to-date the version of Java , the more Ant tasks you get.
+</p>
+<p>
+ <strong>Note: </strong>If a JDK is not present, only the JRE runtime, then many tasks will not work.
+</p>
+<p>
+ <strong>Note: </strong>
+ Ant 1.8.* works with jdk1.4 and higher, Ant 1.7.* works with jdk1.3 and higher, Ant 1.6.* works with jdk 1.2 and higher,
+ Ant 1.2 to Ant 1.5.* work with jdk 1.1 and higher.
+</p>
+
+<h3>Open Source Java Runtimes</h3>
+<p>
+ The Ant team strongly supports users running Ant on <a target="_blank" href="http://openjdk.java.net/">OpenJDK</a> and other
+ open source Java runtimes, and so strives to have a product that works
+ well on those platforms.
+</p>
+<hr>
+<h2><a name="installing">Installing Ant</a></h2>
+<p>The binary distribution of Ant consists of the following directory layout:
+<pre>
+ ant
+ +--- README, LICENSE, fetch.xml, other text files. //basic information
+ +--- bin // contains launcher scripts
+ |
+ +--- lib // contains Ant jars plus necessary dependencies
+ |
+ +--- docs // contains documentation
+ | |
+ | +--- 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
+files 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>
+Note that current releases of Ant no longer support these systems. If you are using an older
+version of Ant, however, 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 launch 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><a name="setup">Setup</a></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, Ant's
+startup 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>Operating System-specific instructions for doing this from the command
+line are in the <a href="#windows">Windows</a>, <a href="#bash">Linux/Unix (bash)</a>,
+and <a href="#tcshcsh">Linux/Unix (csh)</a> sections. Note that using this method,
+the settings will only be valid for the command line session you run them in.</p>
+<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>
+
+<table width="80%">
+<tr>
+ <td colspan="2">
+ <b>Windows Note:</b>
+ </td>
+</tr>
+<tr>
+ <td width="5%">&nbsp;</td>
+ <td>
+ The ant.bat script makes use of three environment variables -
+ ANT_HOME, CLASSPATH and JAVA_HOME. <b>Ensure</b> that ANT_HOME and JAVA_HOME variables are set,
+ and that they do <b><u>not</u></b> have quotes (either
+ ' or &quot;) and they do <b><u>not</u></b> end with \ or with /. CLASSPATH should be unset or
+ empty.
+ </td>
+</tr>
+</table>
+
+<h3><a name="checkInstallation">Check Installation</a></h3>
+<p>You can check the basic installation with opening a new shell and typing <tt>ant</tt>. You
+should get a message like this
+<pre>
+Buildfile: build.xml does not exist!
+Build failed
+</pre>
+So Ant works. This message is there because you need to write an individual buildfile for your
+project. With a <tt>ant -version</tt> you should get an output like
+<pre>
+Apache Ant(TM) version 1.9.2 compiled on July 8 2013
+</pre>
+</p>
+<p>If this does not work ensure your environment variables are set right. They must resolve to:
+<ul>
+ <li>required: %ANT_HOME%\bin\ant.bat</li>
+ <li>optional: %JAVA_HOME%\bin\java.exe</li>
+ <li>required: %PATH%=...<i>maybe-other-entries</i>...;%ANT_HOME%\bin;...<i>maybe-other-entries</i>...</li>
+</ul>
+<b>ANT_HOME</b> is used by the launcher script for finding the libraries.
+<b>JAVA_HOME</b> is used by the launcher for finding the JDK/JRE to use. (JDK is recommended as some tasks
+require the java tools.) If not set, the launcher tries to find one via the %PATH% environment variable.
+<b>PATH</b> is set for user convenience. With that set you can just start <i>ant</i> instead of always typing
+<i>the/complete/path/to/your/ant/installation/bin/ant</i>.
+</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 must be added to Ant's classpath, in any of the following ways:
+</p>
+<ul>
+ <li><p>
+ In <code><i>ANT_HOME</i>/lib</code>. This makes the JAR files available to all
+ Ant users and builds.
+ </p></li>
+
+ <li><p>
+ In <code>${user.home}/.ant/lib</code> (as of Ant 1.6). This
+ allows different users to add new libraries to Ant. All JAR files
+ added to this directory are available to command-line Ant.
+ </p></li>
+
+ <li><p>
+ On the command line with a <code>-lib</code> parameter. This lets
+ you add new JAR files on a case-by-case basis.
+ </p></li>
+
+ <li><p>
+ In the <code>CLASSPATH</code> environment variable. Avoid this; it makes
+ the JAR files visible to <i>all</i> Java applications, and causes
+ no end of support calls. See <a href="#classpath">below</a> for details.
+ </p>
+ </li>
+
+ <li><p>
+ In some <code>&lt;classpath&gt;</code> accepted by the task itself.
+ For example, as of Ant 1.7.0 you can run the <code>&lt;junit&gt;</code>
+ task without <code>junit.jar</code> in Ant's own classpath, so long as
+ it is included (along with your program and tests) in the classpath
+ passed when running the task.
+ </p><p>
+ Where possible, this option is generally
+ to be preferred, as the Ant script itself can determine the best path
+ to load the library from: via relative path from the basedir (if you
+ keep the library under version control with your project), according
+ to Ant properties, environment variables, Ivy downloads, whatever you like.
+ </p></li>
+
+</ul>
+
+<p>
+ If you are using the binary version of Ant, or if you are working from source
+ code, you can easily gather most of the dependencies and install them for use
+ with your Ant tasks. In your <code>ANT_HOME</code> directory you should see a
+ file called <code>fetch.xml</code>. This is an Ant script that you can run to
+ install almost all the dependencies the optional Ant tasks need.
+</p>
+
+<p>
+ To do so, change to the <code>ANT_HOME</code> directory and execute the command:
+</p>
+
+<blockquote>
+ <pre>ant -f fetch.xml -Ddest=<i>[option]</i></pre>
+</blockquote>
+
+<p>
+ where option is one of the following, as described above:
+ <ul>
+ <li><code>system</code> - store in Ant's lib directory <i>(Recommended)</i></li>
+ <li><code>user</code> - store in the user's home directory</li>
+ <li><code>optional</code> - store in Ant's source code lib/optional directory, used if building Ant source code</li>
+ </ul>
+</p>
+
+<p>
+ You may also need to set proxy settings. See the <a href="#proxy">Proxy Settings</a> section for details.
+</p>
+
+<p>
+Note that not all dependencies are gathered using <code>fetch.xml</code>. Tasks that depend on
+commercial software, in particular, will require you to have the commercial software installed
+in order to be used.
+</p>
+
+<p>The Apache Ant Project also provides additional tasks and types that are available as separately
+downloaded Ant Libraries. You can see the the list of available Antlibs at
+the <a href="http://ant.apache.org/antlibs/proper.html" target="_top">Ant Libraries</a> page.
+</p>
+
+<p>You can also find tasks and types provided by third-party projects at the
+<a href="http://ant.apache.org/external.html" target="_top">External Tools and Tasks</a> page.
+</p>
+
+<p>
+ IDEs have different ways of adding external JAR files and third-party tasks
+ to Ant. Usually it is done by some configuration dialog. Sometimes JAR files
+ added to a project are automatically added to ant's classpath.
+</p>
+
+<h3><a name="classpath">The <code>CLASSPATH</code> environment variable</a></h3>
+<p>
+
+The <code>CLASSPATH</code> environment variable is a source of many Ant support queries. As
+the round trip time for diagnosis on the Ant user mailing list can be slow, and
+because filing bug reports complaining about 'ant.bat' not working will be
+rejected by the developers as WORKSFORME "this is a configuration problem, not a
+bug", you can save yourself a lot of time and frustration by following some
+simple steps.
+
+</p>
+<ol>
+
+<li>Do not ever set <code>CLASSPATH</code>. Ant does not need it, it only causes confusion
+and breaks things.
+
+</li>
+
+<li>If you ignore the previous rule, do not ever, ever, put quotes in the
+<code>CLASSPATH</code>, even if there is a space in a directory. This will break Ant, and it
+is not needed. </li>
+
+<li>If you ignore the first rule, do not ever, ever, have a trailing backslash
+in a <code>CLASSPATH</code>, as it breaks Ant's ability to quote the string. Again, this is
+not needed for the correct operation of the <code>CLASSPATH</code> environment variable, even
+if a DOS directory is to be added to the path. </li>
+
+<li>You can stop Ant using the <code>CLASSPATH</code> environment variable by setting the
+<code>-noclasspath</code> option on the command line. This is an easy way
+to test for classpath-related problems.</li>
+
+</ol>
+
+<p>
+
+The usual symptom of <code>CLASSPATH</code> problems is that ant will not run with some error
+about not being able to find <code>org.apache.tools.ant.launch.Launcher</code>, or, if you have got the
+quotes/backslashes wrong, some very weird Java startup error. To see if this is
+the case, run <code>ant -noclasspath</code> or unset the <code>CLASSPATH</code> environment
+variable.
+
+</p>
+
+<p>
+You can also make your Ant script reject this environment
+variable just by placing the following at the top of the script (or in an init target):
+</p>
+<pre>
+&lt;property environment="env."/&gt;
+&lt;property name="env.CLASSPATH" value=""/&gt;
+&lt;fail message="Unset $CLASSPATH / %CLASSPATH% before running Ant!"&gt;
+ &lt;condition&gt;
+ &lt;not&gt;
+ &lt;equals arg1="${env.CLASSPATH}" arg2=""/&gt;
+ &lt;/not&gt;
+ &lt;/condition&gt;
+&lt;/fail&gt;
+</pre>
+
+<h3><a name="proxy">Proxy Configuration</a></h3>
+
+<p> Many Ant built-in and third-party tasks use network connections to retrieve
+files from HTTP servers. If you are behind a firewall with a proxy server, then
+Ant needs to be configured with the proxy. Here are the different ways to do
+this. </p>
+
+<ul>
+
+<li><b>With Java1.5 or above</b><br>
+
+<p>
+When you run Ant on Java1.5 or above, you could try to use the automatic proxy setup
+mechanism with <code>-autoproxy</code>.
+</p>
+
+</li>
+
+<li><b>With explicit JVM properties.</b><br>
+<p>
+These are documented in <a
+href="http://docs.oracle.com/javase/7/docs/technotes/guides/net/properties.html" target="_top">Java's Networking Properties</a>,
+and control the proxy behaviour of the entire JVM. To set them in Ant, declare
+them in the <code>ANT_OPTS</code> environment variable. This is the best option
+for a non-mobile system. For a laptop, you have to change these settings as you
+roam. To set ANT_OPTS:
+</p>
+<blockquote>
+<p>
+ For csh/tcsh:
+</p>
+<pre>
+ setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
+</pre>
+<p>
+ For bash:
+</p>
+<pre>
+ export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
+</pre>
+<p>
+ For Windows, set the environment variable in the appropriate dialog box
+ and open a new console. or, by hand
+</p>
+<pre>
+ set ANT_OPTS = -Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080
+</pre>
+</p>
+</blockquote>
+</li>
+
+<li><b>In the build file itself</b><br>
+
+<p>
+If you are writing a build file that is always to be used behind the firewall,
+the &lt;setproxy&gt; task lets you configure the proxy (which it does by setting
+the JVM properties). If you do this, we strongly recommend using ant properties
+to define the proxy host, port, etc, so that individuals can override the
+defaults.</li>
+</p>
+
+</ul>
+
+<p> The Ant team acknowledges that this is unsatisfactory. Until the JVM
+automatic proxy setup works properly everywhere, explicit JVM options via
+ANT_ARGS are probably the best solution. Setting properties on Ant's
+command line do not work, because those are <i>Ant properties</i> being set, not
+JVM options. This means the following does not set up the command line:
+
+</p>
+
+<pre>ant -Dhttp.proxyHost=proxy -Dhttp.proxyPort=81</pre>
+
+<p> All it does is set up two Ant properties.</p>
+
+<p>One other troublespot with
+proxies is with authenticating proxies. Ant cannot go beyond what the JVM does
+here, and as it is very hard to remotely diagnose, test and fix proxy-related
+problems, users who work behind a secure proxy will have to spend much time
+configuring the JVM properties until they are happy. </p>
+
+
+<h3><a name="windows">Windows and OS/2</a></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.7.0_51
+set PATH=%PATH%;%ANT_HOME%\bin</pre>
+
+<h3><a name="bash">Linux/Unix (bash)</a></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/jdk1.7.0_51
+export PATH=${PATH}:${ANT_HOME}/bin</pre>
+
+<h3><a name="tcshcsh">Linux/Unix (csh)</a></h3>
+<pre>setenv ANT_HOME /usr/local/ant
+setenv JAVA_HOME /usr/local/jdk/jdk1.7.0_51
+set path=( $path $ANT_HOME/bin )</pre>
+
+<p>
+Having a symbolic link set up to point to the JVM/JDK version makes updates more seamless. </p>
+<a name="jpackage"></a>
+<h3>RPM version from jpackage.org</h3>
+<p>
+The <a href="http://www.jpackage.org" target="_top">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.
+</p>
+ <p>
+ <b>NOTE:</b> <em>Since Ant 1.7.0</em>, if the <code>ANT_HOME</code>
+ environment variable is set, the jpackage distribution will be
+ ignored.
+ </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 netrexx, 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-jpackage 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" target="_top">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-jai.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="Tasks/javac.html">javac</a> task or the
+<a href="Tasks/rmic.html">rmic</a> task), then <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="Tasks/exec.html">exec</a> task or the
+<a href="Tasks/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 clone the ant repository from git. See <a href="#sourceEdition">Source Edition</a> for details.</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 OpenJDK or Oracle's javac. It does not work with gcj or
+kjc.</p>
+
+<p>Make sure you have downloaded any auxiliary jars required to
+build tasks you are interested in. These should be
+added to the <code>lib/optional</code>
+directory of the source tree.
+See <a href="#librarydependencies">Library Dependencies</a>
+for a list of JAR requirements for various features.
+Note that this will make the auxiliary JAR
+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>You can also get most of the auxiliary jar files (ie. the jar files
+that various optional Ant tasks depend on) by running Ant on the
+<code>fetch.xml</code> build file. See <a href="#optionalTasks">Optional
+Tasks</a> for instructions on how to do this.
+</p>
+
+<p>As of version 1.7.0 Ant has a hard dependency on JUnit. The <code>fetch.xml</code> build
+ script will download JUnit automatically, but if you don't use this you must
+ install it manually into <code>lib/optional</code> (download it from
+ <a href="http://junit.org/" target="_top">JUnit.org</a>) if you are
+ using a source distribution of Ant.</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>sh 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>
+
+<li>Create the ant.jar and ant-launcher.jar JAR files</li>
+
+<li>Create optional JARs for which the build had the relevant libraries. If
+a particular library is missing from ANT_HOME/lib/optional, then the matching
+ant- JAR file will not be created. For example, ant-junit.jar is only built
+if there is a junit.jar in the optional directory.</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>sh 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>sh 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>
+
+<p>Ant's build script will try to set executable flags for its shell
+ scripts on Unix-like systems. There are various reasons why the
+ chmod-task might fail (like when you are running the build script as
+ a different user than the one who installed Ant initially). In this
+ case you can set the Ant property <code>chmod.fail</code> to false
+ when starting the build like in
+<blockquote>
+ <p><code>sh build.sh install -Dchmod.fail=false</code></p>
+</blockquote>
+and any error to change permission will not result in a build failure.</p>
+
+<hr>
+<h2><a name="librarydependencies">Library Dependencies</a></h2>
+<p>The following libraries are needed in Ant's classpath
+if you are using the
+indicated feature. Note that only one of the regexp libraries is
+needed for use with the mappers
+(and Java includes a regexp implementation which
+Ant will find automatically).
+You will also need to install the particular
+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>jakarta-regexp-1.3.jar</td>
+ <td>regexp type with mappers (if you do not wish to use java.util.regex)</td>
+ <td><a href="http://attic.apache.org/projects/jakarta-regexp.html" target="_top">http://attic.apache.org/projects/jakarta-regexp.html</a></td>
+ </tr>
+ <tr>
+ <td>jakarta-oro-2.0.8.jar</td>
+ <td>regexp type with mappers (if you do not wish to use java.util.regex)<br>
+ To use the FTP task,
+you need jakarta-oro 2.0.8 or later, and <a href="#commons-net">commons-net</a></td>
+ <td><a href="http://attic.apache.org/projects/jakarta-oro.html" target="_top">http://attic.apache.org/projects/jakarta-oro.html</a></td>
+ </tr>
+ <tr>
+ <td>junit.jar</td>
+ <td><code>&lt;junit&gt;</code> task. May be in classpath passed to task rather than Ant's classpath.</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>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
+ <p>
+ <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.
+ </p>
+ <p>
+ <strong>Note</strong>: BSF 2.4.0 is needed to use a post 1.5R3 version
+ of rhino's javascript.
+ </p>
+ <p>
+ <strong>Note</strong>: BSF 2.4.0 uses jakarta-commons-logging
+ so it needs the commons-logging.jar.
+ </p>
+ </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-[version].jar and
+ asm-util-[version].jar and antlr-[version].jar.
+ As of groovy version 1.0-JSR-06, the jars are
+ groovy-1.0-JSR-06.jar, antlr-2.7.5.jar, asm-2.2.jar and asm-util-2.2.jar.
+ Alternatively one may use the embedded groovy jar file.
+ This is located in the embedded directory of the groovy distribution.
+ This bundles all the needed jar files into one jar file.
+ It is called groovy-all-[version].jar.
+ </td>
+ <td>
+ <a href="http://groovy.codehaus.org/" target="_top">http://groovy.codehaus.org/</a>
+ <br>
+ The asm jars are also available from the creators of asm -
+ <a href="http://asm.objectweb.org/" target="_top">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://www.ibm.com/software/awdtools/netrexx/download.html" target="_top">
+ http://www.ibm.com/software/awdtools/netrexx/download.html</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 (e.g. version 2.4.0) work with 1.5R4 and higher).</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 preferred 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 requires 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.org/" target="_top">http://jruby.org/</a></td>
+ </tr>
+ <tr>
+ <td>judo.jar</td>
+ <td>Judoscript with script task</td>
+ <td><a href="http://www.judoscript.org/" target="_top">http://www.judoscript.org/</a></td>
+ </tr>
+ <tr>
+ <td>commons-logging.jar</td>
+ <td>CommonsLoggingListener</td>
+ <td><a href="http://commons.apache.org/logging/"
+ target="_top">http://commons.apache.org/logging/</a></td>
+ </tr>
+ <tr>
+ <td>log4j.jar</td>
+ <td>Log4jListener</td>
+ <td><a href="http://logging.apache.org/log4j/"
+ target="_top">http://logging.apache.org/log4j/</a></td>
+ </tr>
+ <tr>
+ <td><a name="commons-net">commons-net.jar</a></td>
+ <td>ftp, rexec and telnet tasks<br>
+ jakarta-oro 2.0.8 or later is required together with commons-net 1.4.0.<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://commons.apache.org/net/"
+ target="_top">http://commons.apache.org/net/</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://commons.apache.org/bcel/" target="_top">http://commons.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://www.oracle.com/technetwork/java/index-138643.html"
+ target="_top">http://www.oracle.com/technetwork/java/index-138643.html</a></td>
+ </tr>
+ <tr>
+ <td>activation.jar</td>
+ <td>Mail task with Mime encoding, and the MimeMail task</td>
+ <td><a href="http://www.oracle.com/technetwork/java/javase/jaf-135115.html"
+ target="_top">http://www.oracle.com/technetwork/java/javase/jaf-135115.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 <b>0.1.50 or later</b></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="https://jai.dev.java.net/"
+ target="_top">https://jai.dev.java.net/</a></td>
+ </tr>
+</table>
+<br>
+<h2><a name="Troubleshooting">Troubleshooting</a></h2>
+
+
+<h3><a name="diagnostics">Diagnostics</a></h3>
+
+<p> Ant has a built in diagnostics feature. If you run <code>ant
+-diagnostics</code> ant will look at its internal state and print it out. This
+code will check and print the following things. </p>
+
+<ul>
+
+<li>Where Ant is running from. Sometimes you can be surprised.</li>
+
+<li>The version of ant.jar and of the ant-*.jar containing the optional tasks -
+ and whether they match</li>
+
+<li>Which JAR files are in ANT_HOME/lib
+
+<li>Which optional tasks are available. If a task is not listed as being
+available, either it is not present, or libraries that it depends on are
+absent.</li>
+
+
+<li>XML Parser information</li>
+
+<li>JVM system properties
+</li>
+
+<li>The status of the temp directory. If this is not writable, or its clock is
+horribly wrong (possible if it is on a network drive), a lot of tasks will fail
+with obscure error messages.</li>
+
+<li>The current time zone as Java sees it. If this is not what it should be for
+your location, then dependency logic may get confused.
+
+</ul>
+
+<p>
+ Running <code>ant -diagnostics</code> is a good way to check that ant is
+ installed. It is also a first step towards self-diagnosis of any problem.
+ Any configuration problem reported to the user mailing list will probably
+ result ins someone asking you to run the command and show the results, so
+ save time by using it yourself.
+</p>
+
+<p>
+ For under-IDE diagnostics, use the &lt;diagnostics&gt; task to run the same
+ tests as an ant task. This can be added to a diagnostics target in a build
+ file to see what tasks are available under the IDE, what the XML parser and
+ classpath is, etc.
+</p>
+
+<h3><a name="ant-user">user mailing list</a></h3>
+
+<p> If you cannot get Ant installed or working, the Ant user mailing list is the
+best place to start with any problem. Please do your homework first, make sure
+that it is not a <a href="#classpath"><code>CLASSPATH</code></a> problem, and run a <a
+href="#diagnostics">diagnostics check</a> to see what Ant thinks of its own
+state. Why the user list, and not the developer list?
+Because there are more users than developers, so more people who can help you. </p>
+
+<p>
+
+Please only file a bug report against Ant for a configuration/startup problem if
+there really is a fixable bug in Ant related to configuration, such as it not
+working on a particular platform, with a certain JVM version, etc, or if you are
+advised to do it by the user mailing list.
+</p>
+
+
+
+
+</body>
+</html>