Previous Section
Table of Contents
Next Section

Setting Up the Ant Environment

Ant is a project of Apache Software Foundation. It runs on all operating systems. Some UNIX-based systems that support Ant are:

Some Windows-based systems that support Ant are:

Software Requirements

You need the following software to compile and build Ant:

  • Java API for XML Processing (JAXP) to build and use Ant.

  • Java Development Kit (JDK) to provide its utility tools to Ant’s buildfile for the building process.

Installing Ant

To install Ant, you first need to download Ant source code or binary code files to a temporary directory and then decompress the compressed files to a specific directory. Ant is available in the following two editions:

  • Binary edition: Includes the binary files that Sun Microsystems builds from the source in the source edition. You can download the Ant binary edition from the following URL:

    http://cvs.apache.org/builds/ant/nightly

After downloading, compile the Ant source code and then install the compiled code to run Ant on your computer by specifying the following commands at the command prompt:

./configure
make 
make install

You can run Ant from where you have installed the Ant binaries.

Table 1-2 lists the subdirectories of the Ant installation directory:

Table 1-2: Subdirectories of Ant

Directory

Description

bin

Specifies batch files, Perl scripts, and shell scripts for executing Ant.

docs

Documents the working of Ant. This child directory of the Ant installation parent directory contains the Ant documentation.

lib

Specifies the library files that Ant imports during its execution.

src

Specifies source code for Ant. This source code is present in the source distribution.

Installing the Binary Edition

In the binary distribution of Ant, all the Java files exist in compiled form and are packaged into JAR files. To install the binary distribution:

  1. Extract the Ant zip file and unzip it in a specific directory.

  2. Set the ANT_HOME environment variable to the directory that contains Ant.

  3. Set the JAVA_HOME environment variable to the JDK installation directory.

  4. Insert ANT_HOME/bin in the system CLASSPATH environment variable.

You can verify the correct installation of Ant by typing the following command:

ant -version

The following output indicates the correct installation of Ant:

Ant version 1.4.1 compiled on October 11 2001

Ant contains a number of optional tasks to perform a specific function. The tasks require an external library to perform the functions. The external libraries are either present in Ant’s lib directory or you can set the external libraries on the system CLASSPATH. When downloading Ant, you need to download the JAR files to install the optional tasks in the binary distribution directory on the Ant Web site. For example, the <junit> task, which is an optional task of Ant, requires the junit.jar file that you must add to the system CLASSPATH environment variable before running Ant.

Installing the Source Edition

To install Ant from source code:

  1. Extract the source files and redirect them to a directory other than the directory of an existing Ant installation.

  2. Set the ANT_HOME environment variable to the directory that contains Ant.

  3. Set the JAVA_HOME environment variable to the JDK installation directory.

  4. Add ANT_HOME/bin to your system's PATH environment variable.

Using Optional Tasks

To use optional tasks, you need to specify the required JAR files in the CLASSPATH environment variable. For example, the <ftp> task is an optional task that requires the common-net.jar file for its execution. The optional tasks cannot execute without the presence of their required JAR files. When the download and installation processes of the JAR files are complete, you can start compiling the buildfile. The optional tasks are selected automatically if the external libraries that the optional tasks require are present in Ant’s lib directory.

Building Ant Libraries

The command to compile Ant from the source distribution directory for Windows-based operating systems is:

build -Ddist.dir=destination_directory dist

The command to compile Ant from the source distribution directory for UNIX-based operating systems is:

build.sh -Ddist.dir=destination_directory dist

The build script creates a complete binary distribution of Ant in the specified destination directory.

Before executing the above commands, you need to ensure that JAVA_HOME is set to the directory where you have installed JDK.

The command to install Ant directly to ANT_HOME for Windows-based operating systems is:

build install

The command to install Ant directly to ANT_HOME for UNIX-based operating systems is:

build.sh install

Dependencies of Ant

Ant assumes specific dependencies in terms of library files for optional tasks and the operating system that Ant supports for its proper execution. The dependencies of the Ant installation are:

  • Library dependencies

  • Platform dependencies

Library Dependencies

Ant requires various libraries, programs, and packages for the building and execution process of the application. You should either specify these libraries in the CLASSPATH or in the install directory’s lib directory. The libraries contain JAR files that contain tasks that perform the operations.

Table 1-3 lists the various JAR files:

Table 1-3: JAR Files

