Introduction

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.

Configuring

SET ANT_HOME=E:\apache-ant-1.7.0

Running

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

• 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 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 writing this:

  // 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.
• Wildcards in ANT are case sensitive.

Complex Build Script

Simple Build Script

Meta Script

Learning ANT

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?

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?

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.

• 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

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

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

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.

Tips

• 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.
• Parameters of the form "${classes.dir}" are not built-in magic. They are properties expanded inline, much like DOS %set variables. You will find a definition for them earlier in the script of the form:

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

Stomper

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

1. convoluted verbosity
2. atrocious manuals

1. 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.
2. It is much faster than doing the compiles with javac.exe.
3. It works. It is relatively bug free. Once you learn how it works, it is actually easier than writing the equivalent batch scripts.
4. 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

Books

	recommend book⇒Ant in Action
		paperback
	ISBN10:	1-932394-80-X
	ISBN13:	978-1-932394-80-1
	publisher:	Manning
	published:	2007-07-12
	by:	Steve Loughran and Erik Hatcher
Convert JUnit and extending the core tasks. This is not just a repackaging of the ANT documentation.
amazon.ca amazon.com chapters.indigo.ca powells.com amazon.fr barnesandnoble.com amazon.de amazon.co.uk

	recommend book⇒Pro Apache Ant
		hardcover
	ISBN10:	1-59059-559-9
	ISBN13:	978-1-59059-559-6
	publisher:	Apress
	published:	2005-11-16
	by:	Matthew Moodie
Step by step examples.
amazon.ca amazon.com chapters.indigo.ca powells.com amazon.fr barnesandnoble.com amazon.de amazon.co.uk

	recommend book⇒Ant: The Definitive Guide
		paperback
	ISBN10:	0-596-00184-3
	ISBN13:	978-0-596-00184-1
	publisher:	O’Reilly
	published:	2002-05-15
	by:	Jesse E. Tilly, Eric M. Burke
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.7.
amazon.ca amazon.com chapters.indigo.ca powells.com amazon.fr barnesandnoble.com amazon.de O’Reilly Safari amazon.co.uk