Ant: The Definitive Guide Jesse Tilly Eric Burke Publisher: O'Reilly First Edition May 2002 ISBN: 0-596-00184-3, 288 pages Ant is the premier build-management tool for Java environments. Ant is part of Jakarta, the Apache Software Foundation's open source Java project repository. Ant is written entirely in Java, and is platform independent. Using XML, a Java developer describes the modules involved in a build, and the dependencies between those modules. Ant then does the rest, compiling components as necessary in order to build the application. Table of Contents Dedication ............................................................................................................................. 1 Foreword............................................................................................................................... 2 Preface................................................................................................................................... 5 Structure of This Book ....................................................................................................... 5 Audience............................................................................................................................. 7 What You Should Know .................................................................................................... 7 Which Platform and Version.............................................................................................. 7 Conventions Used in This book ......................................................................................... 7 Comments and Questions................................................................................................... 8 Acknowledgments.............................................................................................................. 9 Chapter 1. Ant Jumpstart ................................................................................................. 10 1.1 Files and Directories................................................................................................... 10 1.2 The Ant Buildfile ....................................................................................................... 11 1.3 Running Ant ............................................................................................................... 13 1.4 Ant Command-Line Reference .................................................................................. 15 1.5 Buildfile Outline......................................................................................................... 17 1.6 Learning More............................................................................................................ 17 Chapter 2. Installation and Configuration ...................................................................... 18 2.1 The Distribution ......................................................................................................... 18 2.2 Installation.................................................................................................................. 18 2.3 Configuration ............................................................................................................. 25 Chapter 3. The Buildfile .................................................................................................... 28 3.1 Why XML? ................................................................................................................ 28 3.2 Ant Building Blocks................................................................................................... 29 3.3 An Example Project and Buildfile ............................................................................. 33 3.4 The Buildfile Execution Process................................................................................ 45 3.5 AINASL: Ant Is Not a Scripting Language............................................................... 54 3.6 Buildfile Authoring Issues ......................................................................................... 56 Chapter 4. Ant DataTypes................................................................................................. 58 4.1 DataTypes Defined..................................................................................................... 59 4.2 XML Attribute Conventions ...................................................................................... 59 4.3 Argument DataType................................................................................................... 61 4.4 Environment DataType .............................................................................................. 64 4.5 FileList DataType....................................................................................................... 66 4.6 FileSet DataType........................................................................................................ 67 4.7 PatternSet DataType................................................................................................... 70 4.8 FilterSet DataType ..................................................................................................... 72 4.9 Path DataType............................................................................................................ 74 4.10 Mapper DataType..................................................................................................... 76 Chapter 5. User-Written Tasks......................................................................................... 80 5.1 The Need for Custom Tasks....................................................................................... 80 5.2 Ant's Task Model ....................................................................................................... 81 5.3 The Task Life Cycle................................................................................................... 89 5.4 An Example Through Analysis: The jar Task............................................................ 92 5.5 Miscellaneous Task Topics ...................................................................................... 106 Chapter 6. User-Written Listeners................................................................................. 109 6.1 The BuildEvent Class............................................................................................... 109 6.2 The BuildListener Interface ..................................................................................... 111 6.3 An Example: XmlLogger......................................................................................... 113 6.4 The Parallel Problem................................................................................................ 115 Chapter 7. Core Tasks ..................................................................................................... 117 7.1 Task Summary.......................................................................................................... 117 7.2 Common Types and Attributes ................................................................................ 119 7.3 Project and Target .................................................................................................... 121 7.4 Core Task Reference ................................................................................................ 124 Chapter 8. Optional Tasks............................................................................................... 212 8.1 Task Summary.......................................................................................................... 212 8.2 Optional Task Reference.......................................................................................... 213 Appendix A. The Future of Ant ...................................................................................... 300 A.1 Ant2......................................................................................................................... 300 A.2 Ant1 RIP 2002?....................................................................................................... 301 Appendix B. Ant Solutions .............................................................................................. 302 B.1 Testing Library Availability .................................................................................... 302 B.2 Cleaning Up Does More Than Keep Things Neat................................................... 303 B.3 Using Ant to Consolidate Libraries......................................................................... 303 B.4 Documenting the Buildfile's Targets ....................................................................... 305 B.5 Setting Properties Outside of the Buildfile.............................................................. 305 B.6 Using pathconvert.................................................................................................... 306 B.7 Usage Statements..................................................................................................... 307 B.8 Forking Processes.................................................................................................... 308 B.9 Using Cascading Projects and Buildfiles................................................................. 309 Colophon ........................................................................................................................... 312 Ant: The Definitive Guide Dedication For my grandmother,