ANT : Java Glossary

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 (Operating Systems). You might think of it more as an XML-based scripting language than a simple make. Ant is not clever enough to figure out which classes it needs to include in a jar. An ANT-extension called Ivy, tackles that problems.

Advantages

• You don’t need to deal with the different :; classpath conventions or /\ conventions in different platforms. An ANT script runs on any platform that supports Java.
• ANT loads javac and keeps it resident. This vastly speeds up recompilation speed over a traditional make. Normally ANT just feeds all the source files to javac.exe, invoking it only once. This makes it far faster than javac.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.
• You can extend ANT with Java code that uses the ANT classes and interfaces, though this is a fairly esoteric undertaking.

Disadvantages

• 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.
• XML was never intended as a scripting language. It is torturous what the ANT people do with XML to write scripts in it. It is more unnatural than DOS (Disk Operating System) basic.
• ANT is multiplatform, but is unfortunately not suitable as a general purpose scripting tools like BASH (Bourne Again Shell). Learning it is a fair investment which unfortunately is limited to letting you write build scripts only.
• ANT is not clever about noticing that static final constants have changed, hence requiring recompiling all classes that use them. You must still manually do a clean compile to handle that.
• It would have made much more sense to write the scripts either in a true scripting language or in Java itself. Then you would automatically have at your disposal the full power of Java and a natural syntax for expressing a series of operations, conditional operations, operations on Collections etc. Writing the scripts in Java would also provide exceptional speed and compactness. Further, ANT would be much simpler since there would be no need to reinvent the scripting features such as nested ifs that Java has built-in.

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.8.0_131\.

If you use genjar, copy GenJar.jar and genjar.properties to "J:\Program Files (x86)\apache-ant-1.10.3\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

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

basedir

• The current directory when the ANT script was started?
• the directory where the build.xml script lives?
• J:\com\?
• J:\com\mindprod\?
• J:\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 J:\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

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"/>

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 J:\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.

Javac classpath

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

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:

  <!-- pause -->
  <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 %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

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.

Extracting Version Number from a File

Stomper

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

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