Ant template

Apache ANT is a very powerful JAVA based tool equivalent to UNIX make utility. ANT advantage above Make is that it is platform independent in both execution and in extensions. The disadvantage is that you need JAVA to run ANT.

This article creates a template for ANT-scripts which make script portable across platforms and hardware. The template uses 3 files:

1. Ant build file, the file made by the end-user. A template is described below.
2. local.xml, a file containing information of the system Ant is working on.
3. common.xml, a generic script which can be used by every ant-end-user-xml file.

Requirements

To create and run this example, the following software is needed:

• Java, See http://java.sun.com/javase/downloads/index.jsp .
• Ant, See http://ant.apache.org
• Ant Contrib, See http://ant-contrib.sourceforge.net .

Version information

The version covered in this article are:

• build/template, 1.0.1.1 - 29 Jan 2008.
• local.xml, 1.0.3.1 - 29 Jan 2008
• common.xml, 1.0.5.1 - 28 Jan 2008

File-relation

Explanation The left image shows the relations, imports, includes, locations and additional libraries. The user made build.xml file imports the local.xml (located in the UNIX like-style c:/usr/home/script). The local.xml files imports the generic.xml file (also located in UNIX like-style c:/usr/home/script). Another requirements is the use of the ant-contrib library. I am using a custom made version of my own ant-contrib-hf.jar. The location of this file is depended of the used version of ANT. Use a relative path with respect to the environment ANT_HOME. Most common the developer/user needs to set its own version into the ANT distribution. Unix vs Windows The common.xml has a build-in-mechanism based on the USR_PackardBell location on UNIX and windows to find the correct ant-contrib library. Since my usage of windows is almost zero, the windows implementation is not maintained and tested, the UNIX/OSX is however up-to-date. See the sources for the details. Recommendations To avoid specific settings the windows-environment variable HOMEDRIVE and HOMEPATH are not used. One of the reasons is that Documents and Settings contain spaces. The use of UNIX like directories makes the scripts also more versatile to use on different platforms. In windows use command-files instead of control panels settings for the setting of environment variables. See Windows command templates. So you can easily have different versions of JAVA and ANT installed.

Template Build file

The End-User build file uses version information. I can not stress enough to make use of this functionality for your own convenience, but the user is free to do it.

  <property name= "build.version.number"  value= "1.0.1.1"           />
  <property name= "build.version.date"    value= "29 Jan 2008 22:00" />
  <property name= "stopwatch.name"        value= "template"          />

Before doing anything, it is necessary to include the local.xml file. The location of the local.xml will be somewhere in a directory on your computer/network. In the XML-scripts the UNIX like style is used and may also be used on Windows systems, because ANT is smart enough to replace the correct working way on your system. In this example 3 different locations are used (as they appear on my home systems):

• UNIX/Apple Mac style: /Data/USR_PackardBell/home/script
• Windows Removable Hard-Disk: F:/Users/Data/USR_PackardBell/script
• Windows Local Hard Disk: C:/usr/home/script

This part of the script is platform depended. Since the 'common' knowledge has been put inside the scripts that are imported, a chicken or the egg problem arises. A little trick is used here check the availability of the directories then set the import variable. First the Apple Settings then the removable HD then the local HD. Please be aware the order is important.

  <available file      = "/Users/Shared/Data/USR_PackardBell/home/script"
             type      = "dir"
             property  = "build.localxml.loc"
             value     = "/Data/USR_PackardBell/home/script" />
  <available file      = "F:/Users/Data/USR_PackardBell/script"
             type      = "dir"
             property  = "build.localxml.loc"
             value     = "F:/Users/Data/USR_PackardBell/script" />
  <available file      = "C:/usr/home/script"
             type      = "dir"
             property  = "build.localxml.loc"
             value     = "C:/usr/home/script" />

After the discovery of the correct place of the file, the import can be made:

  <import file="${build.localxml.loc}/local.xml" />

Init

The ANT Build File (ABF) will have to init the code in the local and common xml files. All callable targets need to be dependent of the initial target. To illustrate this behavior look at the following:

