Introduction to Ant

1
Introduction to Ant

• James Brucker

2
What is Ant?

• Ant is a build tool -- it builds software
  according to a set of rules.
• Ant can determine which products depend on which
  sources, and only build the parts that are
  out-of-date.
• An Apache Jakarta project
• Jakarta is an umbrella heading for all the Java
  related Apache projects
• Open source, Apache License
• Project Home http//ant.apache.org/

3
Example of Using Ant (1)

• Here is a project with a "build.xml" file it the
  project directory. First we try asking for help
  on the build tasks

cmdgt ant help echo Usage ant target
echo echo target is one of echo
clean - delete files from the build
directory echo build - compile
java source code echo buildall -
recompile everything (clean first) echo
dist - create a distribution in dist
directory echo javadoc - create Javadoc
in doc/api dir echo test - run
unit tests
Note many build.xml files don't have a "help"
task, so they may not print this message.
4
Example of Using Ant (2)

• We see there is "build" target, so we use it to
  compile the source

cmdgt ant build init mkdir Created dir
world/build copy Copying 1 file to
world/build build javac Compiling 8
source files to build/classes javac
Compiling 3 source files to build/test-classes BU
ILD SUCCESSFUL
Ant performs the "init" target
Ant performs the "build"
The build.xml file told Ant that it must run the
"init" target before the "build" target, so we
see output from two tasks.
5
Example of Using Ant (3)

• Since "build" succeeded, we can try creating a
  jar file (dist).

cmdgt ant dist init build dist mkdir
Created dir dist jar Building jar
dist/world-1.0.jar copy Copying 2 files to
world/dist BUILD SUCCESSFUL
"dist" requires that the "init" and "build" task
be performed, but Ant sees that these targets are
already up-to-date, so it does nothing
The build.xml file told Ant that "dist" depends
on "init" and "build", but the output from these
targets exist and are up-to-date.
6
Typical Development Cycle

• The typical work cycle for building a project
  with Ant is

build compile sources
dist create runnable product
test run unit tests
test-report generate reports
7
A Little History

• For years (decades) developers have used a
  program called "make" to automate project builds.
• Make gets information from a Makefile.
• Example Apache web server
• download the source code for Apache httpd
• unzip or untar the source code
• in the top source directory type configure
• then type make
• wait (it may take several minutes)
• type make install

8
Ant a modern "make"

• Makefile designed for humans to read and edit.
  Not optimal for processing by software.
• Make is written in terms of processing
  instructions for types of files, plus
  application-specific "tasks". Example
• build object (.o) files from C (.c) file
• .o .c
• CC -c CFLAGS lt
• Ant allows developers to define there own rules,
  and has a more expressive syntax.
• Ant uses XML for rules file easier for software
  to read and write.

9
Installing Ant

• Windows
• Download from http//ant.apache.org/
• Unzip to a convenient directory (no spaces
  preferred).I use D\lib\ant
• Add ant-dir\bin to the PATH. I use
• ANT_HOMED\lib\ant
• PATHPATHANT_HOME\bin
• Ubuntu Linux
• "apt-get install ant" will install the GNU Java
  and lots of other packages. Don't do it!
• Download Ant from ant.apache.org, unzip (e.g.
  /opt), and add to your path. This way you can
  use Sun's JRE.

10
Test the Installation
DOS-Never-Diesgt ant -help ant options target
target2 target3 ... Options -help, -h
print this message -version
print the version and exit -quiet, -q
be extra quiet -verbose, -v be
extra verbose -logfile ltfilegt use given
file for log -buildfile ltfilegt use given
buildfile -f ltfilegt -file ltfilegt ''
-Dltpropertygtltvaluegt use value for given
property -keep-going, -k execute all
targets that do not
depend on failed target(s) -propertyfile ltnamegt
load all properties from file
If you get a "command not found" message, then
ant/bin isn't on your PATH. If java is not
found, then the JDK "bin" directory isn't on your
PATH.
11
Sample Application

• World/ project folder
• build.xml Ant build file
• src/ source code
• world/
• domain/
• City.java
• ...
• test/ test source
• world/
• domain/
• CityTest.java
• build/ build products
• classes/ java classes
• dist/ final products
• world-1.0.jar
• lib/ dependent jars
• mysql-connector-bin.jar

12
A Simple Ant Build file

