Title: Everyone Hates build.xml

Author: Martin Moene

Date: 05 October 2014 21:52:51 +01:00 or Sun, 05 October 2014 21:52:51 +01:00

Summary: Using Ant build tool can be tricky. Andy Balaam shows how to structure and test the build code.

Body: 

If you’re starting a new Java project, I’d suggest considering the many alternatives to Ant, including Gant [Gant], Gradle [Gradle], SCons [SCons] and, of course, Make [Make]. This article covers how to bend Ant to work like a programming language, so you can write good code in it, and how to test that code.

It’s seriously worth considering a build tool that makes structured programming easier, but if you’ve chosen Ant, or you’re stuck with Ant, read on.

Most projects I’ve been involved with that use Ant have a hateful build.xml surrounded by fear. Many projects’ build files grow to enormous sizes, for example becoming responsible for deployment, system test execution, notifications and many other jobs.

The most important reason for the fear is that the functionality of the build file is not properly tested, so you never know whether you’ve broken it, meaning you never make ‘non-essential’ changes: changes that make it easier to use or read.

But, before we can write tests, we must address a pre-requisite:

Can you write good code in Ant, even if you aren’t paralysed by fear?

Everyone hates build.xml (code reuse in Ant)

One of the most important aspects of good code is that you only need to express each concept once. Or, to put it another way, you can re-use code.

I want to share with you some of the things I have discovered recently about Ant, and how you should (and should not) re-use code.

But first:

What is Ant?

Ant is 2 languages:

• A declarative language to describe dependencies
• A procedural language to proscribe actions

In fact, it’s just like a Makefile (ignore this if Makefiles aren’t familiar). A Makefile rule consists of a target (the name before the colon) with its dependencies (the names after the colon), which make up a declarative description of the dependencies, and the commands (the things indented by tabs) which are a normal procedural description of what to do to build that target.

  # Ignore this if you don't care about Makefiles!
  target: dep1 dep2   # Declarative
      action1         # Procedural
      action2

The declarative language

In Ant, the declarative language is a directed graph of targets and dependencies, shown graphically in Figure 1:

Figure 1

  <target name="A"/>
  <target name="B" depends="A"/>
  <target name="C" depends="B"/>
  <target name="D" depends="A"/>

This language describes a directed graph of dependencies. I.e. they say what depends on what, or what must be built before you can build something else. Targets and dependencies are completely separate from what lives inside them, which are tasks.

The procedural language

The procedural language is a list of tasks:

  <target ...>
      <javac ...>
      <copy ...>
      <zip ...>
      <junit ...>
  </target>

When the dependency mechanism has decided a target will be executed, its tasks are executed one by one in order, just like in a programming language. Except that tasks live inside targets, they are completely separate from them. Essentially each target has a little program inside it consisting of tasks, and these tasks are a conventional programming language, nothing special (except for the lack of basic looping and branching constructs).

I’m sorry if the above is glaringly obvious to you, but it only recently became clear to me, and it helped me a lot when thinking about how to improve my Ant files.

Avoiding repeated code

Imagine you have two similar Ant targets (see Listing 1).

<target name="A">
  <javac
    srcdir="a/src" destdir="a/bin"
    classpath="myutil.jar" debug="false"
  />
</target>

<target name="B">
  <javac
    srcdir="b/code" destdir="b/int"
    classpath="myutil.jar" debug="false"
  />
</target>
			

The classpath and debug information are the same in both targets, and we would like to write this information in one single place. Imagine with me that the code we want to share is too complex for it to be possible to store it as the values of properties in some properties file.

How do we share this code?

The wrong way: antcall

Listing 2 shows the solution we were using in my project until I discovered the right way.

<target name="compile">
  <javac
    srcdir="${srcdir}" destdir="${destdir}"
    classpath="myutil.jar" debug="false"
  />
</target>

<target name="A">
  <antcall target="compile">
    <param name="srcdir" value="a/src"/>
    <param name="destdir" value="a/bin"/>
  </antcall>
