Insight > Software

Write custom tasks for Ant

In our previous article, we introduced Ant, the Java-based build tool. Ant was specifically designed to work with Java projects, and it benefits from being written entirely in Java. It works anywhere Java is installed, making it completely cross-platform.

However, being cross-platform means that Ant can't call external tools. While build tools like Make can use all the underlying shell tools to help in the build process, Ant has to rely on its built-in tasks alone. Most software builds can get by on the Ant's built-in tasks, but if you hit the limits of those tasks, you'll have to write your own. Fortunately, writing Ant tasks is simple. This article will get you started on writing your own tasks, and by the end, you’ll be ready to fully integrate Ant into your build system. Getting started
Writing an Ant task requires writing a new class that extends the Ant’s Task class. The class itself is simple. It contains a number of setter methods to set the class values and a method named execute () that returns null and throws BuildException. Each setter value corresponds to an attribute of the task tag in the build configuration. For example, the tag <tstamp/> would use no setters, but the tag <property name="dist" value="dist"/> would use setter methods setName () and setValue ().

Methods can take a variety of parameter types. Most commonly, you’ll accept the data type String, but you can pass any type that takes a string as a constructor, such as Integer. For Boolean data types, Ant will be intelligent about whether it calls the setter. If the value of the attribute in the build configuration is “yes,” “true,” or “on,” Ant will send the Boolean value true; otherwise, it will default to false.

Let’s start by looking at a simple task shown in Listing A. Our example will take the optional attributes message, message_count, and show_message. If show_message is true, the task will print the text message to the console message_count times. As you can see, each method takes a different data type as a parameter. The task will output using the log () method.

To compile this task, we need to compile the class against the Ant.jar file that shipped with Ant. To do this, we’ll use Ant to manage the build. If you’ve properly installed Ant, it will recognize all the Java Archive (JAR) files it needs in your $ANT_HOME/lib directory. Otherwise, you’ll need to specify the JAR files you need in the class path.

The resulting class file needs to be packaged as a JAR file and placed in $ANT_HOME/lib/.
Our build file will package the tasks and install them as MyTasks.jar. Listing B shows the build configuration that will do this for us.

To compile and install the SimpleTask.java (which should be in the src directory), we just need to run the command ant install.

Ensure that the JAR file has been properly installed by looking for MyTasks.jar in your $ANT_HOME/lib directory. Assuming that the JAR file has been installed properly, we can now try out our new class. First, we need to tell Ant to import it. In the build configuration, add the following line:
<taskdef name="Simple" classname="SimpleTask"/>

This tells Ant that it should define a task called Simple from the class SimpleTask. (It will resolve the location of SimpleTask by looking in its class path.) You can name the definition to whatever suits your needs.

Once you’ve defined the task, you need to use it. You can do this by calling Simple anywhere in the build configuration. To test the process, let’s create a new target called SimpleTarget, as shown in Listing C.

If you remember, the SimpleTask iterates a message multiple times if the show_message Boolean was set. So when you run ant SimpleTarget, you get output like Listing D.

Now, let’s look at how Ant deals with exceptions.

Dealing with exceptions
When your task hits a critical error—one where building must stop—you need to throw an exception. When Ant receives a BuildException from a task, it stops the compilation and dumps out the error message. Let’s look at the simple exception example shown in Listing E.

As you can see, the task simply throws an exception. But it isn't the code that's interesting here; it's the impact it has on the build. Figure A shows the changes to the build configuration.

Figure A

Changes to the build configuration

Now, take a look at the output from running ant ExceptionTarget.

Figure B

Output from ant ExceptionTarget

As you can see, Ant tells you that the build failed, where the exception was, and which target it was currently in. Let’s turn our attention to dealing with property values.

1 2 Next