Apache Ant Java-Based Build Tool

Making your builds boring… Building projects should be easy and standardized. You should not be spending a substantial amount of your project time on builds. Builds should just work!

Introduction to Ant Ant is a “build tool” – especially useful to compile, package, deploy Java projects It can do much more - file operations, version control/CVS, XML validations/transforms, run system commands, custom tasks, etc Ant is suitable also for all kinds of Java-unrelated file manipulations, e.g. preprocessing static stuff in Web publishing Ant’s alternatives are “batch” files under Windows, Makefile-s or shellscripts under UNIX. Build scripts may be written in other scripting languages as well

Typical Things to Build Classes JARs WARs EARs JavaDocs Documentation HTML/PDF

Ant in Java Projects Even when there is IDE build environment, it is useful to have Ant script to build and deploy (everything is transparent there) In big projects build scripts are usually written by “Technical Designer” or qualified developer Other developers ideally just need to remember a few commands, e.g. ant -projecthelp (lists targets and their descriptions) ant junit (rebuild and run JUnit tests) ant deploy (build and deploy for a system test)

Ant and IDE tools They are complementary: Ant build scripts can automate all kinds of build processes Use IDE (e.g. Eclipse) for editing, unit-testing and version-controlling code; use Ant for doing more complex development tasks, e.g. deployments and system tests Eclipse plugins can solve similar issues as Ant can, but Ant is free and easier to standardize

Ant Features Build-scripts are written using a special XML syntax “Ant tasks” represent object-oriented approach to build process. Tasks can inherit from each other. Build-file language does not have flow control features: loops/iterators, if-constructs, try-catch constructs Instead it is based on recursive nature of Ant’s tasks and Ant’s datatypes filesets, patterns, filters, mappers, etc

Build File XML format Typically in project root directory Default name: build.xml Declarative - define steps, not scripty details Defines a single project A project contains targets Targets contain tasks

Projects A project has three attributes: name - the name of the project default - the default target to use when no target is supplied basedir - the base directory from which all path calculations are done Each project defines one or more targets …

Targets A target can depend on other targets A target has the following attributes: name - the name of the target depends - a comma-separated list of names of targets on which this target depends if - the name of the property that must be set in order for this target to execute unless - the name of the property that must not be set in order for this target to execute description - a short description of this target's function DCBA >ant D Dependency resolution

Tasks A task is a piece of code that can be executed Tasks have a common structure: There is a set of built-in tasks:,,, many more… It is very easy to write your own task: Extend a org.apache.tools.ant.Task class Implement specific stuff like attributes, nested tasks etc. Write a public void execute method, with no arguments, that throws a BuildException. This method implements the task itself.

Properties A project can have a set of properties ${property.name} to access property value Properties can be defined: In Ant file itself (name/value) In one or more external properties file In the command line > ant -Dappname=newstuff jar Environment variables can be accessed

Ant Data Types Commonly used built-in data types: Path Ordered list of path elements, analogous to Java CLASSPATH, contains files and/or directories Fileset Unordered set of files from a single root directory Patternset Selectors, Filterset, and others…

Example build file Simple example build file

Installing Ant Download from current version / Precondition – install J2SE (or JRE) and set variable %JAVA_HOME% Unpack Ant’s installation and set variable %ANT_HOME% Add %ANT_HOME%\bin to your %PATH% variable to enable running “ant.bat” utility from any DOS window

Running Ant Targets Ant targets can be executed from command line: Execute default target: > ant Execute specific target: > ant deploy-jboss Execute multiple targets: > ant test-common generate-test-reports > ant deploy-jboss -Dsite=personal Buildfile: build.xml init: [echo] Building for personal site.... deploy-jboss: [copy] Copying 1 file to /Users/erik/jboss-3.0.0/server/default/deploy BUILD SUCCESSFUL Total time: 18 seconds

Debugging Ant By default, Ant’s messages for failed tasks might be insufficient. You can easily make Ant more verbose to see what it is doing: ant -verbose taskname ant -debug taskname (very verbose) These will show each elementary action performed by the build process

File Tasks Task NameDescription mkdir Creates a directory. Non-existent parent directories are created, when necessary. delete Deletes either a single file, all files and sub-directories in a specified directory, or a set of files specified by one or more FileSets. copy Copies a file or Fileset to a new file or directory. move Moves a file to a new file or directory, or a set(s) of file(s) to a new directory. chmod Changes the permissions of a file or all files inside the specified directories. Currently, it has effect only under Unix. The permissions are also UNIX style, like the arguments for the chmod command. get Gets a file from a URL. More tasks: concat, replace, chown, sync, tempfile, touch,…

More Tasks… Compiles a Java source tree Jars a set of files Creates Web Application Archive <javac srcdir="src" destdir="${build.dir}/WEB-INF/classes" debug="${javac.debug}" classpathref="compile.classpath" /> <jar basedir="${build.dir}" jarfile="${name}.jar“ includes="**/*.class"/> <war destfile="myapp.war" webxml="${web.dir}/WEB-INF/web.xml">

More Tasks… Executes Java class Prints a message Runs JUnit tests Fatal error!

References Ant Home Ant Online Manual Books on Ant Ant Developer's Handbook by Alan Williamson, Kirk Pepperdine, Joey Gibson, Andrew Wu Java™ Extreme Programming Cookbook by Eric M. Burke, Brian M. Coyner Java Development With Ant by Erik Hatcher, Steve Loughran