ANT (Another Neat Tool)

ANT is a tool for automating software build processes, implemented in Java, and best suited to build Java projects. Ant uses an XML file to describe the build process and its dependencies.

Ant is an Apache project, it is open source software, released under the Apache Software License

Project Template

Here follows a simple buildfile that:

• initializes properties and classpath
• compile java classes
• build jar and javadoc

<?xml version="1.0" encoding="UTF-8"?>
<project name="project" default="build" >
    <description>simple project buildfile</description>
 
    <target name="init"
        description="initialize properties and classpath">
        <property name="dir.sources" value="src"/>
        <property name="dir.lib" value="lib"/>
        <property name="dir.build" value="build"/>
        <property name="dir.build.classes" value="${dir.build}/classes"/>
        <path id="classpath.project">
          <fileset dir="${dir.lib}"></fileset>
        </path>
    </target>
 
    <target name="build" depends="compile"
        description="builds the project">
        <jar jarfile="${dir.build}/jar/${ant.project.name}.jar">
          <fileset dir="${dir.build.classes}" includes="**" />
          <manifest/>
        </jar>
      <javadoc destdir="${dir.build}/doc">
        <fileset dir="${dir.sources}" defaultexcludes="yes" includes="**/*.java"/>
      </javadoc>
    </target>
 
    <target name="compile" depends="init"
        description="compile java classes">
      <javac srcdir="${dir.sources}" destdir="${dir.build.classes}">
        <classpath refid="classpath.project"/>
      </javac>
    </target>
 
</project>

Ant Introduction

ANT is a tool for automating software build processes, implemented in Java, and best suited to build Java projects. Ant uses an XML file to describe the build process and its dependencies.

Ant is an Apache project, it is open source software, released under the Apache Software License.

Simple project template

Here follows a simple buildfile that

• initializes properties and classpath
• compile java classes
• build jar and javadoc

<?xml version="1.0" encoding="UTF-8"?>
<project name="project" default="build" >
    <description>simple project buildfile</description>
  
    <target name="init"
          description="initialize properties and classpath">
        <property name="dir.sources" value="src"/>
        <property name="dir.lib" value="lib"/>
        <property name="dir.build" value="build"/>
        <property name="dir.build.classes" value="${dir.build}/classes"/>
        <path id="classpath.project">
          <fileset dir="${dir.lib}" includes="*.jar"/>
        </path>
    </target>
  
    <target name="build" depends="compile"
          description="builds the project">
        <jar jarfile="${dir.build}/jar/${ant.project.name}.jar">
          <fileset dir="${dir.build.classes}" includes="**" />
          <manifest/>
        </jar>
      <javadoc destdir="${dir.build}/doc">
        <fileset dir="${dir.sources}" defaultexcludes="yes" includes="**/*.java"/>
      </javadoc>
    </target>
  
    <target name="compile" depends="init"
          description="compile java classes">
      <javac srcdir="${dir.sources}" destdir="${dir.build.classes}">
        <classpath refid="classpath.project"/>
      </javac>
    </target>
  
</project>

below we present a small list with common ant task.

Simple tasks – Properties, paths and initialization

A small list of common and widely used ant tasks

Properties

Usually you work with a list of properties that defines file, folders and project variables. below two examples of property definition:

<!-- simple property definition -->
<property name="packages-prefix" value="test-archive"/>
<!-- properties loaded by property file -->
<property file="buildfile.properties"/>

The second example import all properties from the externam file buildfile.properties

Paths

Another important issue is to define classpath to use inside your projects. The example shows the definition of a classpath

<path id="classpath.build">
  <fileset dir="${dir.lib}/*.jar" />
</path>

In large projects, may be that you have to define multiple classpaths: one for compile, one for test, etc.

Init – create / delete dirs

Initialization means create or delete directories. An example, frequently used, is the creation of a particular directory structure, ot the deletion of directories containing generated artifacts. The code below shows example of creatin an deleting files/folders.

<delete dir="${dir.build}" includeemptydirs="true" includes="**/*"/>
<mkdir dir="${dir.build}/html" />
<mkdir dir="${dir.build}/fo"/>
<mkdir dir="${dir.build}/pdf"/> 

Common tasks

Here I lisk most common tasks

Javac – java compile

Javac, compile java classes from srcdir to destdir, using the specified classpath. You could also define exclusion filter, compilation level and other parameters. Below there is an example of more complete call to <javac/> task

<javac srcdir="${dir.sources}" destdir="${dir.build.classes}"
    excludes="**/test/**" debug="true"
    target="1.6" source="1.6" encoding="UTF-8" includeantruntime="false">
    <classpath refid="project.class.path" />
    <compilerarg value="-Xlint:unchecked" />
</javac>

Jar – java archive

the Jar task is used to build a *.jar* archive from compiled source and other resources. Below there is an invocation of ant task, with

<jar jarfile="${dir.build}/jar/${name.archive}"
    defaultexcludes="yes" update="true">
  <fileset dir="${dir.resources}/jar/includes" />
  <fileset dir="${dir.build.classes}/"
    includes="**/*.class,**/*.xml,**.properties"
    excludes="**/test/**" />
  <manifest file="${dir.resources}/jar/manifest.mf" />
</jar>

XSL – Xml Transformation

The xsl task performs an XML transformation on provided documents. Below there is an example that passes input parameters to the transformation

<xslt basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.xsl">
  <param name="date" expression="07-01-2000"/>
</xslt>

If you need to use more complex features, like specifyng a catalog, use factory settings, or other; please read the ant manual > xslt task

Other tasks

path & fileset

<path id="test.class.path.run"> 
  <fileset dir="${dir.lib}/compile">
    <include name="*.jar"/>
    <exclude name=".jar" />
  </fileset>
  <fileset dir="${dir.lib}/test">
    <include name="*.jar"/>
    <!--<exclude name="${jboss-libs}"/>-->
  </fileset>  
  <!--<pathelement location="${jboss-common-lib}/antlr.jar"/>-->
  <!--<fileset dir="D:\workspace\emergency.room.backend\lib\test" includes="*.jar"/>-->
  <pathelement location="${dir.build.classes}"/>
   
</path>

copy

copy task example: Copy a set of files to a local directory

<copy todir="E:\opt\myserver\default\deploy">
  <fileset dir="${dir.build}/jar" includes="*.jar" />
  <fileset dir="${dir.build}/config" includes="*.xml" />
</copy>

ftp

ftp task example: uploads a set of files, via ftp, to a server

<ftp server="192.168.100.200" userid="myuser" password="***" action="put">
  <fileset dir="${dir.build.ear}" includes="*.ear" />
  <fileset dir="${dir.build.config}/ds/test/oracle" includes="*-ds.xml" />
</ftp>

Advanced Tasks

If you want to write more complex tasks, I suggest two steps:

1. Read Ant’s documentation. The most important is linked in references
2. Explore the source code of apache ant,

References

• http://ant.apache.org/
• http://en.wikipedia.org/wiki/Apache_Ant
• http://www.apache.org/