Section 3.3. Calling Other Ant Tasks

3.3. Calling Other Ant Tasks

You've seen that you can branch using true/false properties. Ant provides other powerful mechanisms for branchingthe antcall task, which you can use to call one Ant task from another, and the ant task, which calls Ant tasks in other build files.

3.3.1. Calling Ant Tasks in the Same Build File

A better way to think of antcall is that you're starting a new instance of Ant and executing targets in it. When you call an Ant target with antcall, its dependent targets are executed in order, something that can be confusing if you think you're calling a single target. Generally, it's best to do things the standard way and let Ant sort out the dependencies as it's supposed to. However, Ant can make life easier, as when you have a build file that creates a distribution for many different servers, and when varying sets of tasks need to be executed for each. (Even in cases like that, however, you can still set things up easily enough with if and unless and true/false properties.)

When you use antcall, you can think of that call as creating a new project; all the properties of the current project are available in that new project by default. The attributes of the antcall task appear in Table 3-4.

Table 3-4. The antcall attributes

Attribute	Description	Required	Default
inheritAll	If true, means the task should pass all current properties to the new Ant project. Properties passed to the new project will override the properties that are set in the new project.	No	true
inheritRefs	If true, means the task should pass all current references to the new Ant project.	No	false
target	Specifies the target you actually want to run.	Yes

You can set properties in the new project with nested param elements, which supports the same attributes as the property task. Such properties will be passed to the new project, no matter how inheritAll is set.

Properties defined on the command line cannot be overridden by nested param elements.

You can use nested reference elements to copy references from the calling project to the new project. See the attributes of this element in Table 3-5.

References from nested elements will override existing references that have been defined outside of targets in the new project but not those defined inside of targets.

Table 3-5. The reference element's attributes

Attribute	Description	Required	Default
refid	Specifies the id of the reference you want to use in the original project	Yes
torefid	Specifies the id of the reference you want to use in the new project	No	The value of refid

As of Ant 1.6, you can specify sets of properties to be copied into the new project with nested propertyset elements. This element works much like other Ant sets; you can create a set of properties and refer to them all at once by ID. This element can contain propertyref, mapper, and other propertyset elements.

Example 3-2 is an antcall example. In this case, the example calls a new target, displayMessage, to display some text. The example passes the text to display as a parameter named msg.

Example 3-2. Using antcall (ch03/antcall/build.xml)

<?xml version="1.0" ?> <project default="main">     <property name="message" value="Building the .jar file." />     <property name="src" location="source" />     <property name="output" location="bin" />     <target name="main" depends="init, compile, compress">         <antcall target="displayMessage">             <param name="msg" value="${message}"/>         </antcall>     </target>     <target name="displayMessage">         <echo message="msg=${msg}"/>     </target>        <target name="init">         <mkdir dir="${output}" />     </target>        <target name="compile">         <javac srcdir="${src}" destdir="${output}" />     </target>        <target name="compress">         <jar destfile="${output}/Project.jar" basedir="${output}"               includes="*.class" />     </target> </project>

Here's what you see when you run Ant using this build file; the msg parameter was passed to the called target:

C:\ant\ch03\antcall>ant Buildfile: build.xml init:     [mkdir] Created dir: C:\ant\ch03\antcall\bin compile:     [javac] Compiling 1 source file to C:\ant\ch03\antcall\bin compress:       [jar] Building jar: C:\ant\ch03\antcall\bin\Project.jar main: displayMessage:      [echo] msg=Building the .jar file. BUILD SUCCESSFUL Total time: 6 seconds

This is something like a subroutine call, and when using it, there's a tendency to start turning build files into programs. That's almost always a mistake, however; if you find yourself using antcall frequently, you're probably not using Ant the way it was intended. There's a tendency to start writing build files as if you were writing programming code with subroutines, but the best way to write build files is to let Ant doing its thing and check the dependencies. If this seems like this is the second time you've heard this, it is because it's that important.

3.3.2. Calling Ant Tasks in Other Build Files

The ant task is nearly identical to the antcall task, except that it lets you call targets in other build files. Using this task, you can create subproject build files, which let you divide your builds into a core build file with ant tasks to call the other build files as needed. This kind of technique can be useful when your build files are enormous and things are getting too complex to handle in single files; this is one of the ways that Ant scales to meet project needs.

Here's an example using ant, where I'm setting the value of a property named parameter and loading properties from a file:

<ant antfile="subproject/subbuild.xml">     <property name="parameter" value="4096"/>     <property file="config/subproject/build.properties"/> </ant>

You can see the attributes of this task in Table 3-6.

Table 3-6. The ant task's attributes

Attribute	Description	Required	Default
antfile	Specifies the build file where the target to call is	No	build.xml
dir	Directory where the build file is	No	The current project's basedir, unless inheritall has been set to false, in which case there is no default value
inheritAll	If true, makes the task pass all current properties to the new Ant project	No	true
inheritRefs	If true, makes the task pass all current references to the new Ant project	No	false
output	Specifies the filename where the task should write output	No
target	Specifies the target in the Ant project that you want to call	No	The new project's default target

If you don't specify a value for the antfile attribute, the file build.xml in the directory given by the dir attribute is used. If no target attribute is supplied, the default target of the new project will be used.

Passing properties to the new project works as it does with the antcall task, except that here you use nested property elements instead of param elements to pass properties. You can use nested reference elements and nested propertyset elements as with antcall.

The basedir attribute of the new project's project element is affected by the attributes dir and inheritall in ant. Take a look at Table 3-7, which shows how basedir is set based on how you set these two attributes.

Table 3-7. Using dir and inheritAll in ant

dir	inheritAll	basedir in the new project
Value assigned	true	The value of the dir attribute
Value assigned	false	The value of the dir attribute
Omitted	true	The basedir of calling project
Omitted	false	The basedir attribute of the project element of the new project

If you need to start breaking your build files up, consider the subant task, which executes Ant in various subdirectories.