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.




    Ant. The Definitive Guide
    Ant: The Definitive Guide, 2nd Edition
    ISBN: 0596006098
    EAN: 2147483647
    Year: 2003
    Pages: 115
    Authors: Steve Holzner

    Similar book on Amazon

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net