Return-Path: Delivered-To: apmail-ant-notifications-archive@minotaur.apache.org Received: (qmail 9455 invoked from network); 16 May 2010 21:06:18 -0000 Received: from unknown (HELO mail.apache.org) (140.211.11.3) by 140.211.11.9 with SMTP; 16 May 2010 21:06:18 -0000 Received: (qmail 77277 invoked by uid 500); 16 May 2010 21:06:18 -0000 Delivered-To: apmail-ant-notifications-archive@ant.apache.org Received: (qmail 77253 invoked by uid 500); 16 May 2010 21:06:18 -0000 Mailing-List: contact notifications-help@ant.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@ant.apache.org Delivered-To: mailing list notifications@ant.apache.org Received: (qmail 77246 invoked by uid 99); 16 May 2010 21:06:18 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 16 May 2010 21:06:17 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 16 May 2010 21:06:15 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id BF88B23889D7; Sun, 16 May 2010 21:05:55 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r944911 - in /ant/core/trunk/docs/manual: install.html installlist.html Date: Sun, 16 May 2010 21:05:55 -0000 To: notifications@ant.apache.org From: bruce@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20100516210555.BF88B23889D7@eris.apache.org> Author: bruce Date: Sun May 16 21:05:55 2010 New Revision: 944911 URL: http://svn.apache.org/viewvc?rev=944911&view=rev Log: Added short story, described fetch.xml, updated download instructions Modified: ant/core/trunk/docs/manual/install.html ant/core/trunk/docs/manual/installlist.html Modified: ant/core/trunk/docs/manual/install.html URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/install.html?rev=944911&r1=944910&r2=944911&view=diff ============================================================================== --- ant/core/trunk/docs/manual/install.html (original) +++ ant/core/trunk/docs/manual/install.html Sun May 16 21:05:55 2010 @@ -26,7 +26,113 @@

Installing Ant

Getting Ant

Download Area Layout

The Short Story

To get up and running with Ant quickly, follow these steps: +

Make sure you have a Java environment installed, See System +Requirements for details.
Download Ant. See Binary Edition for details.
Uncompress the downloaded file into a directory.
Set environmental variables JAVA_HOME to your Java environment, ANT_HOME to +the directory you uncompressed Ant to, and add ${ANT_HOME}/bin (Unix) or +%ANT_HOME%/bin (Windows) to your PATH. See Setup for details.
Optionally, run ant -f fetch.xml -Ddest=system to get the library dependencies +of most of the Ant optional tasks. If you don't do this, many of the optional Ant tasks will not be available. See Optional Tasks for +details and other options for the -Ddest parameter.
Optionally, add any desired Antlibs. See Ant Libraries for a list. +

+The short story for working with the Ant source code is: +

Get the source code. See Source Edition for details.
Build Ant. See Building Ant for details.

+For the full story, continue reading. +

+ +

Binary Edition

+ +

The latest stable version of Ant is available from the Ant web page http://ant.apache.org/ +

+ +

The binary edition of Ant is shipped with 3 different compression formats: +

.zip - Recommended compression format for Windows, can also be used on other platforms. Supported +by many programs and some operating systems natively.
.tar.gz - Uses the tar program to gather files together, and gzip to compress and uncompress.
.tar.bz2 - Uses the tar program to gather files together, and bzip2 to compress and uncompress..

+Choose the format that is best supported for your platform. +

+ +

As a binary in an RPM Package

+ +

Consult the jpackage section below.

+ +

Bundled in IDEs

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

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

+ +

Bundled in Java applications

+ +

+ 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 wierdly after installing something, try the + diagnostics advice. +

+ +

Source Edition

+ +

If you prefer the source edition, you can download the source for the latest +Ant release from +http://ant.apache.org/srcdownload.cgi. + +If you prefer the leading-edge code, you can access +the code as it is being developed via SVN. The Ant website has details on +accessing SVN. +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. +