ABF or user build file

Local.xml

<project name="Example Project initialization method" default="all" basedir="."> ... <!-- ======================================================= --> <!-- Default task, does it all --> <!-- ======================================================= --> <target name="all" description="Do-It all" depends="initial, help, show, lacieB2lac1t, lac1t2lacieB"> </target> <!-- ======================================================= --> <!-- All tasks should be depended on this initial task --> <!-- ======================================================= --> <target name="initial" depends="local.init"> <!-- Initial settings here --> </target> ... </project>

<project name="local"> ... <!-- ======================================================= --> <!-- Initial tasks. Always call this tasks before any other --> <!-- The user build.xml should include a dependency for this --> <!-- task --> <!-- ======================================================= --> <target name = "local.init" depends = "internal.local.availability, timestamp"> </target> <!-- ======================================================= --> <!-- Sets the availability variables by checking the --> <!-- availability-tests --> <!-- ======================================================= --> <target name = "internal.local.availability" depends = "timestamp, getos, avail-windows, avail-unix" description= "Checks availability ..., aborts if wrong!"> <fail unless="java.home.found" message="No JAVA_HOME specified!" /> <trycatch> <try> <antcall target="internal.test.availability"> <param name="param" value="lacie"/> </antcall> </try> <catch> <property name="lacie.isaDir" value="false"/> </catch> </trycatch> ... </target> ... </project

All local computer system variables are coded in the local.xml file. The local.init calls a ant-target which determines the availability of the drives on the system. See the Drive availability below.

In the above example also other dependencies are shown:

1. getos, Gets the Operation system and sets isUnix or isWindoze.
2. avail-windows
3. avail-unix

Help

It is a good idea to give the user help-information. In this case:

  <target name="help"
          description="Shows help information">
     <echo>--------------- Help Template -----------------------------------</echo>
     <echo>See the readme.txt</echo>
     <echo>Internet: http://www.harmfrielink.nl/wiki/index.php/Ant_template</echo>
     <echo>=================================================================</echo>
  </target>

Show

And to show something use the show option:

  <target name="show"
          description="Shows properties of build, common and local script files."
          depends= "initial, internal.local.show.properties, internal.show.properties" >
     <echo>--------------- Build variables ---------------------------------</echo>
     <echo>Build Version : ${build.version.number} - ${build.version.date}</echo>
     <echo>=================================================================</echo>
     <echo>You can overrule the variables by using the -D command-line</echo>
     <echo>option. An example:</echo>
     <echo>ant -Dziplocation=c:\foo -Dzipfilename=Increment.zip</echo>
  </target>

The output may look something like this:

 C:\usr\home\script>ant -q -f template.xml
    [echo] --------------- Help Template -----------------------------------
    [echo] See the readme.txt
    [echo] Internet: http://www.harmfrielink.nl/wiki/index.php/Ant_template
    [echo] =================================================================
    [echo] --------------- Local Used Properties ---------------------------
    [echo] Local Version : 1.0.3.1 - 29 Jan 2008
    [echo] Local HD      : available as C:
    [echo] IBM Laptop    : NOT available!
    [echo] LaCie         : NOT available!
    [echo] USB Stick     : NOT available!
    [echo] Achmea Data   : NOT available!
    [echo] DTH Maxtor    : available as H:
    [echo] DTH Lacie2    : available as L:
    [echo] LaCie ND      : available as Z:
    [echo] --------------- Common Used Properties --------------------------
    [echo] Common Version: 1.0.5.1 - 28 Jan 2008
    [echo] Common CR     : HJMF 2000-2008
    [echo] Granularity   : 5500
    [echo] Last modified : true
    [echo] --------------- Environment Variables ---------------------------
    [echo] ANT_HOME      : c:\apache-ant-1.6.5
    [echo] ANT_VERSION   : 1.6.5
    [echo] CLASSPATH     : .;C:\Program Files\Java\jre1.6.0_03\lib\ext\QTJava.zip
    [echo] JAVA_HOME     : C:\Program Files\Java\jdk1.5.0_08
    [echo] JAVA_VERSION  : 1.5.0_08
    [echo] User name     : Administrator
    [echo] Windows root  : C:\WINDOWS
    [echo] Run Date-Time : 30 jan 2008  10:08:05 (dutch)
    [echo] -----------------------------------------------------------------
    [echo] --------------- Build variables ---------------------------------
    [echo] Build Version : 1.0.1.1 - 29 Jan 2008 22:00
    [echo] =================================================================
    [echo] You can overrule the variables by using the -D command-line
    [echo] option. An example:
    [echo] ant -Dziplocation=c:\foo -Dzipfilename=Increment.zip

 BUILD SUCCESSFUL
 Total time: 3 seconds
 C:\usr\home\script>

