Learn to automate software build processes with Apache Ant, the most widely used test-driven development build tool for Java projects.
Written By
Apache Ant is an XML based tool for automating software build processes. Starting out as part of the Apache Tomcat codebase, Ant got its first standalone release in July 2000. Today it is the most widely used build tool for Java projects, enabling developers to adopt agile principles: most importantly test-driven development.
A typical Ant script consists of a single build.xml file. The root element of the build script is the project tag. Within the project element there are one or more targets specified. A target contains a set of tasks to be executed.
The project element can specify a default target if no target is chosen during execution of the build script.
Figure 1: The basic structure of an Ant build script.
The most important concept in Ant is that of dependencies. Each target may depend on other targets. When running, Ant resolves these dependencies so that your script gets executed in the order you have specified.
| Attribute | Description | Required |
| name | Name of the project. | No |
| basedir | Base directory from which all path calculations are done | No |
| default | The default target to run when no other target has been specified | No |
Table 1: Project element attributes
| Attribute | Description | Required |
| name | The name and identifier of this target | Yes |
| depends | Comma separated list of other targets that this target depends on | No |
| if | The name of a property which must be set for this target to run | No |
| unless | The name of a property which must not be set for this target to run | No |
| description | Description of this target | No |
| extensionOf | Add the target to the depends list of the named extension point | No |
Table 2: Target element attributes
Properties can be defined within the build script or in separate property files to provide more customizable build scripts.
| Attribute | Description | Required |
| name | Name of the property | No |
| value | The value of the property | One of these when using name attribute |
| location | Set value to absolute filename. If the value passed through is not an absolute path it will be made relative to the project basedir | |
| refId | Reference to an object defined elsewhere | |
| file | Location of the properties file | When not using the name attribute (i.e. loading external properties) |
| resource | Location in the classpath of the properties file | |
| url | URL pointing to properties file | |
| basedir | The basedir to calculate the relative path from | No. Default is project basedir |
| classpath / classpathref | The classpath to use when looking up a resource | No |
| environment | Prefix to use when accessing environment variables | No |
| prefix | Prefix to apply to properties loaded using file, resource or url | No |
Table 3: Property element attributes
All system properties that can be accessed from the System.getProperties() methods in Java can be used in Ant. Additionally, the following built-in properties are available:
| Property Name | Description |
| basedir | Absolute path of projects basedir |
| ant.core.lib | Absolute path of the ant.jar file |
| ant.file | Absolute path of buildfile |
| ant.home | Home directory of Ant |
| ant.java.version | Java version detected |
| ant.project.default-target | Name of the default target |
| ant.project.invoked-targets | List of targets specified in the command line when invoking this project |
| ant.project.name | Name of the project that is running |
| ant.version | Version of Ant |
Table 4: Built-in properties
Path structures can be created using a series of <pathelement> tags. For example, a classpath can be created using:
<classpath>
<pathelement location="/path/jarfile.jar"/>
<pathelement path="/path/lib/jar1.jar;/path/lib/jar2.jar"/>
</classpath>
In order to bundle files together, Ant provides the <fileset> tag:
| Property Name | Description |
| casesensitive | Whether include/excludes patterns must be treated with case sensitivity. Default true |
| dir | Root of the directory tree of this fileset |
| defaultexcludes | If default excludes should be used (set of definitions that are always excluded) |
| erroronmissingdir | If true causes a build error, if false the fileset is ignored |
| excludes | List of patterns of files to exclude |
| excludesfile | Name of a file to exclude |
| file | Shortcut for specifying a fileset containing a single file |
| followssymlinks | Whether symbolic links should be followed. Default true |
Table 5: Fileset attributes
The following sections list out the most commonly used tasks in Ant build scripts. Required attributes are marked in bold.
This section gives a complete reference of all tasks and their attributes that are most commonly used by Java Developers.
Compiling Java Code
Compilation is achieved with the <javac> task.
| Attribute | Description |
| srcdir | Location of java files to compile |
| bootclasspath/ boothclasspathref | Location of bootstrap class files or reference to a predefined path |
| classpath/ classpathref | Classpath to use for compilation or reference to a predefined path |
| compiler | Compiler implementation to use. Default is current VM |
| debug | Whether source should be compiled with debug information (-g parameter). Defaults to off |
| debuglevel | Can be lines, var or source. Used in the -g parameter for the compiler |
| depend | Enables dependency tracking on jikes and classic compilers |
| deprecation | Whether source should compile with deprecation information |
| destdir | Destination for compiled .class files |
| encoding | Encoding of source files |
| errorProperty | Property to set to true if compilation fails |
| excludes | Comma separated list of files that must be excluded from compilation. Wildcard patterns can be used |
| excludesFile | File that contains the exclusion list |
| executable | Path to javac executable to use when fork set to yes |
| extdirs | Location of installed extensions |
| fork | Whether to execute javac using the JDK compiler externally. Default no |
| failonerror | Whether compilation error fails the build. Default true |
| includes | Comma separated list of files that must be included in compilation. Wildcard patterns can be used |
| includeAntRuntime | Whether to include ANT runtime libraries in the classpath. Default yes |
| includeDestClasses | Whether classes compiled to the dest directory are included in the classpath. Default true. When false, causes recompilation of dependent classes |
| includesFile | File containing the exclusion list |
| includeJavaRuntime | Whether to include default libraries from VM.Default no |
| listfiles | Whether source files to be compiled will be listed. Default no |
| memoryInitialSize / memoryMaximumSize | Initial and maximum memory sizes for VM if run externally |
| nowarn | Whether -nowarn should be used with the compiler. Defaults to off |
| optimize | Whether to compile with optimization, ignored since JDK1.3 |
| source | Value of the -source command line switch |
| sourcepath/ sourcepathref | Defaults to value of srcdir or reference to a predefined path |
| target | Generate class files for a particular VM version |
| tempdir | Temporary file location if fork set to yes |
| updatedProperty | Property to set for successful compilation |
| verbose | Use verbose output on the compiler |
Table 6: javac tasks properties
Additional command line arguments can be passed through to the compiler using the <compilerarg> nested element.
Class file dependencies can be managed using the <depend> task.
| Attribute | Description |
| srcdir | Location of Java files to compile. Will be examined to determine which files are out of date |
| cache | Directory where dependency information is stored and retrieved. No cache if not used |
| classpath | Classpath from which dependencies also need to be checked |
| closure | If true, all classes depending on an out-of-date class are deleted |
| destdir | Location of class file to be analyzed |
| dump | If true dependency info is written to the debug level log |
| warnOnRmiStubs | Disables warnings about files that look like rmic generated stubs but no .java source |
Table 7: Depend task properties
Jar files can be created using the <jar> task.
| Attribute | Description |
| destfile | JAR file to create |
| basedir | The directory to build from |
| compress | Compress data in jar. Defaults true |
| createUnicodeExtraFields | Whether to create unicode extra fields to store file names a second time inside the entry's metadata |
| defaultexcludes | Whether default excludes should be used. Default true |
| duplicate | Behavior when a duplicate file is found - add (default), preserve, fail |
| keepcompression | For entries coming from other archives, keep its compression, overriding compress |
| encoding | Character encoding for filenames. Default UTF8 |
| excludes | List of patterns of files to exclude |
| excludesfile | The name of a file that defines an exclude pattern |
| fallbacktoUTF8 | If the specified encoding cannot be used, whether to fallback to UTF8 |
| filesonly | Store only file entries. Default false |
| filesetmanifest | Behavior for when a manifest is found in a zipfilesset. Can merge, mergewithoutmain or skip (default) |
| flattenAttributes | Merge attributes occurring more than once in a section into one single attribute |
| includes | List of patterns of files to include |
| includesfile | The name of a file that defines an include pattern |
| index | Whether to create an index list to speed up classloading. Default false |
| indexMetaInf | Whether to include META-INF in the index. Default false |
| level | Compression level for files from 0 (none) to 9 (maximum) |
| manifest | Location of manifest for jar |
| manifestencoding | Encoding to use for manifest. Default is platform encoding |
| mergeClassPathAttributes | Merge classpath attributes of different manifests when merging |
| preserve0permissions | If a file has permissions value of 0, it will preserve this instead of applying default values |
| roundup | Whether to round up file modification time to the next even number of seconds |
| strict | How to handle breaks of packaging version specification Fail, warn or ignore (default) |
| update | Whether to overwrite files that already exist. Default false |
| useLanguageEncodingFlag | Whether to set language encoding if encoding set to UTF8 only |
| whenmanifestonly | Behavior when no files match - fail, skip or create (default) |
Table 8: Jar task properties
Additionally, you can sign jar archives using the <signjar> task.
| Attribute | Description |
| alias | The alias to sign under |
| jar | The jar file to sign |
| storepass | The password for keystore integrity |
| executable | Specific jarsigner executable to use in place of default in JDK |
| force | Force signing if already signed or not out of date |
| internals | Whether to include the .SF file inside signature block. Default false |
| keypass | The password for the private key |
| keystore | Keystore location |
| lazy | Whether a signature file being present means the jar is signed |
| maxmemory | Maximum memory the VM will use when signing |
| preservelastmodified | Signed files keep the same modification time as original jar files |
| sectionsonly | Whether to compute the hash of entire manifest |
| sigfile | The name of the .SF or .DSA file |
| signedjar | The name of the signed jar file |
| storetype | The keystore type |
| tsacert | Alias in keystore for timestamp authority |
| tsaurl | URL for timestamp authority |
| verbose | Whether to use verbose output. Default false |
Table 9: Signjar task properties
Manifests can be included using the <manifest> task.
| Attribute | Description |
| file | Manifest file to create or update |
| encoding | Encoding to read existing manifest |
| flattenAttributes | Merge attributes occurring more than once in a section into one single attribute |
| mergeClassPathAttributes | Merge classpath attributes of different manifests when merging |
| mode | Either update or replace (default) |
Table 10: Manifest task properties
JavaDoc generation is done through the <javadoc> task.
| Attribute | Description |
| sourcepath sourcepathref sourcefiles |
Location of the source files for the task. At least one of these attributes required for this specification |
| destdir | Destination directory required unless a doclet is specified |
| access | Access mode (public, private, protected, package) |
| additionalparam | Additional parameters to pass through |
| author | Include @author parts |
| bootclasspath / bootclasspathref |
Location of class files loaded by bootstrap class loader |
| bottom | Bottom text for each page |
| breakiterator | Use new breakiterator algorithm |
| charset | Charset for cross platform viewing |
| classpath/classpathref | Location of classpath |
| defaultexcludes | Whether default excludes should be used |
| docencoding | Encoding of output file |
| docfilessubdirs | Deep copy of doc-file subdirectories |
| doclet/docletpathref | Classfile that starts to doclet used |
| doctitle | Title for the package index page |
| encoding | Source file encoding |
| excludepackagenames | Packages to exclude from javadoc |
| executable | Specify a javadoc executable instead of VM default |
| extdirs | Location of installed extensions |
| failonerror | Stops build process if command fails |
| footer | Footer text for each page |
| group | Group specified packages together in overview page |
| header | Header text for each page |
| helpfile | Specifies help file to include |
| includenosourcepackages | When true includes packages with no source |
| link | Create links to javadoc output at given url |
| linksource | Generate links to source files |
| locale | Locale to be used |
| maxmemory | Maximum amount of memory to allocate in VM |
| nodeprecated | Do not include @deprecated information |
| nodeprecatedlist | Do not generate deprecated list |
| notree | Do not generate class hierarchy |
| noindex | Do not generate index |
| nohelp | Do not generate help link |
| nonavbar | Do not generate naviation bar |
| noqualifier | Enables -noqualifier argument for a list of packages (or all) |
| overview | Read overview documentation from HTML file |
| packagenames | List of package files to use |
| packageList | File containing packages to use |
| public | Show only public classes and members |
| protected | Show only protected/public classes and members |
| package | Show only package/protected/public classes and members |
| private | Show all classes and members |
| serialwarn | Warn about @serial tag |
| source | Source level used for compilation |
| splitindex | Split index into one file per letter |
| stylesheetfile | Specifies CSS stylesheet |
| use | Create class and package usage pages |
| verbose | Output all messages of javadoc process |
| version | Include @version parts |
| windowtitle | Browser window title for documentation |
Table 11: JavaDoc task properties
Java classes can be executed from Ant using the <java> task.
| Attribute | Description |
| classname jar | The jar file or classname to execute. If using jar, fork must be set to true |
| append | Whether output/error files should be appended or overwritten |
| args | Arguments for class. Better to use nested <arg> elements |
| classpath / classpathref | Classpath to use for execution |
| clonevm | Clones system properties and bootclasspath of forked VM to be the same as the Ant VM |
| dir | Directory to invoke VM in |
| error | File to write error (System.err) output to |
| errorproperty | Property to store error output from command |
| failonerror | Stops Ant build process if failure occurs |
| fork | Executes the class in another VM |
| input | File where standard input is taken from |
| inputstring | String where standard input is taken from |
| jvm | Command used to invoke JVM. Default is java |
| javmargs | Arguments for forked JVM. Better to use nested <jvmarg> |
| logError | Shows error output in Ant log |
| maxmemory | Maximum memory to allocate to the forked VM |
| newenvironment | When fork=true, do not propogate current environment variables |
| output | File to write output to |
| outputproperty | Property to store output of the command |
| resultproperty | Property where return code of command is stored |
| spawn | Need fork set to true. Will spawn a process independent of calling Ant process |
| timeout | Timeout for the command to execute within before being stopped |
Table 12: Java task properties
JUnit tests are executed from Ant through the <junit> task
| Attribute | Description |
| clonevm | Clones system properties and bootclasspath of forked VM to be the same as the Ant VM |
| dir | Directory from which to invoke the VM |
| errorproperty | Property to set when errors occur |
| failureproperty | Property to set when failure occurs |
| filtertrace | Filter out JUnit or Ant stack frames from stack traces in errors or failures |
| fork | Run JUnit in a separate VM |
| forkmode | How many VMs to create when forking tests. (preTest, perBatch or once) |
| haltonerror | Stop build process if an error happens |
| haltonfailure | Stops build process if a test fails |
| includeAntruntime | Stops build process if a test fails |
| jvm | Command used to invoke VM, default java |
| logfailedtests | Log a FAILED message for each failed test to Ant's logging system |
| maxmemory | Maximum memory to allocate to forked VM |
| newenvironment | When fork=true, do not propogate current environment variables |
| outputformatters | Send output generated by tests to test formatters |
| printsummary | Print statistics for each test case. (on, off, withOutAndErr) |
| reloading | Whether a new classloader should be instAntiated for each test |
| showoutput | Send output to Ant log |
| tempdir | Location for temporary files |
| timeout | Cancel tests if not complete in specified time |
Table 13: JUnit task properties
Tests are defined in nested elements within the <junit> task. Batch tests are defined using the <<batchtest> tag:
| Attribute | Description |
| name | Name of test class |
| errorproperty | Property to set when errors occur |
| failureproperty | Property to set when failure occurs |
| filtertrace | Filter out JUnit or Ant stack frames from stack traces in errorsor failures |
| fork | Run tests in a separate VM, overriding the value set in the <junit> task |
| haltonerror | Stop build process if an error happens |
| haltonfailure | Stops build process if a test fails |
| if | Property condition to run test against, if set |
| todir | Directory to write reports to |
| unless | Property condition to run test against, if not set |
Table 14: JUnit batch test definition
Test results can be written to different formats, using the outputformatters attribute in the <junit> task. The following table shows the options for formatter definition:
| Attribute | Description |
| type | A predefined formatter type of either xml, plain, brief or failure |
| classname | If no type specified, use a customer formatter implementing org.apache.tools.Ant.taskdefs.optional.junit .JUnitResultFormatter |
| if | Use formatter if property is set |
| unless | Use formatter if property is not set |
| usefile | If output should be sent to a file. Default true |
Table 15: JUnit formatter definition
Once tests are completed, reports can be generated for the tests using the <junitreport> task.
| Attribute | Description |
| todir | The directory that will contain the results |
| tofile | The name of the XML file that will aggregate all previously generated results |
Table 16: JUnitReport task properties
The <junitreport> task contains a fileset that collects all the reports from previous Junit tests.
To output to a report file, use the internal <report> tag.
| Attribute | Description |
| format | Format of report (frames or noframes) |
| styledir | Directory containing stylesheets. Files must be junit-frames.xsl or junit-noframes.xsl |
| todir | The directory that files are written to. By default this is the current directory |
Table 17: Report tag for <junitreport>
There are a number of other core tasks related to file operations. The following is an overview of these tasks:
| Task | Description |
| attrib /chmod | Changes permission of a file (attrib for Windows, chmod for Unix) |
| checksum | Generates a checksum for files |
| concat | Concatenates multiple files into one single file, or to the console |
| copy | Copies a file, or collection of files, to another location |
| delete | Deletes a file, directory or collection of files |
| exec | Executes a system command |
| ftp | Provides basic FTP functionality |
| get | Gets a file from a URL |
| import /include | Imports or includes another build file into the current Ant script |
| Sends mail over SMTP | |
| mkdir | Creates a new directory |
| move | Moves a file, or collection of files, to another location |
| record | Listens to the build process and outputs to a file |
| replace | Replaces occurances of a string in file or collection of files |
| replaceregexp | Replaces occurances of a string in file or collection of files using regular expressions |
| sql | Executes SQL statements to a database using JDBC |
| sync | Synchronizes a target directory with a list of files |
| zip / unzip tar / untar | Creates a zip file / unzips an existing zip. Also provides functionality for tar files |
Table 18: Overview of basic infrastructure tasks
ANT provides a number of tasks for connecting with different source control management systems. The core support deals with CVS.
| Task | Description |
| cvs | Handles commands to be run against CVS, defaulting with checkout |
| cvschangelog | Generates a report of change logs recorded in CVS |
| cvspass | Adds entries to a .cvspass file |
| cvstagdiff | Generates a report of the changes between two tags/dates from CVS |
| cvsversion | Retrieves CVS client and server version |
| patch | Applies a diff file to originals |
Table 19: CVS task properties
There are also tasks available for interfacing with ClearCase, Visual Source Safe, Pvcs, Perforce and Continuus. Additional tasks can be found online for DCVS systems such as Git and Mercurial.
Ant provides some tasks that deal with managing properties throughout your build process.
| Task | Description |
| available | Sets property if file, directory or class in classpath is available at runtime |
| basename | Sets property to last element of specified path |
| buildnumber | Reads build number from a specified file |
| condition | Set property if a condition is true |
| dirname | Set property to the directory path of a specified file |
| echoproperties | Display all properties to file or console |
| loadfile | Loads a file into a property |
| loadproperties | Load a property file contents as Ant properties |
| makeurl | Converts filenames into URLs |
| pathconvert | Converts a file list or path structure to a separated string for the target platform |
| property | Set a property |
| propertyfile | Creation and modification of property files |
| uptodate | Set property if specified target file is newer than source files |
| whichresource | Find class or resource |
| xmlproperty | Loads properties from property file written in XML |
Table 20: Ant Property Tasks
{{ parent.title || parent.header.title}}
{{ parent.tldr }}
{{ parent.linkDescription }}
{{ parent.urlSource.name }}