Ant: The Definitive Guide

Conventions Used in This book

The following typographical conventions are used in this book:

Italic

Used for Unix and Windows commands, filenames and directory names, emphasis, and first use of a technical term.

Constant width

Used in code examples and to show the contents of files. Also used for Java class names, Ant task names, tags, attribute names, and environment variable names appearing in the text.

Constant width italic

Used in syntax descriptions to indicate user-defined items.

Constant width bold

Used for user input in examples showing both input and output.

Terminology

For consistency, in this book we refer to an Ant instruction file as a buildfile. In other Ant-related forums and documentation, you may encounter the terms build.xml and antfile. These terms are interchangeable, but buildfile is the preferred term.

When referring to XML, we use the convention that a tag refers to a bracket-delimited markup in the buildfile. For example, <path> is a tag. The term element refers to both a tag and its children, should it have any. The following XML markup is an example of a <path> element. The distinction between tag and element is that the term tag refers only to <path>, while element refers to everything from <path> through </path>.

<path>
    <fileset dir="src">
        <includes name="**/*.java"/>
    </fileset>
</path>

XML elements and tags define Ant tasks and DataTypes in the buildfile. Tasks perform operations and act as the modular part of the Ant engine. DataTypes define complex groupings of data, typically paths or file sets, for the Ant engine.

Filename and Path Conventions

Ant is a Java program and adopts Java’s “agnostic” viewpoint towards filesystems. When run, Ant checks for the path separator and directory separator characters, provided by the underlying JVM, and uses those values. It successfully interprets either the ';' or the ':' inside of the buildfile. For example, when run on a Unix machine, Ant interprets the path dir;dir\\subdir (note the escaped '\') correctly as dir:dir/subdir. Separators must be used consistently within the same value type; the string dir;dir/subdir, combining a Windows path separator (;) and a Unix directory separator (/), is not good form. Throughout this book, Unix and Windows file path conventions will be interspersed in the examples to emphasize the fact that Ant does not care which you use.

Ant does not handle drive letters across platforms. Using drive letters in Ant path elements will restrict a buildfile’s use to Windows environments.