Moodie_559-9Front.fm Page i Tuesday, October 11, 2005 6:14 AM Pro Apache Ant ■ ■ ■ Matthew Moodie Moodie_559-9Front.fm Page ii Tuesday, October 11, 2005 6:14 AM Pro Apache Ant Copyright © 2006 by Matthew Moodie All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher. ISBN (pbk): 1-59059-559-9 Printed and bound in the United States of America 9 8 7 6 5 4 3 2 1 Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. Lead Editor: Steve Anglin Technical Reviewer: Carsten Ziegeler Editorial Board: Steve Anglin, Dan Appleman, Ewan Buckingham, Gary Cornell, Tony Davis, Jason Gilmore, Jonathan Hassell, Chris Mills, Dominic Shakeshaft, Jim Sumser Project Manager: Beth Christmas Copy Edit Manager: Nicole LeClerc Copy Editor: Kim Wimpsett Assistant Production Director: Kari Brooks-Copony Production Editor: Laura Cheu Compositor: Susan Glinert Proofreader: Kim Burton Indexer: Carol Burbo Artist: Kinetic Publishing Services, LLC Cover Designer: Kurt Krames Manufacturing Director: Tom Debolski Distributed to the book trade worldwide by Springer-Verlag New York, Inc., 233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax 201-348-4505, e-mail [email protected], or visit http://www.springeronline.com. For information on translations, please contact Apress directly at 2560 Ninth Street, Suite 219, Berkeley, CA 94710. Phone 510-549-5930, fax 510-549-5939, e-mail [email protected], or visit http://www.apress.com. The information in this book is distributed on an “as is” basis, without warranty. Although every precaution has been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in this work. The source code for this book is available to readers at http://www.apress.com in the Source Code section. Moodie_559-9Front.fm Page iii Tuesday, October 11, 2005 6:14 AM To Laura Moodie_559-9Front.fm Page iv Tuesday, October 11, 2005 6:14 AM Moodie_559-9Front.fm Page v Tuesday, October 11, 2005 6:14 AM Contents at a Glance About the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiii About the Technical Reviewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii ■ CHAPTER 1 Introducing Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 ■ CHAPTER 2 Installing Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 ■ CHAPTER 3 Using Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 ■ CHAPTER 4 Examining Ant’s Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 ■ CHAPTER 5 Building a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 ■ CHAPTER 6 Deploying an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 ■ CHAPTER 7 Running an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 ■ CHAPTER 8 Testing an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 ■ CHAPTER 9 Using Ant in Large Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 ■ CHAPTER 10 Writing Custom Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 ■ CHAPTER 11 Extending Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 ■ CHAPTER 12 Using the Ant API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 ■ INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 v Moodie_559-9Front.fm Page vi Tuesday, October 11, 2005 6:14 AM Moodie_559-9Front.fm Page vii Tuesday, October 11, 2005 6:14 AM CCoonntteennttss About the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiii About the Technical Reviewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii ■ CHAPTER 1 Introducing Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Organizing Complex Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Compiling Simple Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Compiling Larger Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Introducing the Build Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Introducing make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Introducing Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Introducing Ant Targets and Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 ■ CHAPTER 2 Installing Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Installing a Binary Ant Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Downloading a Binary Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Unpacking the Binary Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Verifying the Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Using PGP to Verify the Binary Distribution . . . . . . . . . . . . . . . . . . . . 14 Using MD5 and SHA1 to Verify the Download. . . . . . . . . . . . . . . . . . 19 Installing a Source Ant Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Downloading a Source Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Using CVS to Obtain a Source Distribution. . . . . . . . . . . . . . . . . . . . . 26 Building the Ant Source Distribution with the Build Script. . . . . . . . 26 Taking Final Steps After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Setting %ANT_HOME% on Windows . . . . . . . . . . . . . . . . . . . . . . . . . 28 Setting $ANT_HOME on Unix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 vii d10c55b52b1f8994064c85cd755fb5a9 Moodie_559-9Front.fm Page viii Tuesday, October 11, 2005 6:14 AM viii ■ CONTENTS Examining the Ant Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Looking at the bin Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Looking at the docs Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Looking at the etc Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Looking at the lib Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Upgrading Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 ■ CHAPTER 3 Using Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Running Ant from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Introducing Ant’s Build File Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Examining the Project Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Examining the Target Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Working with Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Using Built-in Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Setting Properties in the Build File . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Setting Properties in Property Files . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Summarizing the Property Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Setting Properties at the Command Line. . . . . . . . . . . . . . . . . . . . . . 56 Examining Property Precedence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Using Properties to Control a Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Using the Available Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Using the Uptodate Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Using the Condition Task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Working with Property Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Using Pathlike Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Setting a Pathlike Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Setting a Classpath Pathlike Structure. . . . . . . . . . . . . . . . . . . . . . . . 74 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 ■ CHAPTER 4 Examining Ant’s Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Using Directory-Based Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Using Pattern Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Working with Directory Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Working with File Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Working with Class File Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Working with File Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Working with Zip File Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Moodie_559-9Front.fm Page ix Tuesday, October 11, 2005 6:14 AM ■ CONTENTS ix ■ CHAPTER 5 Building a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Introducing the Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Introducing the Shared Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Introducing the Third-Party Libraries . . . . . . . . . . . . . . . . . . . . . . . . 101 Introducing the Stand-Alone Application . . . . . . . . . . . . . . . . . . . . . 102 Introducing the Web Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Introducing the Final Directory Structure. . . . . . . . . . . . . . . . . . . . . 103 Compiling Java Applications with Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Setting Up a Working Environment. . . . . . . . . . . . . . . . . . . . . . . . . . 104 Adding Third-Party Libraries to the Build. . . . . . . . . . . . . . . . . . . . . 111 Assembling the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Manipulating File Location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Creating the JAR Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Creating WAR Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Building the Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ■ CHAPTER 6 Deploying an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Building Documentation Bundles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Creating Javadocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Finishing the Bundle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Writing Ant Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Creating Zip and Tar Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Zipping the Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Tarring the Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Using the Zip and Tar Build Paths. . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Distributing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Placing the Application on an FTP Server . . . . . . . . . . . . . . . . . . . . 156 Distributing the Application via E-mail. . . . . . . . . . . . . . . . . . . . . . . 161 Deploying a Web Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 ■ CHAPTER 7 Running an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Running Java Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Running the Stand-Alone Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Redirecting Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176