JAR Name

Description

An Extensible Stylesheet Language (XSL) transformer, such as Xalan or XSL:P

Provides the <style> task that allows you to automate the application of a stylesheet to an XML document using an XSLT processor.

junit.jar

Provides the <junit> task that allows you to write and run automated tests.

xalan.jar

Provides the <junitreport> task that merges the individual XML files that the <junit> task produced and applies a stylesheet to the resulting merged document to deliver a report of test case results.

stylebook.jar

Provides the <stylebook> task that executes the Apache Stylebook documentation generator.

testlet.jar

Provides the <test> task that executes a unit test in the org.apache.testlet framework.

antlr.jar

Provides the <antlr> task that invokes the Another Tool for Language Recognition (ANTLR) Translator Generator on a grammar file. ANTLR is a language tool that provides a framework to build compilers and recognizers from grammatical descriptions containing Java actions.

Commonsnet.jar

Performs common network tasks, such as ftp, rexec, and telnet.

Log4j.jar

Updates the log messages of different applications.

Jdepend.jar

Provides the <jdepend> task that produces design-quality metrics in terms of the extensibility, maintainability, and reusability of each Java package.

Mail.jar

Merges Multipurpose Internet Mail Extension (MIME) data type support for e-mail messages. This JAR file is required to encode e-mail messages into MIME type.

Bsf.jar

Provides the <script> task that executes the build script in an Apache Bean Scripting Framework (BSF)-supported language. BSF is a collection of Java classes that allows you to write Java Server Pages (JSP) in languages other than Java.

BeanShell JAR

Embeds the BeanShell scripting language with the <script> task in Ant build applications.

Netrexx.jar

Embeds the Rexx scripting language with the <script> task in Ant build applications.

Js.jar

Embeds the javascript scripting language with the <script> task in Ant build applications.

Judo.jar

Embeds the Judo scripting language with the <script> task in Ant build applications.

Jcl.jar and tcljava.jar

Embeds the Tool Command Language (TCL) scripting language with the <script> task in Ant build applications.

Jruby.jar

Embeds the Ruby scripting language with the <script> task in Ant build applications.

Jython.jar

Embeds the Python scripting language with the <script> task in Ant build applications.

JAI- java Advanced imaging

Provides the <image> task that helps generate and transform images dynamically. The <image> task exposes the imaging capability of Java2Developer (Java2D), Java Advanced Imaging, and ImageIO as a set of nested elements.

Jsch.jar

Secures data, such as mail, over Simple Mail Transfer Protocol (SMTP) by encrypting and decrypting the data.
Platform Dependencies

Ant is a cross-platform Java-based tool that you can install on a range of operating systems. Some platform-related issues that you should consider when installing Ant are:

  • UNIX: Consists of the kernel, standard utility programs, and system configuration files. The kernel reads system configuration files. If you install Ant on UNIX, you should use a GNU version of tar to untar the Ant source tree because this file is in compressed form. Ant does not save file permissions when you copy or move a file because Java does not provide Ant with the read or write permission. You need to use the <chmod> task to set file permissions.

  • Windows: Uses graphics to run programs. If you want to install Ant on Windows, you should install Ant and JDK in directories.

  • Cygwin: Provides the Linux environment in Windows by allowing Linux commands to execute on the Windows platform. There is no particular JDK and Java Runtime Environment (JRE) for cygwin because it is an application. As a result, JDK or JRE tools support only Windows pathnames under Windows or cygwin.

Listing 1-1 shows how to convert cygwin paths to Windows path names:

Listing 1-1: Converting Cygwin Path Names to Windows Path Names
Start example 
<property name="some.cygwin.path" value="/cygdrive/h/somepath"/>
<exec executable="cygpath" outputproperty="windows.pathname">
<arg value="--windows"/>
<arg value="${some.cygwin.path}"/>
</exec>
<echo message="${windows.pathname}"/>
End example

The above listing converts cygwin path names to Windows path names because JDK or JRE tools support only Windows path names under cygwin or Windows.

  • Novell Netware: Provides a consistent interface that is independent of hardware. Novell Netware is networking software that works on various LANs to transmit messages. To install Ant on Novell Netware, you need to include the following environment variables in the system environment variable settings:

    • CLASSPATH: Specifies the ant.jar, xercesImpl.jar, xml-apis.jar, and other required JAR files in the system CLASSPATH environment variable.

    • ANT_OPTS: Includes a parameter of the form "-envCWD=ANT_HOME" where ANT_HOME specifies the complete path of Ant.


