ANT : Java Glossary

ANT

ANT (A Neat Tool). It is an open-source Java-based platform-independent Make tool. The current version is 1.8.2. Last revised/verified: 2010-12-27

Introduction

Javac does not need a make since it is capable of figuring out for itself what needs to be recompiled, however ANT is useful for all the auxiliary build tasks like time stamping, copying, creating jars, jar signing, bundling for distribution, version control, logging, testing… ANT is multiplatform where batch files are not, making it better suited for team programming where developers may be using a variety of OSes. You might think of it more as an XML-based scripting language than a simple make.

You don’t need to deal with the different :; classpath conventions or /\ conventions in different platforms.

You can extend ANT with Java code that uses the ANT classes and interfaces.

Normally ANT just feeds all the source files to javac.exe, invoking it only once. This makes it far faster than java.exe compilation for compiling many directories. If you use the DEPEND function it will delete some class files before doing this to force Java to recompile based on dependencies. I have heard conflicting reports on whether it will catch all the recompilations needed. Adding JAVAMAKE to ANT makes is slightly smarter, but it still cannot be relied on to catch all the files that need recompiling. It is conservative, and recompiles even more than it needs to when a static final changes. Whenever you change static finals in ANT, you had better recompile the universe doing a clean compile by deleting all the class files first.

The big problem with ANT is its verbosity. It takes a dozen lines just to copy a file. Part of the problem is the XML (extensible Markup Language) base. The other part of the problem is the lack of syntactic sugar.

Configuring

ANT is relentlessly multiplatform, and hence requires almost no configuring. It comes as a zip without an installer. ANT does not use the registry. You must put its bin directory on the PATH for it to find its executables and set up ANT_HOME in the set environment using settings ⇒ Control Panel ⇒ system ⇒ advanced ⇒ environment.

SET ANT_HOME=J:\Program Files (x86)\apache-ant-1.8.2

I found that sometimes ANT could not find its own class files. I solved this by copying all its jars to the java ext directory. ANT requires that the environment variable JAVA_HOME be set correctly to J:\Program Files\java\jdk1.7.0_02 .

If you use genjar, copy GenJar.jar and genjar.properties to J:\Program Files (x86)\apache-ant-1.8.2\lib.

Running

Here is how you might run an ANT script build.xml in the current directory:

or using CyWin Bash:

rem build with ANT under CygWin Bash
rem -v = verbose
rem -Duser.home=W: = set System property user.home to W:
rem -f build2.xml = use ANT script build2.xml (default is build.xml)
rem build = run the "build" target

ant -v -Duser.home=cygdrive/w -f build2.xml build

ANT Scripts

Following, in the next major section, is a fairly complicated script, one I use in production to build and sign a jar for the Wassup Applet. Just try to get the general drift of how it works.

The <!-- in green are comments, since ANT is a type of XML.
At the beginning, in the definitions section, my script sets up properties. These are like local variables, short names for long strings. I try to put all the package specific code up here, and write a generic body.
The spots in the code marked with <target mark distinct stages or steps. In a typical run some steps will be skipped.
Files following the <delete will be deleted.
The <javac line is the one that compiles all the files in the current directory tree. It compiles the whole tree, not just the current directory the way javac.exe does.
The <genjar is a wonderful ANT add-on that cleverly adds just the classes you need to the jar and no more, even when the classes live in other packages. You can also manually add resources and dynamically loaded classes.
<signjar signs the jar using the jarsigner.exe program.
To avoid putting the password for my certificate into the script, which I distribute to the public, I put it in the set environment with:
set jarsignerpassword=sesame
The script accesses the environment with:
storepass="${env.jarsignerpassword}"
which has the same effect as if I had typed:
storepass="sesame".
JET (Just Enough Time) is an ahead-of-time optimising compiler that generates native executables. There is no built-in support for it in ANT, so used the generic <exec to invoke it.
<uptodate compares the dates on two files and sets a property to true or false depending on which is older. This can be used later to bypass a step/target. If for example the JET executable is already newer than the corresponding jar, I can bypass the lengthy JET native compilation of the jar.
<available checks for the existence of a file and sets a corresponding property, pretty clumsy, but that is the penalty for trying to do everything with pure XML syntax.
Conditional execution is extremely clumsy in ANT. Imagine in Java that instead of typing:
```
// conditional increment in Java
if ( file.exists() ) i++;
```
you had to write:
then you have some idea of the verbosity of ANT conditionals. Obviously, ANT conditionals are not written in Java, but they have that same degree of awkwardness. This comes from trying to do everything in pure XML syntax. In ANT you have to create a named step called a target that contains the commands you may or may not want to execute. Then you apply the keyword if and property name to the target. You have to elsewhere in the program set the property to true or false depending on whether you want the step executed. Then you have to do an <antcall to the step to attempt to execute it! All this, because the ANT people have a love affair with XML! It is major production to conditionally copy a file that may or may not exist.
ANT is case sensitive.