• The default build file name is build.xml

ltproject name"World" basedir"."gt
ltdescriptiongt World country facts using
JDBC lt/descriptiongt lt!-- classpath for
required jar files --gt ltpath id"classpath"gt ltf
ileset dir"lib"gt ltinclude name"/.jar"/gt
lt/filesetgt ltpathelement location"build/classes"
/gt lt/pathgt
13
A Simple Ant Build file (2)

• The actual work is defined in "targets"

ltproject name"World" basedir"."gt ...
lttarget name"init"gt instructions for "init"
job lt/targetgt lttarget name"build"
depends"init"gt instructions for "build" job
lt/targetgt lttarget name"dist"
depends"build"gt instructions for "dist" job
lt/targetgt
14
Define a "build" task

• This task tells Ant how to compile our program

lt!-- Compile the java code --gt lttarget
name"build" depends"init"
description"compile the source" gt ltjavac
destdir"build/classes" gt ltsrc
path"src"/gt ltclasspath refid"classpath"/gt lt/j
avacgt lt!-- compile JUnit tests --gt ltjavac
debug"true" destdir"build/test"gt ltsrc
path"test"/gt ltclasspath refid"classpath"/gt
lt/javacgt lt/targetgt
15
"build" depends on "init" task

• Most projects have an "init" task to create
  output directories.

lt!-- initialize build environment --gt lttarget
name"init" description"create dirs"gt ltmkdir
dir"build"/gt (this is not required) ltmkdir
dir"build/classes"/gt ltmkdir dir"build/test"/gt
lt!-- copy property files and xml files
except java files --gt ltcopy includeemptydirs"f
alse" todir"build/classes"gt
ltfileset dir"src" excludes"/.laun
ch, /.java" /gt lt/copygt lt/targetgt
Ant wildcards
16
Test Your Build File

• Cmdgt ant build
• if your build file is "mybuild.xml" then...
• Cmdgt ant -f mybuild.xml build

Buildfile mybuild.xml init mkdir Created
dir workspace/World/build/test copy
Copying 2 files to ... build echo World
workspace/World/mybuild.xml javac Compiling
6 source files to build/classes BUILD SUCCESSFUL
17
Create a Distribution

• Define a "dist" task to create the project jar
  file.

lttarget name"dist" depends"build"
description"create distribution" gt ltmkdir
dir"dist"/gt lt!-- Put build/classes into the
jar file --gt ltjar jarfile"dist/worldfacts-1.0
.jar" basedir"build/classes"gt
lt/jargt ltcopy includeemptydirs"false"
todir"dist"gt ltfileset dir"lib"
includes".jar"/gt lt/copygt ltcopy
includeemptydirs"false" todir"dist"gt
ltfileset dir"src" includes".properties"/gt
lt/copygt lt/targetgt
18
Test the "dist" target

• Cmdgt ant build
• if your build file is "mybuild.xml"...
• Cmdgt ant -f mybuild.xml build

Buildfile mybuild.xml init build dist
mkdir Created dir dist jar Building
jar dist/worldfacts-1.0.jar copy Copying
2 files to world/dist
19
Use properties instead of strings

• We have used "build/classes", "src", ... many
  times in the build file.
• Difficult to maintain and potential for typing
  errors.

src.dir location of source code build.dir
build output base directory build.classes.dir
location of build classes lt!-- directory for
distribution products --gt dist.dir location of
distribution lib.dir location of required
libraries doc.dir documentation base
directory lt!-- used to configure compiler
compliance --gt source source compliance level
(1.5, 1.6 ...) target output compliance level
(1.5, 1.6 ...)
20
Use properties instead of strings
lt!-- directory for main source code --gt ltproperty
name"src.dir" location"src"/gt lt!-- directories
for build output --gt ltproperty name"build.dir"
location"build"/gt ltproperty name"build.classes.d
ir" location"build.dir/classes"/gt lt
!-- directory for distribution products
--gt ltproperty name"dist.dir" location"dist"/gt ltp
roperty name"lib.dir" location"lib"/gt ltproperty
name"doc.dir" location"doc"/gt
lt!-- directories for test classes --gt ltproperty
name"test.src.dir" location"test"/gt ltproperty
name"test.classes.dir" location"build.dir
/test-classes"/gt ltproperty name"test.reports.dir
" location"build.dir/test-reports"/gt
21
Substitute properties for strings