+ + +See the section Building Ant on how to +build Ant from the source code. +You can also access the + +Ant SVN repository on-line.

+ +

Archive Download Area Layout

+Older versions of Ant are available in the archives at http://archive.apache.org/dist/ant/. The +files are organized as follows. +

@@ -46,8 +152,10 @@ @@ -55,7 +163,8 @@ @@ -91,7 +200,7 @@ @@ -105,76 +214,14 @@

Filename or Path
ant-current-bin.zip	- ZIP-Archive containing the compiled version of Ant in the last released version. This is the file - most users will want to download. + 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.
ZIP-Archive containing the sources of Ant. If you have this you could compile Ant itself. If you do not have the required dependencies, the classes depeding on them are just not - build. + 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.
binaries/	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 + 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.
source/	- The source directory holds the source code for specific Ant releases bundled in both ZIP and + 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 + in the parent directory, which is always guaranteed to hold the source code for the most current release of Ant.

Binary Edition

The latest stable version of Ant is available from the Ant web page http://ant.apache.org/. - -

As a binary in an RPM Package

- -

Consult the jpackage section below.

- -

Bundled in IDEs

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

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

- -

Bundled in Java applications

- -

- 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 non 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 wierdly after installing something, try the - diagnostics advice. -

- -

Source Edition

- -

If you prefer the source edition, you can download the source for the latest -Ant release from -http://ant.apache.org/srcdownload.cgi. - -If you prefer the leading-edge code, you can access -the code as it is being developed via SVN. The Ant website has details on -accessing SVN. -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. -

- - -See the section Building Ant on how to -build Ant from the source code. -You can also access the - -Ant SVN repository on-line.

System Requirements

Ant has been used successfully on many platforms, including Linux, @@ -243,7 +290,8 @@ files there. This directory will be know -On these systems, the script used to launch Ant will have +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 "8.3"). This is due to limitations in the OS's handling of the "for" @@ -264,7 +312,7 @@ installed in a short, 8.3 path, s -
Setup
+
Setup

Before you can run Ant there is some additional set up you will need to do unless you are installing the RPM @@ -279,6 +327,10 @@ Windows NT/2000), but it is better to no (see the Advanced section below). This should be set to the directory where your JDK is installed. +
Operating System-specific instructions for doing this from the command +line are in the Windows, Linux/Unix (bash), +and Linux/Unix (csh) sections. Note that using this method, +the settings will only be valid for the command line session you run them in.