Configuring Ant

If the ant.bat batch file is present in the system path, you can run Ant from a command prompt. If the ant.bat file is not present in the system path, you need to configure the following items to run Ant manually:

  • Include ant.jar and any JAXP-compliant XML parser in the system CLASSPATH.

  • Include classes.zip in the CLASSPATH for JDK 1.1 and tools.jar for Java 2 for tasks, such as javac, which help in the compilation process of application building.

  • Set up the ant.home Java system property in the Ant installation directory required to launch the Java Virtual Machine (JVM) with the -D flag.

  • Include the JAR files in the system CLASSPATH for optional tasks.

After setting the system CLASSPATH, enter the following command to call Ant:

java -Dant.home=pathToAnt org.apache.tools.ant.Main

Configuring XML Parser

The Ant buildfile uses XML to store build information. Ant is a Java-based tool that requires Java-based XML parsers, such as Document Object Model (DOM), JAXP, Simple API for XML Processing (SAXP), and Simple API for XML (SAX), to parse the XML document and process the elements sequentially. Ant versions 1.4 and later use JAXP 1.1 as an XML parser. JAXP 1.1 enables applications to parse and transform XML documents independent of a particular XML-processing implementation. JAXP 1.1 JAR files, such as jaxp.jar and parser.jar, are present in ANT_HOME/lib. Ant or ant.bat adds these JAR files along with any other JAR files to the CLASSPATH to parse the XML document.

Configuring a Proxy Server

You need to configure a proxy server to execute specific Ant tasks, such as get, telnet, and ftp, which require a network connection to execute their functions. You can configure the proxy server by setting JVM system properties, such as proxySet, proxyHost, and proxyPort. You can set system properties in two ways:

  • By editing Ant’s startup script ant.bat

  • Using the ANT_OPTS environment variable

The following command sets JVM system properties using the ANT_OPTS environment variable:

set ANT_OPTS=-DproxySet=true -DproxyHost=localhost -DproxyPort=80

Building Ant

Ant is a platform-independent scripting tool that allows you to create build scripts. The two methods to build Ant from source are:

  • Installing the Ant source distribution

  • Installing the Ant module from Current Version System (CVS)

When the installation process is complete, set the JAVA_HOME environment variable to the directory that contains JDK. Download the auxiliary JARs that you need to build tasks. You should either specify them in the CLASSPATH or add them to the lib directory. The next step is to build Ant. The command to build Ant for Windows-based operating systems is:

build -Ddist.dir=<directory_to_contain_Ant_distribution> dist

The command to build Ant for UNIX-based operating systems is:

build.sh -Ddist.dir=<directory_to_contain_Ant_distribution> dist

The above commands create a binary distribution of Ant in the specified directory. If required, these commands bootstrap the Ant code. Bootstrapping is a process to manually compile Ant for execution.

Setting up Environment Variables

You need to set the following environment variables to run the build scripts of Ant:

  • ANT_HOME: Includes the installation directory of Ant. This environment variable is set to the directory that contains Ant.

  • JAVA_HOME: Allows you to upgrade JDK without altering all the scripts. This environment variable is set in the directory that contains JDK.

  • PATH: Includes the bin directories of the J2EE Software Development Kit (SDK), Java 2 Standard Edition (J2SE), and Ant installations.

The method to set these environment variables depends on the operating system of the computer. If you are working on Linux and using a BASH shell, you need to include the following code in the ~/.bashrc file to set the environment variables:

export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/java/j2sdk1.4.2
export PATH=${JAVA_HOME}/bin:${ANT_HOME}/bin:$PATH
export CVS_RSH=ssh

The above code substitutes the correct path for each environment variable.

If you are working on Windows, you can set the environment variables using the System Properties applet present in the System icon on the Control Panel. You need to own administrative rights to set environment variables. Next, include the following environment variables in the CLASSPATH environment variable to adjust the paths of Java, Cygwin, and Ant:

  • Set ANT_HOME to c:\jakarta-ant-1.5.1

  • Set JAVA_HOME to c:\j2sdk1.4.2

  • Set CVS_RSH to ssh

After setting the environment variables, you need to restart the computer for the changes to take effect.


Previous Section
Table of Contents
Next Section