Complex Build Script

This build script builds Wassup, a signed Applet.

Simple Build Script

Here is a much simpler script. It compiles and creates a jar for the com.mindprod.holidays. Holidays Applet. This Applet has a set of dynamic classes, one for each holiday in the year. It also has a resource properties file listing all the dynamic classes. You can take this script, change the properties in the definitions section and use it for your own projects.

Note that a typical ANT script only compiles explicitly mentioned *.java files and their dependencies. It does not do a javac *.java.

Meta Script

This script compiles many other scripts, doing the cleans in all scripts first, then the compiles etc.

Learning ANT

ANT is an unusual program. No matter what you tell it to do, it rarely complains. It trusts you completely, and finds some way to interpret your commands as reasonable. It is just that it will compile quite unexpected files, put them in quite unexpected places and delete quite unexpected files. Do your initial experiments on a small set of expendable files until you get the hang of how it works. You can easily be lulled into a false sense that you understand ANT when you don’t.

basedir

ANT is quite elegant and simple. Nearly all the problems I had with it come from the manual which was written by people who knew too much and failed to explain the basics, such as what the basedir is. Let’s say you want to compile the classes in the com.mindprod.holidays package, what is the basedir?

The current directory when the ANT script was started?
the directory where the build.xml script lives?
C:\com?
C:\com\mindprod?
C:\com\mindprod\holidays?

Nope. None of them!

The ANT people tend to set up directory structures like this: C:\project7\source\com\mindprod\holidays for the *.java files and C:\project7\build\classes\com\mindprod\holidays for the *.class files.

If you do things the Antish way, then the basedir is C:\project7.

If you insist on doing things the simpler way with classes and source in the same directory and you have a simple directory structure like this C:\com\mindprod\holidays for both *.java and *.class, then your basedir is C:\.

The basedir defaults to the current directory when ANT was invoked. This is rarely what you want. When you use a meta-ANT script to invoke all your little build.xml scripts using <ANT or <subant, it can set, and believe it or not, even override the setting in the individual build.xml scripts.

Though I don’t see ANT experts doing this, it seems logical you should explicitly specify the basedir in each xml script. Examples often show it as . or *.*. To me, this makes no sense. Then the script only works if you put the build.xml in the basedir and cd to the basedir before you start the script.

Beware the index="true" option on <jar. At least turn it off if Java can’t find your classes. The problem has been reported in older ANT versions when you have a manifest Class-Path entry. If you set it to true, you must include additional jars using the indexjars feature.

Antish or Javish?

What are the pros and cons of setting you your file structure in the Antish separate directories for source and classes or the Javish way of merging *.java and *.class files in the same directories?

Javish has the following advantages:

It is what most novices learn.
It is easier to keep tabs on what is going on vis a vis compilation. You can compare dates of the java and class files, see if there are uncompiled classes, class file older than the source, watch the relative size of source and class file, etc.
This is the way javac.exe works by default.

Antish has the following advantages:

When you look at directory listings of your source files, they are not cluttered with class files.
You can select the entire tree of source for backup without wasting time backing up class files that could be easily recreated.
you can delete an entire directory tree to get rid of all class files without any possibility of accidentally taking destroying the *.java files in the process.

Javac srcdir

Unlike basedir, srcdir is not built into ANT. It is just a convention. You have to define it with a property.

<property name="srcdir" value="source"/>

Further javac is not smart enough to automatically look in the srcdir property. You have to explicitly specify it: the

