ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ste...@apache.org
Subject svn commit: r358951 - /ant/core/trunk/docs/manual/install.html
Date Sat, 24 Dec 2005 19:48:07 GMT
Author: stevel
Date: Sat Dec 24 11:48:03 2005
New Revision: 358951

URL: http://svn.apache.org/viewcvs?rev=358951&view=rev
Log:
more installation help, esp. classpath, proxy and troubleshooting.

Modified:
    ant/core/trunk/docs/manual/install.html

Modified: ant/core/trunk/docs/manual/install.html
URL: http://svn.apache.org/viewcvs/ant/core/trunk/docs/manual/install.html?rev=358951&r1=358950&r2=358951&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/install.html (original)
+++ ant/core/trunk/docs/manual/install.html Sat Dec 24 11:48:03 2005
@@ -34,7 +34,10 @@
 <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 9x and NT, OS/2 Warp, Novell Netware 6 and MacOS X.
+Windows 9x and NT, 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 work best.
 <p>
 To build and use Ant, you must have a JAXP-compliant XML parser installed and
 available on your classpath.</p>
@@ -49,13 +52,15 @@
 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>
+<code>lib</code> directory or put the jars on the system classpath. 
+Some parts of Ant will fail if you use an old parser, especially one
+that is not namespace-aware. In particular, avoid the Crimson parser.</p>
+
+<p>Tip: "ant -diagnostics" will list the XML parser used and its location.</p>
 
 <p>
 For the current version of Ant, you will also need a JDK installed on
 your system, version 1.2 or later.
-</p><p>
-<strong>Note: </strong>The Microsoft JVM/JDK is not supported.
 </p>
 <p>
 <strong>Note #2: </strong>If a JDK is not present, only the JRE runtime, then
many tasks will not work.
@@ -65,6 +70,7 @@
 <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
@@ -121,7 +127,7 @@
 
 <h3>Setup</h3>
 <p>
-Before you can run ant there is some additional set up you
+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>
@@ -147,28 +153,129 @@
 <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 may either be placed in Ant's lib directory, where they will be picked up
-automatically, or made available on the system CLASSPATH environment variable.
+automatically.
+</p>
+
+<h3><a name="classpath">The CLASSPATH environment variable</a></h3>
+<p>
+
+The CLASSPATH 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 CLASSPATH. 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
+CLASSPATH, 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 CLASSPATH, as it breaks Ant's ability to quote the string. Again, this is
+not needed for the correct operation of the CLASSPATH environment variable, even
+if a DOS directory is to be added to the path. </li>
+
+<li>You can stop Ant using the CLASSPATH environment variable by setting the
+<code>-noclasspath</code> option on the command line.</li>
+
+</ol>
+
+<p>
+
+The usual symptom of CLASSPATH problems is that ant will not run with some error
+about not being able to find org.apache.tools.Ant.main, or, if you have got the
+quotes/backslashes wrong, some very wierd Java startup error. To see if this is
+the case, run <code>ant -noclasspath</code> or unset the CLASSPATH environment
+variable.
+
 </p>
 
-<h3>Windows and OS/2</h3>
+
+<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</b><br>. 
+
+When you run Ant on Java1.5, it tries to use the automatic proxy setup
+mechanism. If this works -and it is a big if, as we see little evidence of it
+doing so on Linux or WinXP, then your proxy is set up without you doing
+anything. You can disable this feature with the <code>-noproxy</code> option.
+
+</li>
+
+<li><b>With explicit JVM properties.</b><br>.
+
+These are documented <a
+href="http://java.sun.com/j2se/1.5.0/docs/guide/net/properties.html">by Sun</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.
+
+</li>
+
+<li><b>In the build file itself</b><br>
+
+If you are writing an 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>
+
+</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. Note that 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.2.2
+set JAVA_HOME=c:\jdk-1.5.0.05
 set PATH=%PATH%;%ANT_HOME%\bin</pre>
 
-<h3>Unix (bash)</h3>
+<h3>Linux/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 JAVA_HOME=/usr/local/jdk-1.5.0.05
 export PATH=${PATH}:${ANT_HOME}/bin</pre>
 
-<h3>Unix (csh)</h3>
+<h3>Linux/Unix (csh)</h3>
 <pre>setenv ANT_HOME /usr/local/ant
-setenv JAVA_HOME /usr/local/jdk-1.2.2
+setenv JAVA_HOME /usr/local/jdk/jdk-1.5.0.05
 set path=( $path $ANT_HOME/bin )</pre>
 
+<p>
+Having a symbolic link set up to point to the JVM/JSK version makes updates more seamless.
</p>
 <a name="jpackage"></a>
 <h3>RPM version from jpackage.org</h3>
 <p>
@@ -206,6 +313,7 @@
 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
@@ -215,8 +323,7 @@
 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>
+<a href="CoreTasks/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>
@@ -308,8 +415,8 @@
 
 <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
+<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 1.4 and higher includes a regexp implementation which
@@ -329,12 +436,10 @@
     <td>An XSL transformer like Xalan or XSL:P</td>
     <td>style task</td>
     <td>
-    <b>If you use JDK 1.4, an XSL transformer is already included, so you need not
do anything special.</b><br>
+    <b>If you use JDK 1.4+, an XSL transformer is already included, so you need not
do anything special.</b><br>
     <ul><li>XALAN : <a href="http://xml.apache.org/xalan-j/index.html"
     target="_top">http://xml.apache.org/xalan-j/index.html</a></li>
-    <li>XSL:P : used to live at <a href="http://www.clc-marketing.com/xslp/"
-    target="_top">http://www.clc-marketing.com/xslp/</a>, but the link
-    doesn't work any longer and we are not aware of a replacement site.</li></ul>
+    </ul>
     </td>
   </tr>
   <tr>
@@ -533,6 +638,65 @@
   </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>The version of ant.jar and ant-optional.jar -and that they match</li>
+
+<li>Which JAR files are int 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 writeable, 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 diagostics, 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">CLASSPATH</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>
+
+
 <hr>
 <p align="center">Copyright &copy; 2000-2005 The Apache Software Foundation. All
rights
 Reserved.</p>



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message