How-To Guides
Getting Started
Policy Strategies
Format Strings
Extending Antlion
First Tutorial: Simple
Ant Tasks
inner processors
inner repositories
Optional Tasks
About optional tasks
Prev   Next  
Antlion Libraries

Antlion uses the term library to refer to the common build concept of a collection of files or directories that the build requires to perform some tasks. Usually, a library contains JAR files and/or class directories used for compiling, testing, and running Java code in a build.

Commonly, to be useful, an Ant build will define properties, paths, and filesets for its various libraries. This causes some difficulties when libraries contain libraries; Ant's filesets can't contain other filesets.

Antlion codifies the common concept of a library into new Ant tasks, so that all the definitions of the Ant properties and references get set in one location.

In order to solve this problem, Antlion breaks the library problem into three pieces: repositories, processors, and entries. There are also collections of repositories and processors, called policies, and collections of entries, called libraries. Antlion contains all these settings inside a <libraryDef> task


An entry represents a single file or directory. This file may be generated by the current build, generated by another build (called an artifact), or from a pre-generated directory pool (generally referred to as third-party libraries).

An entry contains meta-data about the corresponding source. It shouldn't directly reference the file, as that's the respository responsibility.

The meta-data for an entry is in the form of attributes, name-value pairs that the repositories use to determine the actual file location, and processors use to generate Ant properties and references.


A library represents a collection of entries and other libraries that are grouped together for processors to act upon. A <libraryDef> may contain multiple libraries.

A library may only contain references to other libraries, not whole other libraries. This keeps the XML structure flat and easier to read. Referenced libraries will "publish" their entries to the owning library, so that processors will see the owning library's collection as a simple set of entries. Repositories do not search for files inside referenced libraries.


A repository represents a base directory and how to resolve library entries into files or directories within that repository. A <libraryDef> may contain multiple repositories.

The repository looks at the repository setup and the entry's meta-data to discover the corresponding file. If the repository doesn't contain a file for the given entry, then it reports a no-match, and the next repository in the <libraryDef> attempts to find the entry's file. For this reason, a <libraryDef> must keep its repositories ordered in a well-defined manner.

The <libraryDef> searches each entry in every library for its file. Even though a library may reference another library, that referenced library's entries do not get searched in the local <libraryDef>. Rather, it is the responsibility of that referenced library's <libraryDef> to search that library's entries.

A repository may be marked as an "artifact repository" (using the artifact="true" attribute) meaning that files under its directory have the potential to not exist when the Ant build file is executed. Entries which are marked as "artifact" (also using the artifact="true" attribute) tell the artifact repository to not check if the file exists in order to include it. In this way, a set of protections for the user exist: an entry will only be included in a repository if it exists when the build file is executed; the only exception being that artifact repositories will include artifact entries, even if they don't exist. Therefore, it does not make sense to have two artifact repositories in a libraryDef; only the first one will find the artifact entries.

Repositories look for a unique attribute in each entry called "location." If that's set, then the repository will assume that the value of that attribute is the location on the local file system corresponding to the entry. In this way, entries can be "hard-coded" to well known files. Note that the repositories don't care if the file in the "location" attribute exists or not.


A processor represents an action upon a library or library entry in order to augment the Ant project, by adding properties, or reference objects, or altering the library entries themselves. A processor must be contained within a policy.

Antlion provides a set of common processors that should meet most Ant-usage patterns. Since Antlion doesn't expect to know all the different things you may want to do with a bundle of files, custom processors may be added to a policy.


A policy defines a collection of configured processors and a set of repositories that should be used for a project. Having all of these defined in a central location helps keep the maintenance down and project cohesiveness up. For each new <libraryDef>, you only have to specify the reference ID of the policy, and not several tags for the type and repositories, and likewise adding new repositories or modifying the types is done in only one place. Also, a single type means that each <libraryDef> will modify the Ant project in a well-known way.

Antlion supports the ability to have policy inheritance, but this should be used with caution, as multiple types of policies can quickly render a build script unreadable.

Prev   Next  
Document version $Revision: 1.10 $ $Date: 2005/10/27 19:54:00 $

SourceForge Logo
Copyright © 2004-2006, The Antlion Project