If you define srcdir as a relative directory name, it is relative to basedir, not the current directory. Setting it to . means it is the same as the basedir.

Now where should srcdir point? It depends just how much you want to recompile. Let’s assume you just want to compile the classes in the com.mindprod.holidays package.

If you do things the antish way, srcdir should point to C:\project7\source\com\mindprod\holidays where the *.java files you want to compile are.

If you do things the simple way with *.java and *.class mixed then srcdir should point to C:\com\mindprod\holidays.

Let’s assume you want to recompile every java source in the entire com tree.

If you do things the antish way, srcdir should point to C:\project7\source\com,

If you do things the simple way with *.java and *.class mixed then srcdir should point to C:\com.

Javac destdir

Like srcdir, destdir is just a convention for the name of a property. It defines which directory to put the compiled class files. Where should destdir point? If you do things the antish way, it should point to C:\project7\classes, not to C:\project7\classes\com\mindprod\holidays where the class files will eventually end up.

If you do things the simple way with *.java and *.class mixed then destdir should point to C:\, or just leave it out, and javac will automatically put class files in the same directory as the corresponding source file.

Javac classpath

There are two ways to handle the classpath:

Use the classpath in the set environment
Set it explicitly in your ant script.

The second way is preferable, since then your script will run on another machine without the environment classpath:

Tips

Ant is improperly case sensitive. Your environment variables must match in case, even though the operating system itself treats them in a case-insensitive way.
Make sure all your commands are inside some sort of target. Otherwise your ant scripts will crawl along incredibly slowly.
Your java.exe -classpath in ant.bat must not end with \ or ANT will be terribly confused. This is not really ANT ’s fault. It is a side effect of the way java.exe parses the command line. See main for details.
ANT uses its own flavour of wildcards they call patterns. They allow matching both of subdirectory name and filename. That explains all those extra *s in them.
A simple debugging command to pause the script while you examine the files looks like this:
```

<input message="Press Return key to continue..." />
```
Parameters of the form "${classes.dir}" are not built-in magic. They are properties expanded inline, much like DOS (Disk Operating System) %set variables. You will find a definition for them earlier in the script:
```
<property name="classes.dir" value="${basedir}/classes"/>
```
Taskdefs hook ANT up to custom code to integrate some program it is not familiar with out the box. For example, you need a taskdef to tell ANT where to find genjar.jar, since genjar is not a built-in ANT task.
Targets mark stages in the execution of a build e.g. compile, jar, sign. You might run a script only up to the jar stage, by specifying ANT jar as your target on the command line.
Selectors are what ANT calls FilenameFilters.
Unlike javac, ANT is clever and will compile an entire directory tree without being asked.
If something you want to do is not built into ANT, you can add it by writing Java code that implements one or more of ANT ’s interfaces, then hooking it into ANT, usually with a taskdef. ANT is designed so that you can add pretty well anything similar to what you see built-in.
When you do any sort of jar building, double check that the elements are being added to the jar have the expected member name structure that reflects the package name.
When you use ANT to sign jars, the command to invoke jarsigner.exe is called <signjar not <jarsigner as you might expect.
The copy task ignores some extensions. Search the docs for the word defaultexcludes for the various ways to get around this list.
The tstamp task gives you the current date and time as a property in a name of your own choosing, you can then use in constructing filenames etc.
<echoproperties/> will dump out the value of alls possible properties, a debugging aid.
In <zipset includes="xxx" excludes="xxx" the wildcards work like this:
- **/*.java means all files with extension java in any subdir of the current dir.
- *.java means all files with extension java in the current dir.
- **/jetpdb/*.* means any files in a directory called jetpdb at any depth in the current directory tree.
- jetpdb/*.* means any files in a directory called jetpdb hanging directly off the current directory.
- */*.java means any files with extension java in any directory one deep off the current directory.
When you specify multiple targets in a depends parameter, you must specify them in the reverse order you want them executed.
If ant suddenly stops working after working for years, check out the set parameters such as:

When To Clean Compile

Ant and Java combined create a mighty compiling engine that will blow your socks off. The reason is, it loads the Java compiler only once no matter how many source files you have. So even a clean compile is over in a twinkling.

My rule in Java is this:

