A Gentle Introduction to Ant

Build Tools
Creating a product from source may take several steps:
Compile Link Copy files to various directories Remove intermediate files Generate documentation

It becomes problematic to do all these steps manually, first of all because its boring, second because it is errorprone. The objective should be an automated tool that does all the work for you. Type or click one command and create a final product.
Copyright 2004, Java CoE, All Rights Reserved 2

Build Tools
There are a couple ways this can be done:
Write a batch file or script
The scripts tend to be hard to maintain

Use a tool designed for the task

Make Ant

Copyright 2004, Java CoE, All Rights Reserved

What is Ant?
Ant is a cross-platform, XML-based system for creating software products from source code. Open Source (development coordinated by the Apache Jakarta project)

Copyright 2004, Java CoE, All Rights Reserved

Why Ant?
Platform independent
Requires only a JDK 1.1 or later JVM

Easy to use
Built-in tasks accomplish all typical build functions User contributed tasks cover most other needs

Easy to extend
Creating a new Ant task is similar in scope to writing a servlet
Copyright 2004, Java CoE, All Rights Reserved 5

Structure of Ant
Project
a top level collection of targets

Property
an Ant variable

Target
a collection of tasks executed to achieve a particular purpose (a goal)

Task
a unit of Ant execution (a step)
Copyright 2004, Java CoE, All Rights Reserved 6

How Does Ant Work?

Each Project will have a build file (build.xml) Each build file will contain one or more Targets The Target to be executed:
Is either explicitly selected on the command line Or a project default Target is executed

Each Target is executed only once Each Target will contain one or more Tasks Some Tasks are executed conditionally Task are implemented as Java classes
7

Copyright 2004, Java CoE, All Rights Reserved

Properties
You can define variables so things like directory names arent hardcoded through your ant file.
<property description="Source directory" location="${basedir}/source" name="dir.src"/>

Copyright 2004, Java CoE, All Rights Reserved

Project
<project name="MyProject" default="dist" basedir="."> ... </project> The default attribute is required The name and basedir attributes are optional

Copyright 2004, Java CoE, All Rights Reserved

Targets
A target is something that needs to be donecreate initial directories, compile source, create javadoc, create jar files, etc. Targets can depend on other targets
The compile task can depend on an init task that creates directories for the products to land in

Copyright 2004, Java CoE, All Rights Reserved

10

Target
<target name="dist" depends="init" description="Makes a distribution" if="code-present" unless="time-is-short"> ... </target> The name attribute is required The depends, description, if and unless attributes are optional

Copyright 2004, Java CoE, All Rights Reserved

11

Target Dependencies
You can add a comma-delimited list of other targets that depend on this target. If the dependent target depends on other things, those will run, too.
<target name=init description=Create directories> </target> <target name="compile depends="init description=Compile Java sources> </target> <target name=jar depends=compile description=Create jar files> </target>
Copyright 2004, Java CoE, All Rights Reserved 12

Filesets
Often you want to specify a whole series of files, as with the classpath example, when many jar files needed to be specified Rather than individually name every jar file, you can specify a set of files, in this case in the lib directory and all subdirectories of the lib directory.
<classpath> <fileset dir="${dir.lib}" includes="**/*.jar"/> </classpath>

Copyright 2004, Java CoE, All Rights Reserved

13

Pattern-sets and File-sets

Pattern-sets
<patternset id="my.pattern"> <include name="**/*.java"/> <exclude name="**/*Test*"/> </patternset>

File-sets
<fileset dir="./source"> <patternset refid="my.pattern/> </fileset>

Copyright 2004, Java CoE, All Rights Reserved

14

Path-like Structures
Path
<path id="project.class.path"> <pathelement location="./lib"/> <pathelement path="${classpath}"/> </path>

Classpath
<classpath refid="project.class.path">

Can contain pattern-sets and file-sets

Copyright 2004, Java CoE, All Rights Reserved

15

A Simple Compile Task

Compile the source directory, put the results in the build/classes directory, and use the specified jar file
<target depends="init" name="compile"> <!--Compile everything in the source directory -> <javac destdir="${dir.build.classes}"> <classpath> <pathelement location=${lib.dir}/somelib.jar </classpath> <src path="${dir.src}"/> </javac> </target>

Copyright 2004, Java CoE, All Rights Reserved

16

A Simple build.xml File

<?xml version="1.0" encoding="UTF-8"?> <project name="Test" default=compile" basedir="."> <target name=compile"> <javac srcdir="."/> </target> </project>

This file will compile all .java files in the current directory and all its subdirectories that dont have corresponding .class files that are newer.
Copyright 2004, Java CoE, All Rights Reserved 17

Built-in Tasks
Ant AntCall AntStructure Apply Available Chmod Copy Cvs Delete Echo Exec ExecOn Fail Filter FixCRLF GenKey Get GUnzip
18

Copyright 2004, Java CoE, All Rights Reserved

Built-in Tasks (cont.)

Gzip Jar Java Javac Javadoc Mail Mkdir Move Patch Property Replace Rmic SignJar Sql Style Tar Taskdef Touch
19

Copyright 2004, Java CoE, All Rights Reserved

Built-in Tasks (cont.)

Tstamp Unjar Untar Unwar Unzip Uptodate War Zip

Copyright 2004, Java CoE, All Rights Reserved

20

Optional Tasks
ANTLR Cab Depend FTP JavaCC Javah JJTree Jlink JUnit JUnitReport Native2Ascii PropertyFile RenameExtensions Script Sound Stylebook Telnet Test
21

Copyright 2004, Java CoE, All Rights Reserved

Adding A Custom Task

Create a Java class that extends
org.apache.tools.ant.Task

Create a no-arg constructor for it

public MyTask() {}

Plan the attributes, text and child elements that your task element will use For each attribute, add a set method
public void setAttrName(type attrName)

type can be String or any Java primitive type

For text, add an addText method

public void addText(String text)
Copyright 2004, Java CoE, All Rights Reserved 22

Adding A CustomTask (cont.)

for each child element, add a create or add method
for empty child task elements
public ChildTask createChildTask()

for non-empty child task elements

public void addChildTask(ChildTask child)

add the method that implements the tasks

public void execute()

compile the class insure that it can be found using the CLASSPATH environment variable
Copyright 2004, Java CoE, All Rights Reserved 23

Resources
http://jakarta.apache.org/ant/
Ant home page

http://jakarta.apache.org/ant/manual/index. html
On-line Ant User Manual

http://jakarta.apache.org/ant/resources.ht ml
Links to articles, presentations, and FAQs
Copyright 2004, Java CoE, All Rights Reserved 24