Ant

Introduction
Apache Ant is a Java-based build tool. In theory, it is kind of like make, without make's wrinkles.

Links

 * Ant website
 * FAQ
 * Manual

Buildfile
Ant's buildfiles are written in XML. Each buildfile contains one project and at least one (default) target. Targets contain task elements. Each task element of the buildfile can have an id attribute and can later be referred to by the value supplied to this. The value has to be unique.

Project
The root tag is the   tag. It 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.

Optionally, a description for the project can be provided as a top-level   element.

Targets
A target can depend on other targets. You might have a target for compiling, for example, and a target for creating a distributable. You can only build a distributable when you have compiled first, so the distribute target depends on the compile target. Ant resolves these dependencies. Example:

   

Suppose we want to execute target D. From its depends attribute, you might think that first target C, then B and then A is executed. Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.

A target also has the ability to perform its execution if (or unless) a property has been set. This allows, for example, better control on the building process depending on the state of the system (java version, OS, command-line property defines, etc.). To make a target sense this property, you should add the if (or unless) attribute with the name of the property that the target should react to. Note: Ant will only check whether the property has been set, the value doesn't matter. A property set to the empty string is still an existing property. For example:





In the first example, if the module-A-present property is set (to any value), the target will be run. In the second example, if the module-A-present property is set (again, to any value), the target will not be run.

If no if and no unless attribute is present, the target will always be executed.

Tasks
A task is a piece of code that can be executed. Please see the complete core task list and the optional task list] for more information about available Ant tasks.

A task can have multiple attributes (or arguments, if you prefer). The value of an attribute might contain references to a property. These references will be resolved before the task is executed.

Tasks have a common structure:



where name is the name of the task, attributeN is the attribute name, and valueN is the value for this attribute.

Own Tasks
It is posible to create own Tasks by writing a Java class that extends org.apache.tools.ant.Task. This class must have setter methods, to set attributes given by the call of the task in the ant build file.

They must look like:

public void setAttribute(String myAttribute) { this.myAttribute = myAttribute; }

You can implement everything you want ant to do and call theses methods in the execute method:

public void execute throws BuildException { myOwnMethod; }

When you finished writing the Java class you must compile it an pack it to a .jar file. Now you can call this task in your build.xml.

First you must declare the task:

/MyOwnTask.jar"/>

Then you can call it:

 

Properties
A project can have a set of properties. These might be set in the buildfile by the property task, or might be set outside Ant. A property has a name and a value; the name is case-sensitive. Properties may be used in the value of task attributes. This is done by placing the property name between "${" and "}" in the attribute value. For example, if there is a "builddir" property with the value "build", then this could be used in an attribute like this: ${builddir}/classes. This is resolved at run-time as build/classes.

Built-in Properties
Ant provides access to all system properties as if they had been defined using a   task. For example, ${os.name} expands to the name of the operating system.

For a list of system properties see the Javadoc of System.getProperties.

In addition, Ant has some built-in properties:

basedir            the absolute path of the project's basedir (as set                    with the basedir attribute of ). ant.file           the absolute path of the buildfile. ant.version        the version of Ant ant.project.name   the name of the project that is currently executing; it is set in the name attribute of. ant.java.version   the JVM version Ant detected; currently it can hold the values "1.1", "1.2", "1.3", "1.4" and "1.5".

Path-like Structures
You can specify PATH- and CLASSPATH-type references using both and  as separator characters. Ant will convert the separator to the correct character of the current operating system.

Wherever path-like values need to be specified, a nested element can be used. This takes the general form of:

 

The location attribute specifies a single file or directory relative to the project's base directory (or an absolute filename), while the path attribute accepts colon- or semicolon-separated lists of locations. The path attribute is intended to be used with predefined paths - in any other case, multiple elements with location attributes should be preferred.

As a shortcut, the   tag supports path and location attributes of its own, so:



can be abbreviated to:



In addition, DirSets, FileSets, and FileLists can be specified via nested , , and  elements, respectively. Note: The order in which the files building up a FileSet are added to the path-like structure is not defined.

  <pathelement location="classes"/> <dirset dir="${build.dir}"> <include name="apps/**/classes"/> <exclude name="apps/**/*Test*"/> <filelist refid="third-party_jars"/>

This builds a path that holds the value of '${classpath}, followed by all jar files in the lib directory, the classes directory, all directories named classes under the apps subdirectory of ${build.dir}, except those that have the text Test in their name, and the files specified in the referenced FileList.

Objects Definition
Ant uses some words in the manual that are important to create a working file.

FileSet
FileSets are groups of files. These files can be found in a directory tree starting in a base directory and are matched by patterns taken from a number of PatternSets and Selectors. FileSets can appear inside tasks that support this feature or at the same level as target - i.e., as children of project.

Patterns
As described earlier, patterns are used for the inclusion and exclusion of files. These patterns look very much like the patterns used in DOS and UNIX:

'*' matches zero or more characters, '?' matches one character.

In general, patterns are considered relative paths, relative to a task dependent base directory (the dir attribute in the case of ). Only files found below that base directory are considered. So while a pattern like ../foo.java is possible, it will not match anything when applied since the base directory's parent is never scanned for files.

Examples:


 * *.java matches  .java, x.java and FooBar.java, but not FooBar.xml (does not end with .java).


 * ?.java matches  x.java, A.java, but not .java or xyz.java (both don't have one character before .java).

Combinations of *'s and ?'s are allowed.

Matching is done per-directory. This means that first the first directory in the pattern is matched against the first directory in the path to match. Then the second directory is matched, and so on. For example, when we have the pattern /?abc/*/*.java and the path /xabc/foobar/test.java, the first ?abc is matched with xabc, then * is matched with foobar, and finally *.java is matched with test.java. They all match, so the path matches the pattern.

To make things a bit more flexible, we add one extra feature, which makes it possible to match multiple directory levels. This can be used to match a complete directory tree, or a file anywhere in the directory tree. To do this, must be used as the name of a directory. When is used as the name of a directory in the pattern, it matches zero or more directories. For example: /test/** matches all files/directories under /test/, such as /test/x.java, or /test/foo/bar/xyz.html, but not /xyz.xml.