< Zurück | Inhalt | Weiter >

9.4.2 The Buildfile Tags

The buildfile (usually named build.xml) begins with a header announcing that this is an XML document and specifying what version of XML is being used in it:


<?xml version="1.0"?>


The <? and ?> delimiters mark up an XML statement (as opposed to an XML tag).6 In this case, we are declaring that this is an XML document and that it is using XML version 1.0.


image

6. Note that these are the terms we are using to describe XML to a new user. They are not the formal terms for these document elements. For the proper names, consult an XML reference.


9.4.2.1 The project Tag

Every buildfile must begin with a project tag. A buildfile must contain exactly one project tag.

The project tag contains three attributes:

name

The name of the project.

default

The default target (see next section).

basedir

The base directory of the project. Usually this is “.” meaning the directory the buildfile is in.

The project name is just a name. It is not of particular importance to ant, although many IDEs that integrate ant will make use of the name attribute of the project.

The default attribute names a target tag that will be built by default if a build target is not passed to ant (see Section 9.4.2.2).


9.4.2.2 The target Tag

Every time you run ant, you are building a target. If you do not specify a target,

ant will run the target named in the default attribute of the project tag.

A project may contain any number of targets. The target tag has five attributes:

depends

The name or names of other targets that must be built before this target may be built.

description

A descriptive name for the target. Displayed when ant -projecthelp

is run.


if

Specifies a property name (see Section 4.4). The target is only built if the named property is set.


name

The name of the target. This is the name entered as an argument to ant. This is also the name that may be used in the default attribute of the project tag.

unless

This is the reverse of the if attribute. The target is built unless the property is set.


9.4.2.3 Properties

There is more than one way to set what we might call variables in ant. The only one we will concern ourselves with here is properties. Properties are like a simple hash, or associative array. They associate value, which is stored as a String, with a name, which is also a String. They behave very much like the Properties class introduced earlier in this book.7 You can use buildfile prop- erties to associate a single name with a single value that you use in multiple places throughout the buildfile to make configuration changes easier and less error-prone. Some tasks also expect certain properties to be set, as we shall soon see.

You set a property with the property tag (Example 9.2).


image

Example 9.2 A useless build.xml example to demonstrate properties

<?xml version="1.0"?>


<project name="pointless" default="useless" basedir=".">


<target name="useless">

<property name="example.utility" value="nil"/>

<echo>This example's usefulness:

${example.utility}. OK?</echo>

</target>

</project>


image


Running ant with Example 9.2 gives this output:



image

7. In fact, an examination of the ant source code reveals that ant properties are stored in a

HashTable.


$ ant

Buildfile: build.xml


useless:

[echo] This example's usefulness: nil. OK?


BUILD SUCCESSFUL

Total time: 1 second


9.4.2.4 Tasks

A task is something that must be done to build the target. There is no single “task” tag; instead, each kind of task has its own tag8 so there are many tags referred to collectively as task tags.

There are dozens of standard task tags, but only a few of them are “every- day.” We’ll introduce a few of them here, and then talk about the tags that don’t fall into the project/target/task hierarchy.

Standard task attributes. All ant task tags have at least the three attributes:


id

A unique ID for the task (not required).


taskname

A name for the task, used in logging (not required).

description

A description of the task, used for comments.

The javac task. The javac task, not surprisingly, runs the Java compiler. Note that since the Java compiler is written in Java and so is ant, there is no VM launch overhead to running the compiler. This can make ant many times faster than make simply for normal compiles.

The javac tag is one of the most complex in ant.

The javac task tag has a very large number of attributes, and may contain quite a number of other tags within it. First off, it is sensitive to a property, build.compiler, which may be used to specify that a particular Java compiler version must be used. The use of this will come up later when we build part of



image

8. In fact, task tag names correspond to the names of the Java classes that implement them. This will matter to you only if you wish to write your own ant tasks. We will not take you that far in this book.


our application using the GNU Compiler for Java, but for now, and in general, you will not set this property,9 compiling with the default compiler for the JDK version you are using. This is ant’s default behavior.

srcdir

Location of the Java source files.

destdir

Location to store the class files.

includes