• Substitute property names in the build rules

lt!-- initialize environment --gt lttarget
name"init" description"initialize dirs"gt
ltmkdir dir"build.classes.dir"/gt ltmkdir
dir"test.classes.dir"/gt ltmkdir
dir"test.reports.dir"/gt ltmkdir
dir"lib.dir"/gt lt!-- copy the source files
except java files --gt ltcopy includeemptydirs"f
alse" todir"build.classes.dir"gt
ltfileset dir"src.dir"
excludes"/.launch, /.java"/gt
lt/copygt lt/targetgt
22
Test the updated build.xml file

• Delete the "build" directory.
• Run "ant build" again.
• Expect some errors
• typing errors (forgot "." in name)
• Ant may create a file named "build.xxx.dir" if
  you have a misspelled property name in the build
  file

23
Create a "test" task
lttarget name"test" depends"build"gt ltjunit
printsummary"true" haltonfailure"fals
e"gt ltclasspathgt ltpath
refid"classpath"/gt ltpathelement
location"test.classes.dir"/gt
lt/classpathgt ltformatter type"brief"
usefile"false"/gt ltformatter type"xml"/gt
ltbatchtest todir"test.reports.dir"gt
ltfileset dir"test.classes.dir"
includes"/Test.class"/gt
lt/batchtestgt lt/junitgt lt/targetgt
24
What Are Tasks?

• Ant has a large set of built-in tasks, such as
• ltecho ...gt output a message
• ltmkdir ...gt create a directory (if it doesn't
  exist)
• ltcopy ...gt copy a file, directory, or tree
• ltjavac ...gt compile files using java compiler
• ltjar ...gt create a jar file
• ltjunit ...gt run JUnit tests

25
ltproperty name"src" value"..."gt

• Defines a variable ("property") that can be used
  throughout a build script.
• To access value of a property use
  propertyname.
• Useful for defining names of locations and files
  used repeatedly.
• Example
• ltproperty name"src.dir" value"src/java"/gt
• ltjavac ...gt
• ltsrc path"src.dir"/gt
• lt/javacgt

26
ltproperty ...gt (2)

• Read all the properties from a file. The file is
  a plain text file with lines of the form
  "namevalue", like Java properties files
• ltproperty file"build.properties"/gt
• Properties can be imported from system
  environment!
• Prefix environment properties with a "env."
• ltproperty environment"env"/gt
• ltecho message
• "CLASSPATH is env.CLASSPATH"/gt
• ltecho message
• "JAVA_HOME is env.JAVA_HOME"/gt

27
ltcopy file"pattern" tofile"..."/gt

• Copies a file or set of files to another
  location.
• Does not overwrite existing files if they are
  newer than the source file (unless you specify
  that you want it to overwrite).
• Copy a single file.
• ltcopy file"src.dir/myfile.txt"
• tofile"target.dir/mycopy.txt"/gt

28
ltcopy todir"..."gt copy sets of files

• Copy files from one directory to another, omit
  any java source files.
• ltcopy todir"dest.dir" gt ltfileset
  dir"src"gt ltexclude name"/.java"/gt
  lt/filesetgt
• lt/copygt
• Copy all files from the directory ../backup/ to
  src_dir. Replace occurrences of "_at_TITLE_at_" in
  the files with "Foo".
• ltcopy todir"../backup"gt ltfileset
  dir"src_dir"/gt ltfiltersetgt ltfilter
  token"TITLE" value"Foo Bar"/gt lt/filtersetgt
• lt/copygt

29
ltdeletegt

• Deletes files, directories, or sets of files.
• Delete a single file.
• ltdelete file"/lib/ant.jar"/gt
• Delete all .bak files from this directory and
  sub-directories.
• ltdeletegt
• ltfileset dir"." includes"/.bak"/gtlt/deletegt
  
• Delete the build directory and everything in it.
• ltdelete includeEmptyDirs"true"gt
• ltfileset dir"build"/gt
• lt/deletegt

30
ltechogt

• Display a message on terminal. It has 2 forms
• Display a one-line message

ltecho message"Hello Ants" /gt
echo Hello Ants

• Display many lines of text

ltechogt Usage ant target clean - delete
compiler output files build - compile source
code dist - create a distribution lt/echogt
31
Using ltechogt

