Note: This task depends on external libraries not +included in the Apache Ant distribution. See Library Dependencies +for more information.
Antlr 2.7.1 Note: To successfully run ANTLR, your best option is probably to build the whole diff --git a/manual/Tasks/ejb.html b/manual/Tasks/ejb.html index 4911e1407..f5544983c 100644 --- a/manual/Tasks/ejb.html +++ b/manual/Tasks/ejb.html @@ -593,7 +593,7 @@ any of these files are newer than the jar file the jar will be rebuilt otherwise a message is logged that the jar file is up to date.
The task uses the - BCEL framework +BCEL library to extract all dependent classes. This means that, in addition to the classes that are mentioned in the deployment descriptor, any classes that these depend on are also diff --git a/manual/Tasks/image.html b/manual/Tasks/image.html index ed7ed7ef4..077b3721a 100644 --- a/manual/Tasks/image.html +++ b/manual/Tasks/image.html @@ -27,7 +27,7 @@
Image
Description
Applies a chain of image operations on a set of files.
-Requires Java Advanced Image API from Sun.
+Requires Java Advanced Image API from Sun.
Overview of used datatypes
diff --git a/manual/Tasks/junitreport.html b/manual/Tasks/junitreport.html
index 365920b21..fea85e57b 100644
--- a/manual/Tasks/junitreport.html
+++ b/manual/Tasks/junitreport.html
@@ -23,12 +23,14 @@
JUnitReport
+Description
Merge the individual XML files generated by the JUnit task and eventually apply a stylesheet on the resulting merged document to provide a browsable report of the testcases results. -Note: This task depends on external libraries not included in -the Apache Ant distribution. See -Library Dependencies for more information.
+ +Note: This task depends on external libraries not +included in the Apache Ant distribution. See Library Dependencies +for more information.
Requirements
diff --git a/manual/Tasks/netrexxc.html b/manual/Tasks/netrexxc.html index 8102b7271..efdfa4dcd 100644 --- a/manual/Tasks/netrexxc.html +++ b/manual/Tasks/netrexxc.html @@ -58,6 +58,9 @@ supports most attributes of<fileset>
or from the command line asant -Dant.netrexxc.verbose=noverbose ...
+Note: This task depends on external libraries not +included in the Apache Ant distribution. See Library Dependencies +for more information.
Parameters
| KEYS | -PGP-Keysfile. It contains the PGP-keys of Ant developers so you can 'trust' the distribution. | +PGP keyfile. It contains the PGP keys of Ant developers so you can 'trust' the distribution. |
| RELEASE-NOTES-{version}.html | @@ -157,7 +149,7 @@ files are organized as follows.||
| ant-current-bin.zip | - ZIP-Archive containing the compiled version of Ant in the last released version. It is recommended that + 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. @@ -166,105 +158,103 @@ files are organized as follows. | |
| ant-current-src.zip | - 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 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. + ZIP archive containing the sources of Ant. If you have this you can compile Ant. If you do not have the + required 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. | |
| ant-current-*.asc | Security file for checking the correctness of the zip file. This one is the - PGP key. + PGP signature. | |
| ant-current-*.md5 | Security file for checking the correctness of the zip file. This one is the - MD5 key. + MD5 checksum. | |
| ant-current-*.sha1 | Security file for checking the correctness of the zip file. This one is the - SHA1 key. + SHA1 checksum. | |
| antlibs/ | - 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. + 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. | |
| 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 - directory, which is always guaranteed to be the most current release of Ant. + The binaries directory holds specific Ant releases bundled in both ZIP and tar.gz archive 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. | |
| common/ | - 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. + 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. | |
| source/ | - 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. + The source directory holds the source code for specific Ant releases bundled in both ZIP and tar.gz archive + 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. |
-
System Requirements
-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. - ++
System Requirements
++Ant has been used successfully on many platforms, including Linux, commercial flavours of Unix such as Solaris and +HP-UX, macOS, Windows NT descendants, OS/2 Warp, Novell Netware 6, OpenVMS. The platforms used most for development +are, in no particular order, Linux, macOS, Microsoft Windows and Unix; these are therefore that platforms that tend to +work best. As of Ant 1.7, Windows 9x is no longer supported. +
-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. +For the current version of Ant (1.10), you will also need a JDK installed on your system, version 8 or later required. +The more up-to-date the version of Java, the more Ant tasks you get.
- Note: If a JDK is not present, only the JRE runtime, then many tasks will not work. +Note: If a JDK is not present, only the runtime (JRE), then many tasks will not work.
- Note: - 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. + Note: + Ant 1.9.* works with JDK 1.5, Ant 1.8.* works with JDK 1.4 and higher, Ant 1.7.* works with JDK 1.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.
Open Source Java Runtimes
- The Ant team strongly supports users running Ant on OpenJDK and other - open source Java runtimes, and so strives to have a product that works - well on those platforms. +The Ant team strongly supports users running Ant on OpenJDK and +other open source Java runtimes, and so strives to have a product that works well on those platforms. +
+ ++
Installing Ant
++ The binary distribution of Ant consists of the following directory layout:
--
Installing Ant
-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
+ +--- lib // contains Ant JARs plus necessary dependencies
|
+--- docs // contains documentation
| |
@@ -277,12 +267,12 @@ The more up-to-date the version of Java , the more Ant tasks you get.
// - migrate your build files and get rid of 'deprecated' warning
// - ... and more ;-)
-
-Only the bin and lib 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.
+
+Only the bin and lib 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.
| - |
-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"
-batch-file statement. It is recommended, therefore, that Ant be
-installed in a short, 8.3 path, such as C:\Ant.
+ |
+ 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" batch file statement. It is recommended, therefore, that Ant be installed in a
+ short, 8.3 path, such as C:\Ant.
|
|
- 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
+ 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
+
+
|
Setup
+Setup
-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:
+Before you can run Ant there is some additional setup you will need to do unless you are installing the +RPM version from jpackage.org: +- Add the
bindirectory to your path.
- - Set the
ANT_HOMEenvironment variable to the -directory where you installed Ant. On some operating systems, Ant's -startup scripts can guessANT_HOME(Unix dialects and -Windows NT/2000), but it is better to not rely on this behavior.
- - Optionally, set the
JAVA_HOMEenvironment variable -(see the Advanced section below). -This should be set to the directory where your JDK is installed.
+ - Set the
ANT_HOMEenvironment variable to the directory where you installed Ant. On some operating +systems, Ant's startup scripts can guessANT_HOME(Unix dialects and Windows NT descendants), but it is +better to not rely on this behavior.
+ - Optionally, set the
JAVA_HOMEenvironment variable (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 -restrictions on the classes which may be loaded by an extension.
++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 restrictions on the classes which may be loaded by an extension.
+
- 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,
- and that they do not have quotes (either
- ' or ") and they do not end with \ or with /. CLASSPATH should be unset or
- empty.
+ 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, and that they do not have quotes (either ' or ") and
+ they do not end with \ or with /. CLASSPATH should be unset or empty.
|
Check Installation
-You can check the basic installation with opening a new shell and typing ant. You -should get a message like this +
Check Installation
+
+You can check the basic installation with opening a new shell and typing ant. You 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 -project. With a ant -version you should get an output like +
+So Ant works. This message is there because you need to write a buildfile for your project. With a ant
+-version you should get an output like
+
Apache Ant(TM) version 1.9.2 compiled on July 8 2013+
+If this does not work, ensure your environment variables are set right. E.g., on Windows, they must resolve to:
-If this does not work ensure your environment variables are set right. They must resolve to:
-
-
- required: %ANT_HOME%\bin\ant.bat -
- optional: %JAVA_HOME%\bin\java.exe -
- required: %PATH%=...maybe-other-entries...;%ANT_HOME%\bin;...maybe-other-entries... +
- required:
%ANT_HOME%\bin\ant.bat
+ - optional:
%JAVA_HOME%\bin\java.exe
+ - 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
-require the java tools.) If not set, the launcher tries to find one via the %PATH% environment variable.
+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 convenience. With that set you can just start ant instead of always typing
the/complete/path/to/your/ant/installation/bin/ant.
Optional Tasks
-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.
+Optional Tasks
++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. +
-The external libraries required by each of the optional tasks is detailed -in the Library Dependencies section. These external -libraries must be added to Ant's classpath, in any of the following ways: +
+The external libraries required by each of the optional tasks is detailed in the Library +Dependencies section. These external libraries must be added to Ant's classpath, in any of the following ways:
-
-
- In
ANT_HOME/lib. This makes the JAR files available to all - Ant users and builds. -
-
- - In
${user.home}/.ant/lib(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. -
-
- - On the command line with a
-libparameter. This lets - you add new JAR files on a case-by-case basis. -
-
- - In the
-CLASSPATHenvironment variable. Avoid this; it makes - the JAR files visible to all Java applications, and causes - no end of support calls. See below for details. -
-
- - In some
<classpath>accepted by the task itself. - For example, as of Ant 1.7.0 you can run the<junit>- task withoutjunit.jarin Ant's own classpath, so long as - it is included (along with your program and tests) in the classpath - passed when running the task. -- 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. -
+-
+
+In
+ANT_HOME/lib. This makes the JAR files available to all Ant users and builds. +
+ -
+
+In
+${user.home}/.ant/lib(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. +
+
+ -
+
+On the command line with a
+-libparameter. This lets you add new JAR files on a case-by-case basis. +
+
+ -
+
+In the
+CLASSPATHenvironment variable. Avoid this; it makes the JAR files visible to all Java +applications, and causes no end of support calls. See below for details. +
+
+ -
+
+In some
+<classpath>accepted by the task itself. For example, as of Ant 1.7.0 you can run +the<junit>task withoutjunit.jarin Ant's own classpath, so long as it is included +(along with your program and tests) in the classpath passed when running the task. ++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. +
+
- 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.
+If you are using the binary distribution 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 that
+the optional Ant tasks need.
- To do so, change to the ANT_HOME directory and execute the command:
+To do so, change to the ANT_HOME directory and execute the command:
@@ -450,85 +446,71 @@ libraries must be added to Ant's classpath, in any of the following ways:
- 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
-
-
+
system- store in Ant's lib directory (Recommended)
+user- store in the user's home directory
+optional- store in Ant's source codelib/optionaldirectory, used when building Ant +source code
+
- You may also need to set proxy settings. See the Proxy Settings section for details. +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. Tasks that depend on
-commercial software, in particular, will require you to have the commercial software installed
-in order to be used.
+Note that not all dependencies are gathered using fetch.xml. Tasks that depend on commercial software, in
+particular, will require you to have the commercial software installed in order to be used.
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. +
+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. +
+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. +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.
-The CLASSPATH environment variable
+The CLASSPATH environment variable
-
-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.
-
+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.
-
+
- Do not ever set
CLASSPATH. Ant does not need it, it only causes confusion and breaks things.
- - Do not ever set
CLASSPATH. Ant does not need it, it only causes confusion -and breaks things. - -
-
- - 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.
+ - 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.
- - 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 theCLASSPATHenvironment variable, even -if a DOS directory is to be added to the path.
-
- - You can stop Ant using the
CLASSPATHenvironment variable by setting the --noclasspathoption on the command line. This is an easy way -to test for classpath-related problems.
+ - 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 theCLASSPATH+environment variable, even if a DOS directory is to be added to the path.
+ - You can stop Ant using the
CLASSPATHenvironment variable by setting the-noclasspath+option on the command line. This is an easy way to test for classpath-related problems.
-
-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.launch.Launcher, or, if you have got the
-quotes/backslashes wrong, some very weird Java startup error. To see if this is
-the case, run ant -noclasspath or unset the CLASSPATH environment
-variable.
-
+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.launch.Launcher, or, if you have got the quotes/backslashes wrong, some very
+weird Java startup error. To see if this is the case, run ant -noclasspath or unset
+the CLASSPATH environment variable.
-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): +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):
<property environment="env."/> @@ -542,254 +524,236 @@ variable just by placing the following at the top of the script (or in an init t </fail>-
Proxy Configuration
+Proxy Configuration
-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.
++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. +
-
-
-
- With Java1.5 or above
- + - With Java 5 or above
-When you run Ant on Java1.5 or above, you could try to use the automatic proxy setup -mechanism with
--autoproxy. +When you run Ant on Java 5 or above, you could try to use the automatic proxy setup mechanism +with-autoproxy.
- - With explicit JVM properties.
+ - With explicit JVM properties.
-These are documented in Java's Networking Properties, -and control the proxy behaviour of the entire JVM. To set them in Ant, declare -them in the
ANT_OPTSenvironment 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: +These are documented in Java's Networking Properties, and control the proxy behaviour of the entire JVM. To set them in Ant, +declare them in theANT_OPTSenvironment variable. This is the best option for a non-mobile system. For a +laptop, you have to change these settings as you roam. To setANT_OPTS:- For csh/tcsh: +For csh/tcsh:
setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"- For bash: +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 +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
- + - In the build file itself
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.
+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.
-
+
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 Ant properties being set, not -JVM options. This means the following does not set up the command line: - +
+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 Ant properties being set, not JVM options. This means the following does not set
+up the command line:
ant -Dhttp.proxyHost=proxy -Dhttp.proxyPort=81-
All it does is set up two Ant properties.
- -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.
++All it does is set up two Ant properties. +
++One other trouble spot 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. +
-Windows and OS/2
+Windows and OS/2
Assume Ant is installed in c:\ant\. The following sets up the
environment:
set ANT_HOME=c:\ant set JAVA_HOME=c:\jdk1.7.0_51 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/jdk1.7.0_51
export PATH=${PATH}:${ANT_HOME}/bin
-Linux/Unix (csh)
+Linux/Unix (csh)
setenv ANT_HOME /usr/local/ant setenv JAVA_HOME /usr/local/jdk/jdk1.7.0_51 set path=( $path $ANT_HOME/bin )
-Having a symbolic link set up to point to the JVM/JDK version makes updates more seamless.
- -RPM version from jpackage.org
-
-The JPackage project distributes an RPM version of Ant.
-With this version, it is not necessary to set JAVA_HOME or
- ANT_HOME environment variables and the RPM installer will correctly
-place the Ant executable on your path.
-
- NOTE: Since Ant 1.7.0, if the ANT_HOME
- environment variable is set, the jpackage distribution will be
- ignored.
-
-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. oro-2.0.8-2jpp.noarch.rpm) and the small library that links
-ant and the external package (e.g. ant-apache-oro-1.6.2-3jpp.noarch.rpm).
-
-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: +Having a symbolic link set up to point to the JVM/JDK version makes updates more seamless. +
+RPM version from jpackage.org
+
+The JPackage project distributes an RPM version of Ant. With this
+version, it is not necessary to set JAVA_HOME or ANT_HOME environment variables and the RPM
+installer will correctly place the Ant executable on your path.
+
+NOTE: Since Ant 1.7.0, if the ANT_HOME environment variable is set, the JPackage
+distribution will be ignored.
+
+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. oro-2.0.8-2jpp.noarch.rpm) and the small library that links Ant and the
+external package (e.g. ant-apache-oro-1.6.2-3jpp.noarch.rpm).
+
+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: +
+-
-
- Decide where you want to deploy the extra jars. One option is in
$ANT_HOME/lib, -which, for JPackage is usually/usr/share/ant/lib. Another, less messy option -is to create an.ant/libsubdirectory 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 -here
- - Download a non-jpackage binary distribution from the regular - Apache Ant site +
- Decide where you want to deploy the extra JARs. One option is in
$ANT_HOME/lib, which, for JPackage is +usually/usr/share/ant/lib. Another, less messy option is to create an.ant/libsubdirectory +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 here
+ - Download a non-JPackage binary distribution from the regular Apache Ant site
- Unzip or untar the distribution into a temporary directory -
- Copy the linking jar, in this case
ant-jai.jar, into the library directory you -chose in step 1 above.
- - Copy the proprietary jar itself into the same directory. +
- Copy the linking JAR, in this case
ant-jai.jar, into the library directory you chose in step 1 +above.
+ - Copy the proprietary JAR itself into the same directory.
--noconfig command-line switch to avoid JPackage's classpath mechanism.
+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 --noconfig command-line switch to avoid JPackage's classpath mechanism.
-Advanced
+Advanced
+ +There are many different ways to run Ant. What you need is at least the following:
-There are lots of variants that can be used to run Ant. What you need is at -least the following:
-
-
- The classpath for Ant must contain
ant.jarand any jars/classes -needed for your chosen JAXP-compliant XML parser.
- - When you need JDK functionality
-(such as for the javac task or the
-rmic task), then
tools.jar-must be added. The scripts supplied with Ant, -in thebindirectory, will add -the required JDK classes automatically, if theJAVA_HOME+ - The classpath for Ant must contain
ant.jarand any JARs/classes needed for your chosen JAXP-compliant +XML parser.
+ - When you need JDK functionality (such as for the javac task or
+the rmic task), then
tools.jarmust be added. The scripts supplied with Ant, +in thebindirectory, will add the required JDK classes automatically, if theJAVA_HOMEenvironment variable is set.
-
- - When you are executing platform-specific applications, such as the
-exec task or the
-cvs task, the property
ant.home-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 + - When you are executing platform-specific applications, such as the exec task or
+the cvs task, the property
ant.homemust be set to the directory containing +where you installed Ant. Again this is set by the Ant scripts to the value of theANT_HOMEenvironment variable.
-
Building Ant
-To build Ant from source, you can either install the Ant source distribution -or clone the ant repository from git. See Source Edition for details.
-Once you have installed the source, change into the installation -directory.
- -Set the JAVA_HOME environment variable
-to the directory where the JDK is installed.
-See Installing Ant
-for examples on how to do this for your operating system.
Note: The bootstrap process of Ant requires a greedy -compiler like OpenJDK or Oracle's javac. It does not work with gcj or -kjc.
- -Make sure you have downloaded any auxiliary jars required to
-build tasks you are interested in. These should be
-added to the lib/optional
-directory of the source tree.
-See Library Dependencies
-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
-Installing Ant.
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.
Your are now ready to build Ant:
+ +The supplied Ant shell scripts all support anANT_OPTS 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.
+
++
Building Ant
++To build Ant from source, you can either install the Ant source distribution or clone the Ant repository from Git. See +Source Distribution for details. +
++Once you have installed the source, change into the installation directory. +
+ +
+Set the JAVA_HOME environment variable to the directory where the JDK is
+installed. See Installing Ant for examples on how to do this for your operating system.
+
+Note: The bootstrap process of Ant requires a greedy compiler like OpenJDK or Oracle's javac. It does not work +with gcj or kjc. +
+ +
+Make sure you have downloaded any auxiliary JARs required to build tasks you are interested in. These should be added to
+the lib/optional directory of the source tree. See Library Dependencies
+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 Installing Ant.
+
+You can also get most of the auxiliary JAR files (i.e. 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.
+
+Your are now ready to build Ant: +
-
build -Ddist.dir=<directory_to_contain_Ant_distribution> dist(Windows)
sh build.sh -Ddist.dir=<directory_to_contain_Ant_distribution> dist(Unix)
This will create a binary distribution of Ant in the directory you specified.
++This will create a binary distribution of Ant in the directory you specified. +
-The above action does the following:
++The above action does the following: +
-
-
-
- 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. - -
- 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 "dist" target
-in Ant's own
build.xmlfile.
-
- - Create the ant.jar and ant-launcher.jar JAR files - -
- 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. +
- 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. +
- 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 "dist" target in Ant's own
build.xmlfile.
+ - Create the
ant.jarandant-launcher.jarJAR files
+ - Create optional JARs for which the build had the relevant libraries. If a particular library is missing
+from
lib/optional, then the matching ant-library JAR file will not be created. For +example,ant-junit.jaris only built if there is ajunit.jarin thelib/optional+directory.
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 bootstrap.bat (Windows) or bootstrap.sh (UNIX)
-to build a new bootstrap version of Ant.
+On most occasions you will not need to explicitly bootstrap Ant since the build scripts do that for you. However, if the
+build file you are using makes use of features not yet compiled into the bootstrapped Ant, you will need to manually
+bootstrap. Run bootstrap.bat (Windows) or bootstrap.sh (UNIX) to build a new bootstrap version
+of Ant.
+
ANT_HOME
directory, you can use:
@@ -804,299 +768,267 @@ You can avoid the lengthy Javadoc step, if desired, with:
sh build.sh install-lite (Unix)
bin and lib directories.
-Both the install and
-install-lite targets will overwrite
-the current Ant version in ANT_HOME.
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 chmod.fail to false
- when starting the build like in
+
+
+Both the install and install-lite targets will overwrite the current Ant version
+in ANT_HOME.
+
+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 chmod.fail to false when starting the build like in
+
-and any error to change permission will not result in a build failure. - -
sh build.sh install -Dchmod.fail=false
-
Library Dependencies
-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 -Installing Ant / Optional Tasks section above.
++and any error to change permission will not result in a build failure. +
+ ++
Library Dependencies
+ ++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 Installing Ant / Optional Tasks section above. +
| Jar Name | +JAR Name | Needed For | Available At | ||
| jakarta-regexp-1.3.jar | -regexp type with mappers (if you do not wish to use java.util.regex) | -http://attic.apache.org/projects/jakarta-regexp.html | +jakarta-regexp-1.4.jar | +regexp type with mappers (if you do not wish to use + java.util.regex) | +https://attic.apache.org/projects/jakarta-regexp.html |
| jakarta-oro-2.0.8.jar | -regexp type with mappers (if you do not wish to use java.util.regex) - To use the FTP task, -you need jakarta-oro 2.0.8 or later, and commons-net |
- http://attic.apache.org/projects/jakarta-oro.html | +regexp type with mappers (if you do not wish to use + java.util.regex) or ftp task with commons-net 1.4.1 | +https://attic.apache.org/projects/jakarta-oro.html | |
| junit.jar | -<junit> task. May be in classpath passed to task rather than Ant's classpath. |
- http://www.junit.org/ | +junit task (may be in classpath passed to task rather than Ant's classpath) | +http://junit.org/ | |
| xalan.jar | -junitreport task | -http://xml.apache.org/xalan-j/ | +junitreport task | +https://xml.apache.org/xalan-j/ | |
| antlr.jar | -antlr task | +antlr task | http://www.antlr.org/ | ||
| bsf.jar | -script task
- - Note: Ant 1.6 and later require Apache BSF, not - the IBM version. I.e. you need BSF 2.3.0-rc1 or later. - -- Note: BSF 2.4.0 is needed to use a post 1.5R3 version - of rhino's javascript. - -- Note: BSF 2.4.0 uses jakarta-commons-logging - so it needs the commons-logging.jar. - - |
- http://jakarta.apache.org/bsf/ | +script task + Note: Ant 1.6 and later require Apache BSF 2.3.0 or later. + Note: BSF 2.4.0 is needed to use a 1.5R4 or later versions of Rhino JavaScript. + Note: BSF 2.4.0 uses Commons Logging so it needs the commons-logging.jar. + |
+ https://commons.apache.org/bsf/ | |
| Groovy jars | -Groovy with script and scriptdef tasks - 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. - |
+ Groovy JARs | +Groovy Ant tasks with bindings or Groovy with script + and scriptdef tasks |
- http://groovy.codehaus.org/
- - The asm jars are also available from the creators of asm - - http://asm.objectweb.org/ + http://groovy-lang.org/ + Use either groovy-ant for Groovy Ant tasks with bindings or groovy-bsf for Groovy with script and scriptdef tasks + (or groovy-all) |
|
| netrexx.jar | -netrexx task, Rexx with the script task | -- http://www.ibm.com/software/awdtools/netrexx/download.html | +netrexxc task, Rexx with script task | +https://www.ibm.com/software/awdtools/netrexx/library.html | |
| js.jar | -Javascript with script task - 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). |
- http://www.mozilla.org/rhino/ | +rhino.jar + (included in Java 7 runtime, replaced by Nashorn in Java 8 and later) |
+ JavaScript with script task + Note: Apache BSF 2.4.0 works only with Rhino 1.5R4 and later versions. |
+ https://www.mozilla.org/rhino/ |
| jython.jar | -Python with script task - Warning : jython.jar also contains classes from jakarta-oro. - Remove these classes if you are also using jakarta-oro. |
- http://jython.sourceforge.net/ | +Python with script task | +http://www.jython.org/ | |
| jpython.jar | -Python with script task deprecated, jython is the preferred engine | -http://www.jpython.org/ | +jacl.jar and tcljava.jar | +TCL with script task | +http://tcljava.sourceforge.net/ |
| jacl.jar and tcljava.jar | -TCL with script task | -http://www.scriptics.com/software/java/ | +jtcl.jar | +TCL with script task | +https://jtcl-project.github.io/jtcl/ |
| BeanShell JAR(s) | -BeanShell with script task.
- - Note: Ant requires BeanShell version 1.3 or - later |
+ BeanShell with script task. + Note: Ant requires BeanShell version 1.3 or later |
http://www.beanshell.org/ | ||
| jruby.jar | -Ruby with script task | +Ruby with script task | http://jruby.org/ | ||
| judo.jar | -Judoscript with script task | +Judo language with script task | http://www.judoscript.org/ | ||
| commons-logging.jar | CommonsLoggingListener | -http://commons.apache.org/logging/ | +https://commons.apache.org/logging/ | ||
| log4j.jar | Log4jListener | -http://logging.apache.org/log4j/ | +https://logging.apache.org/log4j/ | ||
| commons-net.jar | -ftp, rexec and telnet tasks - jakarta-oro 2.0.8 or later is required together with commons-net 1.4.0. - 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. + | ||||
| commons-net.jar | +ftp, rexec
+ and telnet tasks + A minimum version of commons-net of 1.4.0 is needed to compile Ant, earlier versions did not support the full range + of configuration options. + jakarta-oro 2.0.8 is required together with commons-net 1.4.x at run time. + Note: do not use commons-net 3.2 because + of performance issues |
- http://commons.apache.org/net/ | +https://commons.apache.org/net/ | ||
| bcel.jar | -classfileset data type, - JavaClassHelper used by the ClassConstants filter reader and - optionally used by ejbjar for dependency determination - | -http://commons.apache.org/bcel/ | +classfileset data type, JavaClassHelper used by the ClassConstants filter + reader and optionally used by ejbjar task for dependency determination | +https://commons.apache.org/bcel/ | |
| mail.jar | -Mail task with Mime encoding, and the MimeMail task | -http://www.oracle.com/technetwork/java/index-138643.html | +javax.mail-api.jar | +mail task with MIME encoding, + and deprecated mimemail task | +https://javaee.github.io/javamail/ |
| activation.jar | -Mail task with Mime encoding, and the MimeMail task | +activation.jar + (included in Java 6 and later runtime) |
+ mail task with MIME encoding, + and deprecated mimemail task | http://www.oracle.com/technetwork/java/javase/jaf-135115.html | |
| jdepend.jar | -jdepend task | -http://www.clarkware.com/software/JDepend.html | +jdepend task | +https://github.com/clarkware/jdepend | |
| resolver.jar 1.1beta or later | -xmlcatalog datatype only if support for external catalog files is desired | -http://xml.apache.org/commons/. | +resolver.jar 1.1 or later | +xmlcatalog datatype only if support for external catalog files is + desired | +https://xerces.apache.org/xml-commons/components/resolver/ |
| jsch.jar 0.1.54 or later | -sshexec and scp tasks | -http://www.jcraft.com/jsch/index.html | +sshexec and scp tasks | +http://www.jcraft.com/jsch/ | |
| JAI - Java Advanced Imaging | -image task | -https://jai.dev.java.net/ | +image task | +https://download.java.net/media/jai/builds/release/1_1_3/INSTALL.html | |
| XZ - XZ for Java 1.6 or later | -xz and unxz tasks, xzresource, xz compression in tar/untar | -http://www.tukaani.org/xz/java.html | +xz and unxz + tasks, xzresource, xz compression + in tar/untar tasks | +https://www.tukaani.org/xz/java.html |
-
Troubleshooting
+Troubleshooting
-Diagnostics
+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.
+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.
+
- Where Ant is running from. Sometimes you can be surprised. -
- The version of ant.jar and of the ant-*.jar containing the optional tasks - - and whether they match - -
- Which JAR files are in ANT_HOME/lib +
- The version of ant.jar and of the ant-*.jar containing the optional tasks - and whether they match -
- 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. +
- Which JAR files are in
ANT_HOME/lib
+ - 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.
- XML Parser information -
- JVM system properties - +
- JVM system properties -
- 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. +
- 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. -
- 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. +
- 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.
- 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.
+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 diagnostics, 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. +For diagnostics from within IDE, use the diagnostics task to run the same tests as +an Ant option. 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.
user mailing list
-
-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.
+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. +