Comma- or space-separated list of files (optionally using wildcards) that must be included; all .java files are included when this attribute is not specified.

excludes

Comma- or space-separated list of files (optionally using wildcards) that must be excluded; no files (except default excludes) are excluded when omitted.

classpath

The classpath to use.

sourcepath

The sourcepath to use; defaults to the value of the srcdir attribute or to nested src elements. To suppress the sourcepath switch, use sourcepath="".

classpathref

The classpath to use, given as a reference to a path defined elsewhere.

extdirs

Location of installed extensions.

nowarn

Indicates whether the -nowarn switch should be passed to the compiler; defaults to off (i.e., warnings are shown).


image

9. The one place you are likely to need to set this is when you are using a recent JDK to compile applets that you wish to work in Netscape 4.0 and IE 4.0 and older browsers. But this book doesn’t teach you Java applets. We swear.


debug

Indicates whether the source should be compiled with debug information; defaults to off. If set to off, -g:none will be passed on the command line to compilers that support it (for other compilers, no command-line argument will be used). If set to true, the value of the debuglevel attribute determines the command-line argument.

debuglevel

Keyword list to be appended to the -g command-line switch. This will be ignored by all implementations except modern and classic (version 1.2 and more recent). Legal values are none or a comma-separated list of the fol- lowing keywords: lines, vars, and source. If debuglevel is not specified (by default) nothing will be appended to -g. If debug is not turned on, this attribute will be ignored.

optimize

Indicates whether compilation should include optimization; defaults to off.

deprecation

Indicates whether source should be compiled with deprecation informa- tion; defaults to off.

verbose

Asks the compiler for verbose output; defaults to no.

depend

Enables dependency tracking for compilers that support this (Jikes and classic).

The jar task. The jar task makes a JAR file.

The javadoc task. One of the greatest benefits of developing in Java is the nearly automatic generation of thorough and correct documentation. Javadoc is the tool that does the job, and the javadoc task is the way to automate document production in ant. This tag has a number of attributes that specify where the source to be documented is located, how the documentation is to be produced, and where the documentation is to be placed.

The copy and mkdir tasks. These tasks are used to copy files and make directories.


The rmic task. Remote Method Invocation is a distributed computing technology (Section 5.8). RMI requires the generation of server and stub classes that provide the networking support for an RMI-enabled class. This is normally done by the rmic compiler, and this is one of the common reasons the Java programmers turn to build automation tools. The rmic tag allows ant to build RMI classes.


9.4.2.5 Other Tags

So far we have ignored a major component of ant. In order to introduce it, we need to give you a (painfully) high-level view of how ant works “under the hood.”

Task tags actually map directly to Java classes that implement the tasks. Each task class is an instance of the Task class (in other words, it is a Java class that either directly or indirectly extends the Task class). This is how you can write your own tasks—download the ant source code and write your classes that extend the Task class.

Tasks are not, however, the only tags that map to Java classes. There is another category of tags that do so. They are called datatypes. These are classes that directly or indirectly extend the ant DataType class.

Generally speaking, a task may require zero to many datatypes to specify the data with which the task works. Some such tags include the manifest tag used in our sample build.xml file discussed later in this chapter.

We’ll mention a couple of the most frequently used datatype tags here and leave looking up the details as an exercise for you.

The PatternSet, Include, and Exclude datatypes. As you may have noticed, the most common tags we have covered allow you to specify the files to be processed using the tag’s attributes. Usually, you nominate a base directo- ry and let the task tag process everything in that directory.

There are times, however, when you need finer grained control than that. For example, you might wish to exclude all Java classes whose names end in “Test” (Example 9.3).

Other datatypes. There are many other datatypes used for various purposes. One of them, FilterSet, is able to modify files before they are copied or moved. This can be useful, for example, to put build information into a source file for an About dialog.


image

Example 9.3 Using the PatternSet datatype

<patternset id="nontest.source">

<include name="**/*.java">

<exclude name="**/*Test.java">

<patternset>


<target name="build">

<javac destdir="build">

<src path="src"/>

<patternset refid="nontest.source"/>

</javac>

</target>


image


In general, datatypes give you more sophisticated control than do the at- tributes of a task. Take a look at the Ant User’s Manual 10 for full details on ant.