When I am debugging, I do an ordinary compile unless I update a non-private static final constant. Then I do a clean compile of the source file containing that constant and of all users of that constant.
If something strange seems to be happening, with old code being used, I do a bulk clean compile.
Just prior to a big test or final release, I do a clean compile.
After changes that affect a number of packages, I do a site wide clean compile. I don’t try to sort out which ones really need it.

Building the jars and the zips takes more time than compiling, so compiling is not the bottleneck any more. MAKE-like tracking dependencies as a game not worth the candle.

Extracting Version Number from a File

Stomper

ANT is verbose and repetitive. If you clone and modify scripts, then discover an error, spelling mistake or typo in the original, or discover a better way to do something, you will have propagated the error in many places to fix. So what I did was write a Java program to stomp out my ANT scripts like a cookie cutter. That way they are perfectly consistent, perfectly aligned, and consistently commented. If I fix a bug in one script, it is fixed in all. I describe each package with a couple of lines and the cookie cutter produces the reams and reams of ANT coding.

I have not officially released my Stomper. It contains far too much code specific to my needs, but it might give you an idea of how you could write you own. You can view it in the Subversion repository. You debug once, not once for each package. Either everything works or nothing works. This is important because debugging ANT scripts is difficult. ANT gives you very little explanation of why it does what it does and the documentation is abysmal. You have to figure most things out by experiment or by looking at other people’s scripts.

Summary

Though ANT has two major warts:

convoluted verbosity
atrocious manuals

It has four features that make it mandatory for any medium to large project:

It is cross platform. You need only one set of scripts for a team to do builds on wide variety of hardware. You can give build scripts to customers that will work without tweaking no matter what their hardware.
It is much faster than doing the compiles with javac.exe.
It works. It is relatively bug free. Once you learn how it works, it is actually easier than writing the equivalent batch scripts.
It is extensible. If ANT is missing functionality, you can write Java code to add what you need. Most other scripting languages are closed.

Extra Libraries

Many ANT commands such as FTP (File Transfer Protocol) and GENJAR require auxiliary jars not part of ANT. See the Ant Library Dependencies Documentation to find out what these jars are and where to download them. Just put them in your ext directory to make them available to ANT.

Books

recommend book⇒Ant in Action: Java Development with Ant, Second Edition

by:

Steve Loughran and Erik Hatcher

978-1-932394-80-1

paperback

publisher:

Manning

published:

2007-07-12

Convert JUnit and extending the core tasks. This is not just a repackaging of the ANT documentation.

Greyed out stores probably do not have the item in stock

recommend book⇒Pro Apache Ant

by:

Matthew Moodie

978-1-59059-559-6

hardcover

publisher:

Apress

published:

2005-11-16

Step by step examples.

Greyed out stores probably do not have the item in stock

recommend book⇒Ant: The Definitive Guide

by:

Jesse E. Tilly, Eric M. Burke

978-0-596-00184-1

paperback

publisher:

O’Reilly

978-0-613-91199-3

hardcover

published:

2002-05-15

You would expect there to have been an ant on the cover, but that creature was already spoken for Oracle PL /SQL Programming. Not one of O’Reilly’s better efforts. Does not properly cover Ant 1.5..1.8.

Greyed out stores probably do not have the item in stock

ANT Factory
AnthillPro3
AntView (Plugin for Eclipse)
C2 ANT wiki
CruiseControl
genjar
InstallAnywhere integration with ANT
Jakarta ANT resources
Java Guru ANT FAQ
Java Guru ANT Forums
Maven
Nant
On Java article
on the fly compose, compile and run
os.name
Turbine

	You can get the freshest copy of this page from:	or possibly from your local J: drive (Java virtual drive/mindprod.com website mirror)
	http://mindprod.com/jgloss/ant.html	J:\mindprod\jgloss\ant.html
	Please email your feedback for publication, letters to the editor, errors, omissions, typos, formatting errors, ambiguities, unclear wording, broken/redirected link reports, suggestions to improve this page or comments to Roedy Green : If you want your message kept confidential, not considered for posting, please explicitly specify that.
	Canadian Mind Products
	mindprod.com IP:[65.110.21.43]
view Blog	Your face IP:[38.107.179.213]
Feedback	You are visitor number 76,636.