Ant ClearCase Integration

In terms of its integration with ClearCase, the Ant distribution already has a number of predefined tasks. These tasks are basically interfaces to the ClearCase cleartool command, with command-line options made available as task attributes. The complete list of tasks can be found online at http://ant.apache.org/manual/OptionalTasks/clearcase.html. Using these tasks to interface with ClearCase is quite straightforward. First, think of the commands you want to invoke (as cleartool subcommands) and the arguments that the commands need. Use the cleartool man pages to help you (such as cleartool man lock to look up the options for the lock command). Then map this command and its options to the particular Ant task that implements it. For example, suppose that, as part of your build process, you want to update the build snapshot view, lock the integration branch, and check out a file (that records the build version). A target to do this might look something like this:

<target name="clearcase-pre" depends="init"     description="execute ClearCase pre compile commands">     <!-- update snapshot view -->     <ccupdate viewpath="${user.dir}\.." graphical="false"         overwrite="true" currenttime="true"/>     <!-- lock the build branch -->     <cclock objsel="brtype:project_int"         replace="true" nusers="ccadm"/>     <!-- checkout files to be updated -->     <cccheckout viewpath="src/com/ratlbank/model/Bank.java"         reserved="true" notco="false"/> <target>

This set of commands is functionally equivalent to the following ClearCase cleartool commands:

• cleartool update -graphical -overwrite -ctime <directory_ location>

• cleartool lock brtype:project_int -replace -nusers ccadm

• cleartool checkout -nc -reserved src/com/ratlbank/model/Bank.java

However, one of the problems with this set of tasks is that a Java class exists for each cleartool command. This sounds fine in practice and allows a degree of argument checking. However, the caveat is that whenever IBM Rational Software adds or updates a cleartool subcommand, this integration becomes out of date and needs to be reworked. Similarly, the existing tasks do not support some of Ant's more powerful features, such as support for the <fileset> element. A complementary approach is to use the third-party library clearantlib, which is described next.

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: http://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 JavaTools 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:

>cd C:\Views\javatools_int\JavaTools\ant\src\clearantlib-src-x.x >set ANT_HOME=C:\Views\javatools_int\JavaTools\ant >ant install

or the following on Linux/UNIX:

>cd /Snapshot_views/javatools_int/JavaTools/ant/src/clearantlib-src.x.x >export ANT_HOME=/Snapshot_views/javatools_int/JavaTools/ant >ant install

The second line is used to set the environment variable ANT_HOMEthe 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:

<?xml version="1.0"?> <project name="RatlBankModel" default="main" xmlns:ca="antlib:net.sourceforge.clearantlib"> <target name="main">     <ca:ccexec failonerror="true" output="ccexec.out">          cleartoolpath="C:\Program Files\Rational\ClearCase\bin">         <arg value="describe" />         <arg value="-long" />         <arg value="build.properties" />     </ca:ccexec> </target>

As you can see, this new Ant task called <ccexec> 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:

<?xml version="1.0"?> <project name="RatlBankModel" default="main" xmlns:ca="antlib:net.sourceforge.clearantlib"> <target name="main">     <ca:ccapply failonerror="true" maxparallel="5">         <arg value="checkin"/>         <arg line="-nc -ident"/>         <fileset dir="${dir.src}">             <include name="**/*.java"/>         </fileset>     </ca:ccapply> </target> </project>

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 <ccapply> 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 <apply> tasks in the Ant manuals, because the <ccapply> task inherits all of its properties.

The <ccexec> and <ccapply> 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 libraryin 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.