</target>

<target name="B">
  <antcall target="compile">
  ...
			

Here we put the shared code into a target called compile, which makes use of properties to access the varying information (or the parameters, if we think of this as a function). The targets A and B use the <antcall> task to launch the compile target, setting the values of the relevant properties.

This works, so why is it wrong?

Why not antcall?

antcall launches a whole new Ant process and runs the supplied target within that. This is wrong because it subverts the way Ant is supposed to work. The new process will re-calculate all the dependencies in the project (even if our target doesn’t depend on anything) which could be slow. Any dependencies of the compile target will be run even if they’ve already been run, meaning some of your assumptions about order of running could be incorrect, and the assumption that each target will only run once will be violated. What’s more, it subverts the Ant concept that properties are immutable, and remain set once you’ve set them: in the example above, srcdir and destdir will have different values at different times (because they exist inside different Ant processes).

Basically what we’re doing here is breaking all of Ant’s paradigms to force it to do what we want. Before Ant 1.6 you could have considered it a necessary evil. Now, it’s just evil.

The horrific way: custom tasks

Ant allows you to write your own tasks (not targets) in Java. So our example would look something like Listing 3 (Java) and Listing 4 (Ant).

// ... imports here ...
public class MyCompile extends Task {
  String srcdir;
  public void setSrcDir(String s) {
    srcdir = s;
  }
  String destdir;
  public void setDestDir(String d) {
    destdir = d;
  }
  public void execute() throws BuildException
  {
    Project p = getProject();
    Javac javac = new Javac();
    javac.setSrcdir( new Path( p, srcdir ) );
    javac.setDestdir( new File( destdir ) );
    javac.setClasspath( new Path( p,
                                  "myutil.jar" ) );
    javac.setDebug( false );
    javac.execute();
  }
}
			

<target name="first">
  <javac srcdir="mycompile"/>
  <taskdef name="mycompile" classname="MyCompile"
    classpath="mycompile"/>
</target>

<target name="A" depends="first">
  <mycompile srcdir="a/src" destdir="a/bin"/>
</target>

<target name="B" depends="first">
  <mycompile srcdir="b/code" destdir="b/int"/>
</target>
			

Here we write the shared code as a Java task, then call that task from inside targets A and B. The only word to describe this approach is ‘cumbersome’. Not only do we need to ensure our code gets compiled before we try to use it, and add a taskdef to allow Ant to see our new task (meaning every target gets a new dependency on the ‘first’ target), but much worse, our re-used code has to be written in Java, rather than the Ant syntax we’re using for everything else. At this point you might start asking yourself why you’re using Ant at all – my thoughts start drifting towards writing my own build scripts in Java ... anyway, I’m sure that would be a very bad idea.

The relatively OK way: macrodef

So, enough teasing. Listing 5 shows the Right Way.

<macrodef name="mycompile">
  <attribute name="srcdir"/>
  <attribute name="destdir"/>
  <sequential>
    <javac
      srcdir="@{srcdir}" destdir="@{destdir}"
      classpath="myutil.jar" debug="false"
    />
  </sequential>
</macrodef>

<target name="A">
  <mycompile srcdir="a/src" destdir="a/bin"/>
</target>

<target name="B">
  <mycompile srcdir="b/code" destdir="b/int"/>
</target>
			

Since Ant 1.6, we have the macrodef task, which allows us to write our own tasks in Ant syntax. In any other language these would be called functions, with arguments which Ant calls attributes. You use these attributes by giving their name wrapped in a @{} rather than the normal ${} for properties. The body of the function lives inside a sequential tag.

This allows us to write re-usable tasks within Ant. But what about re-using parts from the other language – the declarative targets and dependencies?

Avoiding repeated dependencies?

Imagine we have a build file containing targets like this:

  <target name="everyoneneedsme"...
  <target name="A" depends="everyoneneedsme"...
  <target name="B" depends="everyoneneedsme"...
  <target name="C" depends="everyoneneedsme"...
  <target name="D" depends="everyoneneedsme"...

In Ant, I don’t know how to share this. The best I can do is make a single target that is re-used whenever I want the same long list of dependencies, but in a situation like this where everything needs to depend on something, I don’t know what to do. (Except, of course, drop to the Nuclear Option of the <script> tag, which we’ll see later.)

I haven’t used it in anger, but this kind of thing seems pretty straightforward with Gradle. I believe Listing 6 is roughly equivalent to my example above, but I hope someone will correct me if I get it wrong.

task everyoneneedsme

tasks.whenTaskAdded { task ->
    task.dependsOn everyoneneedsme
}
task A
task B
task C
task D
			

(Disclaimer: I haven’t run this.)

So, if you want nice features in your build tool, like code-reuse and testability, you should consider a build tool that is integrated into a grown-up programming language where all this stuff comes for free. But, if you’re stuck with Ant, you should not despair: basic good practice is possible if you make the effort.

Everyone loves build.xml (test-driven Ant)

Of course, if you’re going to have any confidence in your build file you’re going to need to test it. Now we’ve learnt some basic Ant techniques, we’re ready to do the necessary magic that allows us to write tests.

First, let me clear up what we’re testing:

What do we want to test?

We’re not testing our Java code. We know how to do that, and to run tests, if we’ve written them using JUnit [JUnit], just needs a <junit> tag in our build.xml. (Other testing frameworks are available and some people say they’re better.)

The things we want to test are:

• build artifacts – the ‘output’ of our builds i.e. JAR files, zips and things created when we run the build,
• build logic – such as whether dependencies are correct, whether the build succeeds or fails under certain conditions, and
• units of code – checking whether individual macros or code snippets are correct.

Note, if you’re familiar with the terminology, that testing build artifacts can never be a ‘unit test’, since it involves creating real files on the disk and running the real build.

Below we’ll see how I found ways to test build artifacts, and some ideas I had to do the other two, but certainly not a comprehensive solution. Your contributions are welcome.

Before we start, let’s see how I’m laying out my code:

Code layout

build.xml      - real build file
asserts.xml    - support code for tests
test-build.xml - actual tests

I have a normal build file called build.xml, a file containing support code for the tests (mostly macros allowing us to make assertions) called asserts.xml, and a file containing the actual tests called test-build.xml.

To run the tests I invoke Ant like this:

  ant -f test-build.xml test-name

test-build.xml uses an include to get the assertions:

  <include file="asserts.xml"/>

Tests call a target inside build.xml using subant, then use the code in asserts.xml to make assertions about what happened.

Simple example: code got compiled

If we want to check that a <javac ...> task worked, we can just check that a .class file was created. Here’s the test, in test-build.xml:

  <target name="test-class-file-created">
    <assert-target-creates-file
      target="build"
      file="bin/my/package/ExampleFile.class"
    />
  </target>

We run it like this:

  ant -f test-build.xml test-class-file-created

The assert-target-creates-file assertion is a macrodef in asserts.xml like this:

  <macrodef name="assert-target-creates-file">
    <attribute name="target"/>
    <attribute name="file"/>
    <sequential>
      <delete file="@{file}" quiet="true"/>
      <subant antfile="build.xml" buildpath="."
              target="@{target}"/>
      <assert-file-exists file="@{file}"/>
    </sequential>
  </macrodef>

It just deletes a file (if it exists), runs the target using subant, then asserts that the file exists, which uses the macrodef in Listing 7.

<macrodef name="assert-file-exists">
  <attribute name="file"/>
  <sequential>
    <echo message=
       "Checking existence of file: @{file}"/>
    <fail message=
       "File '@{file}' does not exist.">
      <condition>
        <not><available file="@{file}"/></not>
      </condition>
    </fail>
  </sequential>
</macrodef>
			

This uses a trick I’ve used a lot, which is the fail task, with a condition inside it, meaning that we only fail if the condition is satisfied. Here we use not available which means fail if the file doesn’t exist.

Harder example: JAR file

Now let’s check that a JAR file was created, and has the right contents. Listing 8 is the test.

<target name="test-jar-created-with-manifest">
  <assert-target-creates-file
    target="build"
    file="dist/MyProduct.jar"
  />
  <assert-file-in-jar-contains
    jarfile="dist/MyProduct.jar"
    filename="MANIFEST.MF"
    find="Main-Class: my.package.MyMain"
  />
			

This just says after we’ve run the target, the file MyProduct.jar exists, and it contains a file called MANIFEST.MF that has the right Main-Class information in it.

assert-file-in-jar-contains looks like Listing 9, which basically unzips the JAR into a directory, then searches the directory using fileset for a file with the right name and contents, and fails if it’s not found (i.e. if the resourcecount of the fileset is zero). These are the kinds of backflips you need to do to bend Ant to your will.

<macrodef name="assert-file-in-jar-contains">
  <attribute name="jarfile"/>
  <attribute name="filename"/>
  <attribute name="find"/>
  <sequential>
    <!-- ... insert checks that jar exists, and
     contains file -->
    <delete dir="${tmpdir}/unzip"/>
    <unzip src="@{jarfile}"
           dest="${tmpdir}/unzip"/>
    <fail message="@{jarfile}:@{filename} should
          contain @{find}">
      <condition>
        <resourcecount when="equal" count="0">
          <fileset dir="${tmpdir}/unzip">
            <and>
              <filename name="**/@{filename}"/>
              <contains text="@{find}"/>
            </and>
          </fileset>
        </resourcecount>
      </condition>
    </fail>
    <delete dir="${tmpdir}/unzip"/>
  </sequential>
</macrodef>
			

Or, you can choose the Nuclear Option.

The Nuclear Option

If ant tasks just won’t do, since Ant 1.7 and Java 1.6 we can drop into a <script> tag. You ain’t gonna like it:

  <script language="javascript"><![CDATA[
    system.launchMissiles(); // Muhahahaha
  ]]></script>

The script tag allows us to use a scripting language as provided through the JSR 223 Java feature directly within our Ant file [DrDobbs], meaning we can do anything.

In all the JVMs I’ve tried, the only scripting language actually available is JavaScript, provided by the Rhino virtual machine [MDN], which is now part of standard Java.

When using the script tag, expect bad error messages. Rhino produces unhelpful stack traces, and Ant doesn’t really tell you what went wrong.

So now we know how to test the artifacts our build produces, but what about directly testing the logic in build.xml?

Testing build logic

We want to:

• Confirm that targets succeed or fail under certain conditions
• Check indirect dependencies are as expected
• Test a unit of Ant logic (e.g. a macrodef)

Success and failure

Listing 10 is a little macro I cooked up to assert that something is going to fail.

<macrodef name="expect-failure">
  <attribute name="target"/>
  <sequential>
    <local name="ex.caught"/>
    <script language="javascript"><![CDATA[
      try {
        project.executeTarget( "@{target}" );
      } catch( e ) {
        project.setProperty( "ex.caught", "yes" )
      }
    ]]></script>
    <fail message="@{target} succeeded!!!"
          unless="ex.caught"/>
  </sequential>
</macrodef>
			

I resorted to the Nuclear Option of a script tag, and used Ant’s Java API (through JavaScript) to execute the target, and catch any exceptions that are thrown. If no exception is thrown, we fail.

Testing dependencies

To check that the dependencies are as we expect, we really want to run ant’s dependency resolution without doing anything. Remarkably, ant has no support for this. But we can hack it in (see Listing 11).

<target name="printCdeps">
  <script language="javascript"><![CDATA[
    var targs = project.getTargets().elements();
    while( targs.hasMoreElements() )
    {
      var targ = targs.nextElement();
      targ.setUnless( "DRY.RUN" );
    }
    project.setProperty( "DRY.RUN", "1" );
    project.executeTarget( "targetC" );
  ]]></script>
</target>
			

(See ‘Dry run mode for Ant’ [Balaam] for more.)

