Apache Ant Best Practices | Page 5

Apache Ant Best Practices

Downloading and Installing clearantlib

clearantlib is a ClearCase Ant integration library in the form of an Ant antlib. An antlib is a prebuilt library that you can plug in to Ant without recompilation. It is simply a set of classes referred to by an XML namespace and then referenced just like any other Ant task or type. This makes it easy to integrate a set of tasks with a prebuilt version of Ant, such as the version of Ant included with Eclipse, Rational Application Developer, or CruiseControl. If you develop your own set of additional Ant tasks, it is definitely worth putting them in an antlib so that you don't have to recompile Ant each time you download and install a new version.

Antlib Support

Only Ant version 1.6 and later support the antlib format, so you need to make sure the environment or tools you are using are similarly aligned.

To install clearantlib, first download and extract the source distribution from the Web site: https://clearantlib.sourceforge.net. There should be a link to a page for downloading the source distribution. In this case you will download the zip file clearantlib-src-x.x.zip(or the latest version of clearantlib). Extract this file to a directory. I recommend putting it in your Java-Tools ant/src directory. You can add this directory to source control too if you make any changes to the distribution. You should then have a structure similar to that shown in Figure 5.1.

Figure 5.1 Antlib build directory structure

Once this is complete you can then build and install clearantlib in the standard manner. To do this, go to the command line and execute the following commands on Windows:

or the following on Linux/UNIX:

The second line is used to set the environment variable ANT_HOME—the root directory for your previously installed copy of Ant. The Ant build script looks for this environment variable and installs the clearantlib library (clearantlib.jar) in the Ant lib directory as part of the installation process. Note that these steps assume that the javatools_int view created in Chapter 3 is still available. Note also that the exact Linux/UNIX assignment of this variable depends on the shell being used (the preceding example is for the Bourne/Korn shell). I recommend adding the library to version control at this stage too.

Using the Library

To use the library you create a build.xml file for your applications as normal and also refer to antlib's XML namespace. This is illustrated in the following example, which simply executes a cleartool describe on the file build.properties and redirects the output to the file ccexec.out:

As you can see, this new Ant task called takes any number of nested elements representing the arguments to the ClearCase cleartool command. The task also has an attribute called failonerror, which in this example is set to true. This specifies that Ant should terminate the build if this particular command fails. You can use the optional attribute cleartoolPath to specify the directory location where the ClearCase cleartool command can be found.

Alternatively, if you wanted to check in the complete set of Java files in the src directory, you could write an Ant target similar to the following:

In this example, the additional attribute maxparallel specifies how many elements should be passed to each cleartool invocation. For example, if 20 files needed to be checked in, four cleartool commands would be executed, each with five arguments. Normally, you would want as many files to be passed to a single cleartool command as possible. However, this might cause problems on operating systems (such as some versions of Windows) where command-line lengths are limited. maxparallel is a good way of circumventing this. The task has a number of additional inherited and potentially useful capabilities, such as transforming the names of the input (source) files to the output (target) files using regular expression "mappers." Some of these capabilities will be used later in this book. For more information on these capabilities, refer to the Ant tasks in the Ant manuals, because the task inherits all of its properties.

The and tasks are the two most basic tasks that clearantlib supports and that I use in this chapter. Later in the book, however, I will look at how to use more of the tasks in this library—in particular, to help with the reporting and releasing process. For more information on the tasks that are included with clearantlib, see the man pages that come with the distribution.

Project Support

All the Ant build.xml files that have been created so far have been quite simple. These files might suffice for building small Java projects, but the real world is not always so simple. You are probably wondering how Ant scales to projects with multiple components and a large code base. This section covers this issue and describes some of the capabilities and techniques that you can use for large or complicated projects.

"This content is excerpted from the new book titled, "IBM Rational ClearCase, Ant, and CruiseControl: The Java Developer's Guide to Accelerating and Automating the Build Process", authored by Kevin A. Lee. The content represents pages 81 to 91, from the chapter, "Apache Ant Best Practices". The book published by IBM Press in June, 2006, Copyright 2006 by International Business Machines Corporation. All rights reserved. Reprinted with permission from Pearson Education. ISBN 0-321-35699-3. For further information, please visit: www.ibmpressbooks.com."

URL: