Ant: The Definitive Guide

Preface

Compilation of all Java™ source files is no longer the only step necessary to build many Java-based projects. For the typical HelloWorld program, book examples, and simple applets, source file compilation is sufficient. Complex Java-based projects, like web applications or Swing-based programs (such as JBuilder), require much more. Up-to-date sources must be retrieved from source control. Dependencies not automatically handled by the Java compiler need to be managed. Various classes must be bundled and delivered to multiple locations, sometimes as JAR or WAR files. Some Java technologies, such as Enterprise Java Beans (EJB) and Remote Method Invocation (RMI) classes, need separate compilation and code generation steps not performed by the Java compiler. While shell scripts and GNU Make are often the first choice tools for performing these alternative tasks — in terms of “getting the job done,” these tools perform adequately — they turn out to be poor choices in the long run.

As functional as it may be, GNU Make leaves a lot to be desired in terms of ease-of-use. Makefiles have their own language syntax, requiring a separate knowledge set for their authors. GNU Make lacks platform-independence, requiring multiple versions of the same makefile (one for each target platform) to be maintained and distributed. The nature of shell scripts and GNU Make (remembering that GNU Make is simply a language extension on top of an existing shell) makes moving from operating system to operating system, and even from shell to shell, difficult or impossible for anyone but an expert user. While it is not unusual to use GNU Make, the time and maintenance required to follow this path is too high for modern Java-based projects.

Sun provides Java versions of all their SDK tools. Executables such as javac are simply wrappers executing the Java code. Other vendors’ tools, like BEA’s EJB compiler for WebLogic, JUnit, and the Jakarta tools and libraries are all written in Java. GNU Make can only call executables from the command line. For example, to invoke a Java class, GNU Make must use the java command to invoke the JVM, and pass the class name as a command-line argument. Make is incapable of programmatically using any of the Java tools’ libraries, such as exception and error objects. These libraries allow for a more flexible build process. A tool written in Java (such as WebLogic’s ejbc compiler) can share information from exceptions and errors with other objects (such as Ant task objects) available inside the same JVM. This serves to enhance the build process beyond command-line return codes and after-the-fact error-message string parsing.

The problems with GNU Make and the possibilities of a build tool written in Java influenced James Duncan Davidson to write Ant. Ant runs the Java compiler as a class, not as a call from the command line. Remaining inside the JVM allows for specialized code to handle errors, and for action on results Sun provides through its compiler. Ant uses XML as its buildfile syntax, therefore enhancing, rather than straining, developers’ and project managers’ skill sets. Ant extends the build process beyond just running programs, and is more properly termed a build environment than a build tool.

Structure of This Book

Ant: The Definitive Guide contains all of the knowledge a newcomer to Ant needs. For the Ant expert, Ant: The Definitive Guide is a reference, providing detailed definitions of Ant’s core tasks, discussing the main features of Ant, providing some best practices for managing projects with Ant, and explaining workarounds for some of Ant’s problems.

Chapter 1, walks through a very basic Ant buildfile example, with the intent of getting you up and running quickly. We show how to create directories, compile code, and generate a JAR file, but do not delve into the details of how everything works. The chapter also includes detailed information on Ant’s command-line usage. We conclude with a rough outline of a buildfile for use as a starter template.

Chapter 2, shows how to get Ant, install it, and configure it on Windows and Unix platforms. We list some of the pitfalls found with these development platforms, as well as provide workarounds and solutions.

Chapter 3, shows an example Ant buildfile in the context of a sample project. We dissect and describe the major parts and structures of the buildfile, explaining such things as the general flow of the Ant engine and the benefits of Ant using XML, highlighting the major parts of a buildfile.

Chapter 4, describes each of the Ant DataTypes in detail. While DataTypes are used in earlier chapters, this is where we really dig into them. We show how to use environment variables and pass command-line arguments to processes, as well as how to work with lists of files and patterns.

Chapter 5, covers one of Ant’s best features: the ability to extend Ant. With the capability to write extensions, you are able to handle anything a particular project may require. As a bonus, you can reuse your tasks in future projects, reaping benefits from your effort well beyond the initial implementation. Your tasks can even be shared and distributed publicly so that people you don’t even know can benefit from your work.

Chapter 6, covers how to design and develop your own build-event listeners. With these, you can write classes that perform operations based on the flow related to buildfile processing. These operations range from sending emails when certain complex tasks complete, to redirecting the same events to a centralized “build-listening framework.” The possibilities, just like with user-written tasks, are endless. The chapter also covers a further extension to listeners: user-written loggers. With these, you can augment or even replace Ant’s default logging system.

Chapter 7, is a comprehensive reference to the entire set of core Ant tasks. For each task, you’ll find a description, a list of Ant versions supporting the task, and definitions for all task attributes. You’ll also find helpful samples of task usage.

Chapter 8, provides a reference, similar in form to Chapter 7, for Ant’s rich library of optional tasks.

Appendix A, discusses just that. We cover future directions and expected new features, as well as suggest steps you can take to avoid using soon-to-be-obsolete features.

Appendix B, delves into some of the more common ways Ant is used to solve various build problems. Additionally, we talk about using buildfiles with cascading project structures. These are project structures with a primary project directory and many subproject subdirectories. Each subproject contains its own buildfile, and the master project has a master buildfile capable of building all of the subprojects.