Drive availability

A very specific part of the scripts is the ability to check for the availability of drives to the computer, an extremely convenient part of the Ant scripting. This section describes how to to add a drive to the Drive Availability recognition script.

1. Add the drive defininition. Specify the 'letter, name, dpid and user'.
2. Add the Availability properties. Specify the isaDir file or directory check.
3. Add the Check availability test. Specify a try catch block for the drive.
4. Add the drive to the internal.local.show.drives target.

Add drive definition

The drive definition looks like:

  <property name="localhd.letter"        value="C:" />
  <property name="localhd.name"          value="Local HD     "  />
  <property name="localhd.dpid"          value="usr/CHICON_HJMF_LOCALHD" />
  <property name="localhd.user"          value="usr" />
  <property name="localhd.dpiddir"       value="dir"        />

A new definition can be given using another name for localhd. The part after the dot (.) has to be the same for all definitions. The meaning:

Definition	Description
XXX.letter	The letter of the drive with semi-colon and without dash.
XXX.name	The name of the drive will be used in the show target.
XXX.dpid	This is the check dir/file for the specific drive. The directory have to exist. Make the name as unique as possible.
XXX.user	The user directory of the drive. The directory have to exist.
xxx.dpiddir	Specifies if the given dpid is a file or a dir. Possible options are file or dir.

Add availability properties

The availability property are the placeholders for the available drives and look like:

  <available property="localhd.isaDir"  file="${localhd.letter}/${localhd.dpid}"   type="${localhd.dpiddir}"  />

A new definition can be given using another name for localhd. The part after the dot (.) has to be the same for all definitions. The meaning:

Definition	Description
XXX.isaDir	Placeholder for the availability for the drive definition of XXX.
XXX.letter	The drive letter, see above.
XXX.dpid	This is the check dir/file for the specific drive. The directory have to exist. Make the name as unique as possible. See above
xxx.dpiddir	Specifies if the given dpid is a file or a dir. Possible options are file or dir. See above.

Add check availability test

These Ant scripts code part tests the drive availability and sets te variable to true or false:

  <target name       = "internal.local.availability"
          depends    = "timestamp, getos, avail-windows"
          description= "Checks availability of required builds/jars, aborts if wrong!">
     <fail unless="java.home.found"  message="No JAVA_HOME specified or wrong!"  />
     <trycatch>
        <try>
           <antcall target="internal.test.availability">
              <param name="param"  value="localhd"/>
           </antcall>
        </try>
        <catch>
           <property name="localhd.isaDir" value="false"/> 
        </catch>
     </trycatch>  

The localhd has to be replaced (2x) by the used definition (the parts before the dot (.)).

Add drive to show

This Ant script part shows the availability of the drive in the internal show option.

  <target name="internal.local.show.drives" >
     <antcall target="internal.show.availability" >
        <param name="param"   value="localhd"   />
     </antcall>            

Replace the localhd by the used drive definition.

Example files

• build.xml, the template build file
  • bu.xml, Riet Example build file (private access).
• local.xml, the local definition file
• common.xml, the generic code file.

See also

• Windows command templates, a description of using windows command templates for setting environment variables and launching parallel versions.