• A good build.xml file should have a help or usage
  target

ltproject name"myapp" default"help"gt lttarget
name"help"gt ltechogt Usage ant target where
'target' is one of clean - delete compiler
output files build - compile source code
dist - create a distribution lt/echogt lt/targetgt
32
ltmkdir dir"..."/gt

• Create a directory.
• ltmkdir dir"dist.dir"/gt
• Creates a subdirectory named "jars" in the
  location specified by the "dist.dir" property.
• ltmkdir dir"dist.dir/jars"/gt

33
ltjavacgt

• Compiles Java source code.
• Attempts to analyze source such that up to date
  .class file are not recompiled.
• Example Compile all java source files under
  src.dir and put the .class files in the
  build.classes directory. Include debugging
  information in the .class files.
• ltjavac srcdir"src"
• destdir"build.classes"
• classpath"mylib.jar"
• debug"true"/gt

34
ltjavac ...gt (2)

• You can specify additional source directories and
  further restrict which files are compiled using
  include and exclude .
• ltjavac destdir"build"
• classpath"xyz.jar" debug"on"gt
• ltsrc path"src"/gt
• ltsrc path"src2"/gt
• ltinclude name"package/p1/"/gt
• ltinclude name"package/p2/"/gt
• ltexclude name"package/p1/test/"/gt
• lt/javacgt

35
ltjar ...gt

• Creates a JAR file from a set of files or updates
  an existing JAR.
• Will automatically supply a manifest file for the
  JAR or use one you specify.
• Example make a jar file including all files in
  build/classes
• ltjar jarfile"dist/lib/myapp.jar"
• basedir"build/classes"/gt

36
ltjar ...gt

• Create a JAR file from all the files in
  build/classes and src/resources. (two sets
  of files)
• Any files named Test.class in the build
  directory are not included in the JAR.
• ltjar jarfile"dist/lib/myapp.jar"gt
• ltfileset dir"build/classes"
• excludes"/Test.class" /gt
• ltfileset dir"src/resources"/gt
• lt/jargt

37
ltjavadocgt

• Creates Javadocs from Java source code files.
• Example Build Javadoc only for the packages
  beginning with "org.ske..." in the src\
  directory.
• ltjavadoc packagenames"org.ske."
• sourcepath"src"
• destdir"doc/api"/gt
• This command will search all subdirectories of
  src for .java files.

38
ltjavagt

• Invoke a Java program from within an Ant build
  file.
• Can fork a separate process so that a
  System.exit() does not kill the Ant build.
• ltjava classname"test.Main"gt ltarg
  value"some-arg-to-main"/gt ltclasspathgt
  ltpathelement location"test.jar"/gt
  ltpathelement path"java.class.path"/gt
  lt/classpathgtlt/javagt

39
ltjavagt

• Invoke a class named test.Main in a separate Java
  VM. The Java VM is invoked using the options
• -Xrunhprofcpusamples,filelog.txt,depth3
• to request profiling.
• ltjava classname"test.Main" fork"yes"gt
  ltsysproperty key"DEBUG" value"true"/gt ltarg
  value"-h"/gt ltjvmarg value
• "-Xrunhprofcpusamples,filelog.txt,depth3"/gt
  lt/javagt

40
More Ant Tasks

• The Apache Ant distribution includes more than 50
  core tasks and many optional tasks.
• Examples zip, gzip, war (create a war file),
• Many tasks correspond to standard Linux commands,
  like mkdir, copy, move.
• You can write your own Ant tasks using lttaskdef
  /gt.
• See Ant manual (ant/docs directory) for how to
  use each task.

41
Tools

• List of Ant tools
• http//ant.apache.org/external.html
• NetBeans creates build.xml files for NetBeans
  projects.
• Eclipse can "export" an Ant build file, but it
  contains a lot of Eclipse-specific references
  that make the build file not portable.
• Ivy (http//ant.apache.org/ivy) is a dependency
  manager for Ant. Automatically downloads
  dependencies, similar to what Maven does (Ivy can
  use Maven repositories).

42
Resources

• Ant Home http//ant.apache.org
• Apache Ant Manual. Installed with ant, in the
  ant/docs directory. The Ant Manual documents all
  Ant tasks.
• Ant The Definitive Guide. O'Reilly. Terse, but
  lots of info.

43
(No Transcript)