Now we need to be able to run a build and capture the output. We can do that like Listing 12.

<target name="test-C-depends-on-A">
  <delete file="${tmpdir}/cdeps.txt"/>
  <ant
    target="printCdeps"
    output="${tmpdir}/cdeps.txt"
  />
  <fail message="Target A did not execute when
        we ran C!">
    <condition>
      <resourcecount when="equal" count="0">
        <fileset file="${tmpdir}/cdeps.txt">
          <contains text="targetA:"/>
        </fileset>
      </resourcecount>
    </condition>
  </fail>
  <delete file="${tmpdir}/cdeps.txt"/>
</target>
			

We use ant to run the build, telling it to write to a file cdeps.txt. Then, to assert that C depends on A, we just fail if cdeps.txt doesn’t contain a line indicating we ran A. (To assert a file contains a certain line we use a load of fail, condition, resourcecount and fileset machinery as before. This could do with some improvement to cover target names that overlap – for example ‘compile-a’ will be wrongly found if ‘test-compile-abc’ was run.)

So, we can check that targets depend on each other, directly or indirectly. Can we write proper unit tests for our macrodefs?

Testing ant units

To test a macrodef or target as a piece of logic, without touching the file system or really running it, we will need fake versions of all the tasks, including <jar>, <copy>, <javac> and many more.

If we replace the real versions with fakes and then run our tasks, we can set up our fakes to track what happened, and then make assertions about it.

If we create a file called real-fake-tasks.xml, we can put things like this inside:

  <macrodef name="jar">
    <attribute name="destfile"/>
    <sequential>
      <property name="jar.was.run" value="yes"/>
    </sequential>
  </macrodef>

and, in build.xml we include something called fake-tasks.xml, with the optional attribute set to true:

  <include file="fake-tasks.xml" optional="true"/>

If the target we want to test looks like this (in build.xml):

  <target name="targetA">
    <jar destfile="foo.jar"/>
  </target>

Then we can write a test like this in test-build.xml:

  <target name="test-A-runs-jar"
          depends="build.targetA">
    <fail message="Didn't jar!"
          unless="jar.was.run"/>
  </target>

and run the tests like this:

  cp real-fake-tasks.xml fake-tasks.xml
  ant -f test-build.xml test-A-runs-jar
  rm fake-tasks.xml

If fake-tasks.xml doesn’t exist, the real tasks will be used, so running your build normally should still work.

This trick relies on the fact that our fake tasks replace the real ones, which appears to be an undocumented behaviour of my version of Ant. Ant complains about us doing this, with an error message that sounds like it didn’t work, but actually it did (on my machine).

If we wanted to avoid relying on this undocumented behaviour, we’d need to write our real targets based on special macrodefs called things like do-jar and provide a version of do-jar that hands off to the real jar, and a version that is a fake. This would be a lot of work, and pollutes our production code with machinery needed for testing, but it could work with Ant’s documented behaviour, making it unlikely to fail unexpectedly in the future.

Summary

You can write Ant code in a test-driven way, and there are even structures that allow you to write things that might be described as unit tests.

At the moment, I am using mostly the ‘testing artifacts’ way. The tests run slowly, but they give real confidence that your build file is really working.

Since I introduced this form of testing into our build, I enjoy working with build.xml a lot more, because I know when I’ve messed it up.

But I do spend more time waiting around for the tests to run.

References

[Balaam] ‘Dry run mode for Ant’ on Andy Balaam’s blog http://www.artificialworlds.net/blog/2013/01/31/dry-run-mode-for-ant-ant-n-ant-dry-run/

[Gant] http://gant.codehaus.org/

[Gradle] http://www.gradle.org/

[DrDobbs] http://www.drdobbs.com/jvm/jsr-223-scripting-for-the-java-platform/215801163

[JUnit] http://junit.org/

[Make] http://www.gnu.org/software/make/

[MDN] https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino

[SCons] http://www.scons.org/

Notes: 

More fields may be available via dynamicdata ..