Targets

A target is a container of tasks that cooperate to reach a desired state during the build process.

Targets can depend on other targets and Apache Ant ensures that these other targets have been executed before the current target. For example you might have a target for compiling 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 tries to execute the targets in the depends attribute in the order they appear (from left to right). Keep in mind that it is possible that a target can get executed earlier when an earlier target depends on it:

<target name="A"/>
<target name="B" depends="A"/>
<target name="C" depends="B"/>
<target name="D" depends="C,B,A"/>

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.

Call-Graph:  A --> B --> C --> D

In a chain of dependencies stretching back from a given target such as D above, each target gets executed only once, even when more than one target depends on it. Thus, executing the D target will first result in C being called, which in turn will first call B, which in turn will first call A. After A, then B, then C have executed, execution returns to the dependency list of D, which will not call B and A, since they were already called in process of dependency resolution for C and B respectively as dependencies of D. Had no such dependencies been discovered in processing C and B, B and A would have been executed after C in processing D's dependency list.

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: In the most simple case Ant will only check whether the property has been set, the value doesn't matter, but using property expansions you can build more complex conditions. See the properties page for more details. For example:

<target name="build-module-A" if="module-A-present"/>

<target name="build-own-fake-module-A" unless="module-A-present"/>

In the first example, if the module-A-present property is set (to any value, e.g. false), 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.

Only one propertyname can be specified in the if/unless clause. If you want to check multiple conditions, you can use a dependent target for computing the result for the check:

<target name="myTarget" depends="myTarget.check" if="myTarget.run">
    <echo>Files foo.txt and bar.txt are present.</echo>
</target>

<target name="myTarget.check">
    <condition property="myTarget.run">
        <and>
            <available file="foo.txt"/>
            <available file="bar.txt"/>
        </and>
    </condition>
</target>

Call-Graph:  myTarget.check --> maybe(myTarget)

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

Important: the if and unless attributes only enable or disable the target to which they are attached. They do not control whether or not targets that a conditional target depends upon get executed. In fact, they do not even get evaluated until the target is about to be executed, and all its predecessors have already run.

The optional description attribute can be used to provide a one-line description of this target, which is printed by the -projecthelp command-line option. Targets without such a description are deemed internal and will not be listed, unless either the -verbose or -debug option is used.

It is a good practice to place your tstamp tasks in a so-called initialization target, on which all other targets depend. Make sure that target is always the first one in the depends list of the other targets. In this manual, most initialization targets have the name "init".

    <project>
        <target name="init">
            <tstamp/>
        </target>
        <target name="otherTarget" depends="init">
            ...
        </target>
    </project>
    

Especially if you only have a few tasks you also could place these tasks directly under the project tag (since Ant 1.6.0):

    <project>
        <tstamp/>
    </project>
    

If the depends attribute and the if/unless attribute are set, the depends attribute is executed first.

A target has the following attributes:

A target name can be any alphanumeric string valid in the encoding of the XML file. The empty string "" is in this set, as is comma "," and space " ". Please avoid using these, as they will not be supported in future Ant versions because of all the confusion they cause on command line and IDE. IDE support of unusual target names, or any target name containing spaces, varies with the IDE.

Targets beginning with a hyphen such as "-restart" are valid, and can be used to name targets that should not be called directly from the command line.
For Ants main class every option starting with hyphen is an option for Ant itself and not a target. For that reason calling these target from command line is not possible. On the other hand IDEs usually don't use Ants main class as entry point and calling them from the IDE is usually possible.

Extension-Points

since Ant 1.8.0.

Extension-Points are similar to targets in that they have a name and a depends list and can be executed from the command line. Just like targets they represent a state during the build process.

Unlike targets they don't contain any tasks, their main purpose is to collect targets that contribute to the desired state in their depends list.

Targets can add themselves to an extension-points's depends list via their extensionOf attribute. The targets that add themselves will be added after the targets of the explicit depends-attribute of the extension-point, if multiple targets add themselves, their relative order is not defined.

The main purpose of an extension-point is to act as an extension point for build files designed to be imported. In the imported file an extension-point defines a state that must be reached and targets from other build files can join the depends list of said extension-point in order to contribute to that state.

For example your imported build file may need to compile code, it might look like:

<target name="create-directory-layout">
   ...
</target>
<extension-point name="ready-to-compile"
              depends="create-directory-layout"/>
<target name="compile" depends="ready-to-compile">
   ...
</target>

Call-Graph:  create-directory-layout --> 'empty slot' --> compile

And you need to generate some source before compilation, then in your main build file you may use something like

<target name="generate-sources"
        extensionOf="ready-to-compile">
   ...
</target>

Call-Graph:  create-directory-layout --> generate-sources  --> compile

This will ensure that the generate-sources target is executed before the compile target.

Don't rely on the order of the depends list, if generate-sources depends on create-directory-layout then it must explicitly depend on it via its own depends attribute.