Note: 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 @@ -294,9 +346,9 @@ restrictions on the classes which may be The ant.bat script makes use of three environment variables - - ANT_HOME, CLASSPATH and JAVA_HOME. Ensure that ANT_HOME and JAVA_HOME variables are set, + ANT_HOME, CLASSPATH and JAVA_HOME. Ensure that ANT_HOME and JAVA_HOME variables are set, and that they do not have quotes (either - ' or ") and they do not end with \ or with /. CLASSPATH should be unset or + ' or ") and they do not end with \ or with /. CLASSPATH should be unset or empty. @@ -309,11 +361,11 @@ should get a message like this Buildfile: build.xml does not exist! Build failed -So Ant works. This message is there because you need to write an individual buildfile for your +So Ant works. This message is there because you need to write an individual buildfile for your project. With a ant -version you should get an output like
Apache Ant version 1.7.1 compiled on June 27 2008 -
+

If this does not work ensure your environment variables are set right. They must resolve to:
@@ -322,7 +374,7 @@ Apache Ant version 1.7.1 compiled on Jun
required: %PATH%=...maybe-other-entries...;%ANT_HOME%\bin;...maybe-other-entries...

ANT_HOME is used by the launcher script for finding the libraries. -JAVA_HOME is used by the launcher for finding the JDK/JRE to use. (JDK is recommended as some tasks +JAVA_HOME 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. PATH is set for user convinience. With that set you can just start ant instead of always typing the/complete/path/to/your/ant/installation/bin/ant. @@ -378,6 +430,50 @@ libraries must be added to Ant's classpa
+ 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 ANT_HOME directory you should see a + file called fetch.xml. This is an Ant script that you can run to + install almost all the dependencies the optional Ant tasks need. +
+ +
+ To do so, change to the ANT_HOME directory and execute the command: +
+ +
+
ant -f fetch.xml -Ddest=[option]
+
+ where option is one of the following, as described above: +
+
system - store in Ant's lib directory (Recommended)
+
user - store in the user's home directory
+
optional - store in Ant's source code lib/optional directory, used if building Ant source code
+
+
+ +
+ You may also need to set proxy settings. See the Proxy Settings section for details. +
+ +
+Note that not all dependencies are gathered using fetch.xml. For example, netrexx.jar and jai.jar +require you to manually download the files. See Library Dependencies.for the +URLs where you can get these files. +
+ +
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 Ant Libraries page. +
+ +
You can also find tasks and types provided by third-party projects at the +External Tools and Tasks page. +
+ +
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. @@ -453,29 +549,55 @@ this.

With Java1.5
+
When you run Ant on Java1.5, you could try to use the automatic proxy setup -mechanism with -autoproxy. +mechanism with -autoproxy. +

With explicit JVM properties.
- +
These are documented by Sun, and control the proxy behaviour of the entire JVM. To set them in Ant, declare them in the ANT_OPTS environment variable. This is the best option for a non-mobile system. For a laptop, you have to change these settings as you -roam. - +roam. To set ANT_OPTS: +
+
+
+ For csh/tcsh: +
+
+ setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080" +
+
+ For bash: +
+
+ export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080" +
+
+ For Windows, set the environment variable in the appropriate dialog box + and open a new console. or, by hand +
+
+ set ANT_OPTS = -Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080 +
+
+

In the build file itself
-If you are writing an build file that is always to be used behind the firewall, +
+If you are writing a build file that is always to be used behind the firewall, the <setproxy> 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.
+
@@ -505,14 +627,14 @@ environment:
set JAVA_HOME=c:\jdk-1.5.0.05 set PATH=%PATH%;%ANT_HOME%\bin -
Linux/Unix (bash)
+
Linux/Unix (bash)

Assume Ant is installed in /usr/local/ant. The following sets up the environment:

export ANT_HOME=/usr/local/ant export JAVA_HOME=/usr/local/jdk-1.5.0.05 export PATH=${PATH}:${ANT_HOME}/bin
-
Linux/Unix (csh)
+
Linux/Unix (csh)

setenv ANT_HOME /usr/local/ant setenv JAVA_HOME /usr/local/jdk/jdk-1.5.0.05 set path=( $path $ANT_HOME/bin )
@@ -595,7 +717,7 @@ at the source for your platform's invoca

Building Ant

To build Ant from source, you can either install the Ant source distribution -or checkout the ant module from SVN.
+or checkout the ant module from SVN. See Source Edition for details.

Once you have installed the source, change into the installation directory.
@@ -620,7 +742,14 @@ still need to make the JARs available as described under Installing Ant.
-
As of version 1.7.0 Ant has a hard dependency on JUnit and you must +
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 +fetch.xml build file. See Optional +Tasks for instructions on how to do this. +
+ +
As of version 1.7.0 Ant has a hard dependency on JUnit. The fetch.xml build + script will download JUnit automatically, but if you don't use this you must install it manually into lib/optional (download it from JUnit.org) if you are using a source distribution of Ant.
Modified: ant/core/trunk/docs/manual/installlist.html URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/installlist.html?rev=944911&r1=944910&r2=944911&view=diff ============================================================================== --- ant/core/trunk/docs/manual/installlist.html (original) +++ ant/core/trunk/docs/manual/installlist.html Sun May 16 21:05:55 2010 @@ -33,6 +33,7 @@
System Requirements

Installing Ant

Check Installation
+
Optional Tasks

Building Ant

Library Dependencies

Platform Specific Issues