From 9bfe68ba1203e45235643b1882e8066971d3ec99 Mon Sep 17 00:00:00 2001 From: Steve Loughran Date: Sat, 24 Dec 2005 19:48:03 +0000 Subject: [PATCH] more installation help, esp. classpath, proxy and troubleshooting. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@358951 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/install.html | 204 +++++++++++++++++++++++++++++++++++---- 1 file changed, 184 insertions(+), 20 deletions(-) diff --git a/docs/manual/install.html b/docs/manual/install.html index 342a4665a..cf029e2d5 100644 --- a/docs/manual/install.html +++ b/docs/manual/install.html @@ -34,7 +34,10 @@ Ant CVS repository on-line.

System Requirements

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.

To build and use Ant, you must have a JAXP-compliant XML parser installed and available on your classpath.

@@ -49,13 +52,15 @@ If you wish to use a different JAXP-compliant parser, you should remove from Ant's lib directory. You can then either put the jars from your preferred parser into Ant's -lib directory or put the jars on the system classpath.

+lib 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.

+ +

Tip: "ant -diagnostics" will list the XML parser used and its location.

For the current version of Ant, you will also need a JDK installed on your system, version 1.2 or later. -

-Note: The Microsoft JVM/JDK is not supported.

Note #2: If a JDK is not present, only the JRE runtime, then many tasks will not work. @@ -65,6 +70,7 @@ your system, version 1.2 or later.

The binary distribution of Ant consists of the following directory layout: 

   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 @@ installed in a short, 8.3 path, such as C:\Ant. 
 
 
Setup

 

-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 RPM 
 version from jpackage.org:

 
     
   
   
@@ -533,6 +638,65 @@ Already included in jdk 1.4
   
 
 

+
Troubleshooting

+
+
+
Diagnostics

+
+
 Ant has a built in diagnostics feature. If you run ant
+-diagnostics ant will look at its internal state and print it out. This
+code will check and print the following things. 

+
+
+
+

+Running ant -diagnostics 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.
+

+
+

+For under-IDE diagostics, use the <diagnostics> 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. 
+

+
+
user mailing list

+
+
 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 CLASSPATH problem, and run a diagnostics check 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. 

+
+

+
+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.
+

+
+
 

 
Copyright © 2000-2005 The Apache Software Foundation. All rights
 Reserved.