spelling patch by Kev Jackson

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@277995 13f79535-47bb-0310-9956-ffa450edef68
20 years ago · 6b21c7c998
--- a/docs/ant_in_anger.html
+++ b/docs/ant_in_anger.html
@@ -13,7 +13,7 @@

 <h4  align="center">
 Steve Loughran<br>
 Last updated 2002-11-09
 Last updated 2005-03-16
 </h4>

 <a name="introduction">
@@ -22,15 +22,15 @@ Last updated 2002-11-09
 </a>

 <a href="http://ant.apache.org/">Apache Ant</a>
 can be an invaluable tool in a team development process -or it can
 can be an invaluable tool in a team development process - or it can
 be yet another source of problems in that ongoing crises we call
 development . This
 document contains some strategies and tactics for making the most of
 Ant. It is moderately frivolous in places, and lacks almost any actual
 examples of Ant xml. The lack of examples is entirely deliberate -it
 examples of Ant XML. The lack of examples is entirely deliberate - it
 keeps document maintenance costs down. Most of the concepts covered
 don't need the detail about XML representations, as it is processes we
 are concerned about, not syntax. Finally, please be aware that the
 don't need the detail provided by XML representations, as it is the processes we
 are concerned about, not the syntax. Finally, please be aware that the
 comments here are only suggestions which need to be customised to meet
 your own needs, not strict rules about what should and should not be
 done.
@@ -44,10 +44,10 @@ document covers:
 <li> Team efforts, usually with the petulant prima-donnas all us Java
 programmers become once we realise how much in demand we are.

 <li> A fairly distributed development team -spread across locations and
 <li> A fairly distributed development team - spread across locations and
 maybe time zones.

 <li> Separate sub projects -from separate beans in a big
 <li> Separate sub projects - from separate beans in a big
 enterprise application to separate enterprise applications which need to
 be vaguely aware of each other.

@@ -58,7 +58,6 @@ late next century the date coming up from below.
 <li> Everyone is struggling to keep up with platform and tool evolution.

 <li> Extensive use of external libraries, both open and closed source.

 </ul>

 What that all means is that there is no time to spend getting things
@@ -74,21 +73,19 @@ the other problems.
 <h3>
 Clarify what you want Ant to do</h3>


 Ant is not a silver bullet. It is just another rusty bullet in the armory of
 development tools available at your disposal. Its primary purpose is to
 accelerate the construction and deployment of Java projects. You could certainly
 extend Ant to do anything Java makes possible: it is easy to imagine writing an
 image processing task to help in web site deployment by shrinking and
 recompressing jpeg files, for example. But that would be pushing the boundary of
 what Ant is really intended to do -so should be considered with care.

 <P>
 what Ant is really intended to do - so should be considered with care.

 <p>
 Ant is also a great adjunct to an IDE; a way of doing all the housekeeping of
 deployment and for clean, automated builds. But a good modern IDE is a
 productivity tool in its own right -one you should consider keeping using. Ant
 just lets you give the teams somewhat more freedom in IDE choice -&quot;you can
 productivity tool in its own right - one you should continue to use. Ant
 just lets you give the teams somewhat more freedom in IDE choice - &quot;you can
 use whatever you want in development, but Ant for the deployment
 builds&quot; Now that many modern open source and commercial IDEs
 include Ant support (including jEdit, Forte, Eclipse and IDEA),
@@ -99,18 +96,17 @@ build process integrated into the tool.
 Define standard targets
 </h3>


 When you have multiple sub projects, define a standard set of targets.
 Projects with a split between interface and implementation jar files
 could consider <b>impl</b> and <b>intf</b> targets -with separate
 <b>debug-impl</b>and <b>debug-intf</b> targets for the debug version.
 could consider <b>impl</b> and <b>intf</b> targets - with separate
 <b>debug-impl</b> and <b>debug-intf</b> targets for the debug version.
 And of course, the ubiquitous <b>clean</b> target.

 <P>
 <p>

 With standard target names, it is easy to build encompassing Ant build
 files which just hand off the work to the classes below using the
 <a href="manual/CoreTasks/ant.html">&lt;ant&gt;</a>
 <a href="manual/CoreTasks/ant.html">ant</a>
 task. For example. the clean target could be handed down to the <tt>intf</tt> and
 <tt>impl</tt> subdirectories from a parent directory

@@ -138,31 +134,29 @@ If Ant does not do what you want, you can use the
 <a href="manual/CoreTasks/exec.html">exec</a> and
 <a href="manual/CoreTasks/java.html">java</a> tasks or
 <a href="manual/OptionalTasks/script.html">inline scripting</a> to extend it. In a
 project with many build.xml files, you soon find that having a single
 project with many <tt>build.xml</tt> files, you soon find that having a single
 central place for implementing the functionality keeps maintenance
 overhead down. Implementing task extensions through Java code seems
 extra effort at first, but gives extra benefits:-

 <ul>

 <li>Cross platform support can be added later without changing any
 build.xml files</li>
 <tt>build.xml</tt> files</li>

 <li>The code can be submitted to the Ant project itself, for other
 people to use and maintain</li>

 <li>It keeps the build files simpler</li>

 </ul>

 In a way, it is it this decoupling of functionality, "the tasks", from
 In a way, it is this decoupling of functionality, "the tasks", from
 the declaration of use, "the build file", that has helped Ant succeed.
 If you have to get something complex done in Make or an IDE, you have a
 hairy makefile that everyone is scared of, or an IDE configuration that
 is invariably very brittle. But an Ant task is reusable and shareable
 among all Ant users. Many of the core and optional tasks in Ant today,
 tasks you do or will come to depend on, were written by people trying to
 solve their own pressing problems. 
 solve their own pressing problems.

 <h3>
 Embrace Automated Testing
@@ -170,7 +164,6 @@ Embrace Automated Testing

 <b>(alternatively "recriminate early, recriminate often")</b>
 <p>

 Ant lets you call <a href="manual/OptionalTasks/junit.html">JUnit</a>
 tasks, which unit test the code your team has written. Automated testing
 may seem like extra work at first, but JUnit makes writing unit tests so
@@ -178,12 +171,10 @@ easy that you have almost no reason not to. Invest the time in learning
 how to use JUnit, write the test cases, and integrate them in a 'test'
 target from Ant so that your daily or hourly team build can have the
 tests applied automatically. One of the free to download chapters of
 <a href="http://manning.com/antbook/">Java Development with Ant</a>
 <a href="http://manning.com/hatcher">Java Development with Ant</a>
 shows you how to use JUnit from inside Ant.  

 <p>


 Once you add a way to fetch code from the SCM system, either as an Ant
 task, in some shell script or batch file or via some continuous
 integration tool. the integration test code can be a pure Ant task run
@@ -194,10 +185,9 @@ used even though no developer would willingly use that configuration
 given the choice.

 <p>

 System tests are harder to automate than unit tests, but if you can
 write java code to stress large portions of the system -even if the code
 can not run as JUnit tasks- then the <a href= "manual/CoreTasks/java.html">java</a>
 write java code to stress large portions of the system - even if the code
 can not run as JUnit tasks - then the <a href= "manual/CoreTasks/java.html">java</a>
 task can be used to invoke them. It is best to specify that you want a
 new JVM for these tests, so that a significant crash does not break the
 full build. The Junit extensions such as 
@@ -205,36 +195,33 @@ full build. The Junit extensions such as
 <a href="http://jakarta.apache.org/cactus/">Cactus</a> for J2EE and servlet 
 testing help to expand the testing framework. To test properly you will still
 need to invest a lot of effort in getting these to work with your project, and 
 deriving great unit, system and regression tests -but your customers will love 
 deriving great unit, system and regression tests - but your customers will love 
 you for shipping software that works.   


 <h3>Learn to Use and love the add-ons to Ant</h3>
 The Ant distribution is not the limit of the Ant universe, it is only
 the beginning. Look at the 
 <A href="http://ant.apache.org/external.html">
 <a href="http://ant.apache.org/external.html">
 External Tools and Tasks page
 </A> for an up to date list. Here are some of them that .
 </a> for an up to date list. Here are some of them that .

 <ul>
 <li>
 <a href="http://checkstyle.sourceforge.net/">Checkstyle</a><br>
 This tool audits your code and generates HTML reports of wherever any
 style rule gets broken. Nobody can hide from the code police now! tip:
 start using this early, so the corrections are less.
 start using this early, so there's less to correct.</li>
 <li>
 <A href="http://ant-contrib.sf.net/">Ant-contrib</A><br>
 <a href="http://ant-contrib.sf.net/">Ant-contrib</a><br>
 This sourceforge project contains helper tasks that are kept separate
 from core Ant for ideological purity; the foreach and trycatch tasks in
 particular. These give you iteration and extra error handling. Also on
 the site is the &lt;cc&gt; task suite, that compile and link native code
 on a variety of platforms.

 on a variety of platforms.</li>
 <li>
 <a href="http://xdoclet.sourceforge.net/">XDoclet</a>

 XDoclet adds attributed oriented programming to Java. By adding javadoc
 tags to your code you can have XDoclet automatically generate web.xml
 tags to your code you can have XDoclet automatically generate <tt>web.xml</tt>
 descriptors, taglib descriptors, EJB interfaces, JMX interface classes,
 Castor XML/SQL bindings, and many more. The key here is that all those
 fiddly little XML files you need to create, and those interfaces EJB and
@@ -242,40 +229,36 @@ JMX requires to implement, all can be autogenerated from your Java
 code with a few helper attributes. This reduces
 errors and means you can change your code and have the rest of the app
 take its cue from the source. Never do EJB, JMX or webapps without it!

 </li>
 </ul>


 <a name="crossplatform">
 <h2>
 Cross Platform Ant
 </h2>
 </a>

 Ant is the best foundation for cross platform Java development and
 testing to date. But if you are not paying attention, it is possible to
 produce build files which only work on one platform -or indeed, one
 produce build files which only work on one platform - or indeed, one
 single workstation.

 <p>

 The common barriers to cross-platform Ant are the use of command line
 tools (exec tasks) which are not portable, path issues, and hard coding
 in the location of things.

 <h3>Command Line apps: <a href="manual/CoreTasks/exec.html">Exec</a>/
 <h3>Command Line apps: <a href="manual/CoreTasks/exec.html">Exec</a> /
 <a href= "manual/CoreTasks/apply.html">Apply</a></h3>

 The trouble with external invocation is that not all functions are found
 cross platform, and those that are often have different names -DOS
 descendants often expect .exe or .bat at the end of files. That can be
 cross platform, and those that are often have different names - DOS
 descendants often expect <tt>.exe</tt> or <tt>.bat</tt> at the end of files. That can be
 bad if you explicitly include the extension in the naming of the command
 (don't!), good when it lets you keep the unix and DOS versions of an
 executable in the same bin directory of the project without name
 clashes arising.

 <p>

 Both the command line invocation tasks let you specify which platform
 you want the code to run on, so you could write different tasks for each
 platform you are targeting. Alternatively, the platform differences
@@ -295,44 +278,41 @@ This difference between platforms (indeed, the whole java classpath
 paradigm) can cause hours of fun.

 <p>

 Ant reduces path problems; but does not eliminate them entirely. You
 need to put in some effort too. The rules for handling path names are
 that 'DOS-like pathnames are handled', 'Unix like paths are handled'.
 Disk drives -'C:'- are handled on DOS-based boxes, but placing them in
 the build.xml file ruins all chances of portability. Relative file paths
 are much more portable. Semicolons work as path separators -a fact which
 the <tt>build.xml</tt> file ruins all chances of portability. Relative file paths
 are much more portable. Semicolons work as path separators - a fact which
 is useful if your Ant invocation wrapper includes a list of jars as a
 defined property in the command line. In the build files you may find it
 better to build a classpath by listing individual files (using location=
 attributes), or by including a fileset of *.jar in the classpath
 attributes), or by including a fileset of <tt>*.jar</tt> in the classpath
 definition.
 <p>
 There is also the <a
 href="manual/CoreTasks/pathconvert.html">PathConvert</a> task which
 can put a fully resolved path into a property. Why do that? Because then 
 you can use that path in other ways -such as pass it as a parameter to 
 you can use that path in other ways - such as pass it as a parameter to 
 some application you are calling, or use the replace task to patch it
 into a localised shell script or batch file.
 <p>
 Note that DOS descended file systems are case insensitive (apart from
 the obscure aberration of the WinNT POSIX subsystem run against NTFS),
 and that Windows pretends that all file extensions with four or more
 letters are also three letter extensions (try DELETE *.jav in your java
 letters are also three letter extensions (try <tt>DELETE *.jav</tt> in your java
 directories to see a disastrous example of this).

 <p>

 Ant's policy on case sensitivity is whatever the underlying file system
 implements, and its handling of file extensions is that *.jav does not
 find any .java files. The Java compiler is of course case sensitive -you can
 implements, and its handling of file extensions is that <tt>*.jav</tt> does not
 find any <tt>.java</tt> files. The Java compiler is of course case sensitive - you can
 not have a class 'ExampleThree' implemented in "examplethree.java".

 <p>

 Some tasks only work on one platform -<a href= "manual/CoreTasks/chmod.html">
 Some tasks only work on one platform - <a href= "manual/CoreTasks/chmod.html">
 Chmod</a> being a classic example. These tasks usually result in just a
 warning message on an unsupported platform -the rest of the target's
 warning message on an unsupported platform - the rest of the target's
 tasks will still be called. Other tasks degrade their functionality on
 platforms or Java versions. In particular, any task which adjusts the
 timestamp of files can not do so properly on Java 1.1. Tasks which can
@@ -341,63 +321,56 @@ href="manual/CoreTasks/touch.html">Touch</a> and <A href="manual/CoreTasks/unzip
 Unjar/Unwar/Unzip</a> for example, degrade their functionality on
 Java1.1, usually resorting to the current timestamp instead.


 <p>

 Finally, Perl makes a good place to wrap up Java invocations cross
 platform, rather than batch files. It is included in most Unix
 distributions, and is a simple download for <a href=
 "http://www.activestate.com/Products/ActivePerl/"> Win32 platforms from
 ActiveState</a>. A Perl file with .pl extension, with the usual Unix
 "http://www.activestate.com/Products/ActivePerl/">Win32 platforms from
 ActiveState</a>. A Perl file with <tt>.pl</tt> extension, the usual Unix
 path to perl on the line 1 comment and marked as executable can be run
 on Windows, OS/2 and Unix and hence called from Ant without issues. The
 perl code can be left to resolve its own platform issues. Don't forget to
 set the line endings of the file to the appropriate platform when you
 redistribute Perl code; <a
 href="manual/CoreTasks/fixcrlf.html">&lt;fixCRLF&gt;</a> 
 href="manual/CoreTasks/fixcrlf.html">fixCRLF</a> 
 can do that for you.

 <a name="team">
 <h2>Team Development Processes</h2>
 </a>

 Even if each team member is allowed their choice of IDE/editor, or even
 OS, you need to set a baseline of functionality on each box. In
 particular, the JDKs and jars need to be in perfect sync. Ideally pick
 the latest stable Java/JDK version available on all developer/target
 systems and stick with it for a while. Consider assigning one person to
 be the contact point for all tools coming in -particularly open source
 be the contact point for all tools coming in - particularly open source
 tools when a new build is available on a nightly basis. Unless needed,
 these tools should only really be updated monthly, or when a formal
 release is made.

 <p>

 Another good tactic is to use a unified directory tree, and add on extra
 tools inside that tree. All references can be made relative to the tree.
 If team members are expected to add a directory in the project to their
 path, then command line tools can be included there -including those
 path, then command line tools can be included there - including those
 invoked by Ant exec tasks. Put everything under source code control and
 you have a one stop shop for getting a build/execute environment purely
 from CVS or your equivalent.


 <a name="deploying">
 <h2>Deploying with Ant</h2>
 </a>

 One big difference between Ant and older tools such as Make is that the
 processes for deploying Java to remote sites are reasonably well
 evolved in Ant. That is because we all have to do it these days, so
 many people have put in the effort to make the tasks easier.
 <p>

 Ant can <a href="manual/CoreTasks/jar.html">Jar</a>, <a href=
 "manual/CoreTasks/tar.html"> Tar</a> or <a
 "manual/CoreTasks/tar.html">Tar</a> or <a
 href="manual/CoreTasks/zip.html">Zip</a> files for deployment, while the
 <a href="manual/CoreTasks/war.html">War</a> task extends the jar task
 for better servlet deployment. 
 <a href = "manual/OptionalTasks/jlink.html">Jlink</a> is a
 <a href ="manual/OptionalTasks/jlink.html">Jlink</a> is a
 jar generation file which lets you merge multiple sub jars. This is
 ideal for a build process in which separate jars are generated by sub
 projects, yet the final output is a merged jar. <a href=
@@ -405,36 +378,32 @@ projects, yet the final output is a merged jar. <a href=
 build a cab file which is useful if you still have to target IE deployment.

 <p>

 The <a href = "index.html#ftp">ftp</a> task lets you move stuff up to a
 server. Beware of putting the ftp password in the build file -a property
 The <a href="index.html#ftp">ftp</a> task lets you move stuff up to a
 server. Beware of putting the ftp password in the build file - a property
 file with tight access control is slightly better. The <a href=
 "manual/CoreTasks/fixcrlf.html">FixCRLF task</a> is often a useful interim step if
 "manual/CoreTasks/fixcrlf.html">FixCRLF</a> task is often a useful interim step if
 you need to ensure that files have Unix file extensions before upload. A
 WebDav task has long been discussed, which would provide a more secure
 upload to web servers, but it is still in the todo list. Rumour has it
 that there is such a task in the jakarta-slide libraries. With MacOS X,
 Linux and Windows XP all supporting WebDAV file systems, you may even be able
 to use <a href="manual/CoreTasks/copy.html">&lt;copy&gt;</a> to deploy
 to use <a href="manual/CoreTasks/copy.html">copy</a> to deploy
 though a firewall. 

 <p>

 EJB deployment is aided by the <a href="manual/OptionalTasks/ejb.html">ejb tasks</a>,
 EJB deployment is aided by the <a href="manual/OptionalTasks/ejb.html">ejb</a> tasks,
 while the 
 <a
 href="manual/OptionalTasks/serverdeploy.html">&lt;serverdeploy&gt;</a>
 href="manual/OptionalTasks/serverdeploy.html">serverdeploy</a>
 suite can deploy to multiple servers. The popularity of Ant has
 encouraged vendors to produce their own deployment tasks which they
 redistribute with their servers. For example, the Tomcat4.1 installation
 includes tasks to deploy, undeploy and reload web applications.

 <p>

 Finally, there are of course the fallbacks of just copying files to a
 destination using <a href="manual/CoreTasks/copy.html">Copy</a> and <a href =
 "index.html#copydir">Copydir</a> , or just sending them to a person or
 process using <a href= "manual/CoreTasks/mail.html">Mail</a> or the attachment
 destination using <a href="manual/CoreTasks/copy.html">Copy</a> and <a href="index.html#copydir">Copydir</a> , or just sending them to a person or
 process using <a href="manual/CoreTasks/mail.html">Mail</a> or the attachment
 aware <a href= "manual/OptionalTasks/mimemail.html">MimeMail</a>.
 In one project our team even used Ant to build CD images through a build followed
 by a long set of Copy tasks, which worked surprisingly well, certainly
@@ -450,7 +419,7 @@ through SSH.
 How you structure your directory tree is very dependent upon the
 project. Here are some directory layout patterns which can be used as
 starting points. All the jakarta projects follow a roughly similar
 style, which makes it easy to navigate around one form one project to
 style, which makes it easy to navigate around one from one project to
 another, and easy to clean up when desired. 

 <h3>Simple Project</h3>
@@ -460,7 +429,7 @@ The project contains sub directories
 <tr>
    <td><b>bin</b>
    </td>
    <td>common binaries, scripts -put this on the path.
    <td>common binaries, scripts - put this on the path.
    </td>
 </tr>

@@ -501,43 +470,38 @@ The project contains sub directories

 The bin, lib, doc and src directories should be under source code control.
 Slight variations include an extra tree of content to be included in the
 distribution jars -inf files, images, etc. These can go under source
 too, with a <tt>metadata</tt> directory for web.xml and similar
 manifests, and a <tt>web</tt> folder for web content -JSP, html, images
 distribution jars - inf files, images, etc. These can go under source
 too, with a <tt>metadata</tt> directory for <tt>web.xml</tt> and similar
 manifests, and a <tt>web</tt> folder for web content - JSP, html, images
 and so on. Keeping the content in this folder (or sub hierarchy)
 together makes it easier to test links before deployment. The actual
 production of a deployment image -such as a war file- can be left to the
 production of a deployment image, such as a war file, can be left to the
 appropriate Ant task: there is no need to completely model your source tree 
 upon the deployment hierarchy. 
 <p> 

 Javadoc output can be
 directed to a doc/ folder beneath build/, or to doc/javadoc.
 directed to a <tt>doc/</tt> folder beneath <tt>build/</tt>, or to <tt>doc/javadoc</tt>.

 <h3>Interface and Implementation split</h3>

 If the interface is split from the implementation code then this can be
 supported with minor changes just by having a separate build path for
 the interface directory -or better still just in the jar construction:
 the interface directory - or better still just in the jar construction:
 one jar for interface and one jar for implementation.


 <h3>Loosely Coupled Sub Projects</h3>

 In the loosely coupled approach multiple projects can have their own
 copy of the tree, with their own source code access rights.
 One difference to consider is only having one instance of the bin and
 lib directories across all projects. This is sometimes good -it helps
 keep copies of xerces.jar in sync, and sometimes bad -it can update
 lib directories across all projects. This is sometimes good - it helps
 keep copies of xerces.jar in sync, and sometimes bad - it can update
 foundational jar files before unit testing is complete.

 <p>

 To still have a single build across the sub projects, use parent
 build.xml files which call down into the sub projects.

 <tt>build.xml</tt> files which call down into the sub projects.
 <p>

 This style works well if different teams have different code
 access/commitment rights. The risk is that by giving extra leeway to the
 sub projects, you can end up with incompatible source, libraries, build
@@ -555,16 +519,15 @@ an automated, continuous, background build process.

 Tightly coupled projects have all the source in the same tree; different
 projects own different subdirectories. Build files can be moved down to
 those subdirectories (say src/com/iseran/core and src/com/iseran/extras),
 or kept at the top -with independent build files named core.xml and
 extras.xml
 those subdirectories (say <tt>src/com/iseran/core</tt> and <tt>src/com/iseran/extras</tt>),
 or kept at the top - with independent build files named <tt>core.xml</tt> and
 <tt>extras.xml</tt>.

 <p>

 This project style works well if everyone trusts each other and the
 sub projects are not too huge or complex. The risk is that a split to a
 more loosely coupled design will become a requirement as the projects
 progress -but by the time this is realised schedule pressure and
 progress - but by the time this is realised schedule pressure and
 intertwined build files make executing the split well nigh impossible.
 If that happens then just keep with it until there is the time to
 refactor the project directory structures. 
@@ -576,34 +539,31 @@ refactor the project directory structures.
 </a>

 Once you start using Ant, you should have a policy on when and how the
 team updates their copies. A simple policy is "every official release
 team updates their copies. A simple policy is &quot;every official release
 after whatever high stress milestone has pushed all unimportant tasks
 (like sleep and seeing daylight) on the back burner". This insulates you
 (like sleep and seeing daylight) on the back burner&quot;. This insulates you
 from the changes and occasional instabilities that Ant goes through
 during development. Its main disadvantage is that it isolates you from
 the new tasks and features that Ant is constantly adding.

 <p>

 Often an update will require changes to the build.xml files. Most
 Often an update will require changes to the <tt>build.xml</tt> files. Most
 changes are intended to be backwards compatible, but sometimes an
 incompatible change turns out to be
 necessary. That is why doing the update in the lull after a big
 milestone is important. It is also why including ant.jar and related
 milestone is important. It is also why including <tt>ant.jar</tt> and related
 files in the CVS tree helps ensure that old versions of your software
 can be still be built.

 <p>

 The most aggressive strategy is to get a weekly or daily snapshot of the
 ant source, build it up and use it. This forces you to tweak the
 build.xml files more regularly, as new tasks and attributes can take
 <tt>build.xml</tt> files more regularly, as new tasks and attributes can take
 while to stabilise. You really have to want the new features, enjoy
 gratuitous extra work or take pleasure in upsetting your colleagues to
 take this approach.

 <p>

 Once you start extending Ant with new tasks, it suddenly becomes much
 more tempting to pull down regular builds. The most recent Ant builds
 are invariably the best platform for writing your extensions, as you
@@ -611,10 +571,10 @@ can take advantage of the regular enhancements to the foundational
 classes. It also prevents you from wasting time working on something
 which has already been done. A newly submitted task to do something
 complex such as talk to EJB engines, SOAP servers or just convert a text
 file to uppercase may be almost exactly what you need -so take it,
 file to uppercase may be almost exactly what you need - so take it,
 enhance it and offer up the enhancements to the rest of the world. This
 is certainly better than starting work on your 'text case converter'
 task on Ant 0.8 in isolation, announcing its existence six months latter
 task on Ant 0.8 in isolation, announcing its existence six months later
 and discovering that instead of adulation all you get are helpful
 pointers to the existing implementation. The final benefit of being
 involved with the process is that it makes it easier for your tasks to 
@@ -624,9 +584,8 @@ If that happens you can revert to an official Ant release, and get on
 with all the other crises. 

 <p>

 You should also get on the <a href =
 "mailto:dev-subscribe@ant.apache.org" > dev mailing list
 "mailto:dev-subscribe@ant.apache.org">dev mailing list
 </a>, as it is where the other developers post their work, problems and
 experience. The volume can be quite high: 40+ messages a day, so
 consider routing it to an email address you don't use for much else. And
@@ -638,30 +597,27 @@ distraction.
 Installing with Ant.
 </h2>
 </a>

 Because Ant can read environment variables, copy, unzip and delete files
 and make java and OS calls, it can be used for simple installation
 tasks. For example, an installer for tomcat could extract the
 environment variable TOMCAT_HOME, stop tomcat running, and copy a war
 file to TOMCAT_HOME/webapps. It could even start tomcat again, but the
 environment variable <tt>TOMCAT_HOME</tt>, stop tomcat running, and copy a war
 file to <tt>TOMCAT_HOME/webapps</tt>. It could even start tomcat again, but the
 build wouldn't complete until tomcat exited, which is probably not what
 was wanted. 

 <p>

 The advantage of using Ant is firstly that the same install targets
 can be used from your local build files (via an <tt>ant</tt> invocation
 of the install.xml file), and secondly that a basic install target is
 of the <tt>install.xml</tt> file), and secondly that a basic install target is
 quite easy to write. The disadvantages of this approach are that the
 destination must have an up to date version of Ant correctly
 pre-installed, and Ant doesn't allow you to handle failures well -and a
 pre-installed, and Ant doesn't allow you to handle failures well - and a
 good installer is all about handling when things go wrong, from files
 being in use to jar versions being different. This means that Ant is not
 suited for shrink wrapped software, but it does work for deployment and
 installation to your local servers.

 <p>

 One major build project I was involved in had an Ant install build file
 for the bluestone application server, which would shutdown all four
 instances of the app server on a single machine, copy the new version of
@@ -678,7 +634,6 @@ on your IDE toolbar to build, unit test, deploy and then functional test
 your webapp. 

 <p>

 One extra trick I added later was a junit test case to run through the
 install check list. With tests to verify access permissions on network
 drives, approximate clock synchronisation between servers, DNS
@@ -688,7 +643,6 @@ during install time and report problems. [The same tests could also be
 invoked from a JMX MBean, but that's another story]. 

 <p>

 So, Ant is not a substitute for a real installer tool, except in the
 special case of servers you control, but in that context it does let
 you integrate remote installation with your build. 
@@ -703,7 +657,7 @@ Tips and Tricks</h2>
    get
 </b><dd>

 The <a href="manual/CoreTasks/get.html">&lt;get&gt;</a> task can fetch any URL, so be used
 The <a href="manual/CoreTasks/get.html">get</a> task can fetch any URL, so be used
 to trigger remote server side code during the build process, from remote
 server restarts to sending SMS/pager messages to the developer
 cellphones.
@@ -712,8 +666,7 @@ cellphones.
 i18n
 </b><dd>


 Internationalisation is always trouble. Ant helps here with the <A href=
 Internationalisation is always trouble. Ant helps here with the <a href=
 "manual/OptionalTasks/native2ascii.html">native2ascii</a> task which can escape out all non
 ascii characters into unicode. You can use this to write java files
 which include strings (and indeed comments) in your own non-ASCII
@@ -725,7 +678,7 @@ Use Property Files
 </b><dd>

 Use external property files to keep per-user settings out the build
 files -especially passwords. Property files can also be used to
 files - especially passwords. Property files can also be used to
 dynamically set a number of properties based on the value of a single
 property, simply by dynamically generating the property filename from the
 source property. They can also be used as a source of constants across
@@ -735,12 +688,12 @@ multiple build files.
 Faster compiles with Jikes
 </b><dd>

 The <a href="http://www.jikes.org/">jikes compiler</a> is usually much
 The <a href="http://jikes.sourceforge.net/">jikes compiler</a> is usually much
 faster than javac, does dependency checking and has better error
 messages (usually). Get it. Then set
 build.compiler to "jikes" for it to be used in your build files.
 <tt>build.compiler</tt> to "jikes" for it to be used in your build files.
 Doing this explicitly in your build files is a bit dubious as it requires the
 whole team (and sub projects) to be using jikes too -something you can only
 whole team (and sub projects) to be using jikes too - something you can only
 control in small, closed source projects. But if you set 
 <tt>ANT_OPTS&nbsp;=&nbsp;-Dbuild.compiler=jikes</tt>
 in your environment, then all your builds on your system will use 
@@ -748,7 +701,7 @@ Jikes automatically, while others can choose their own compiler, or let
 ant choose whichever is appropriate for the current version of Java.   

 <dt><b>
 #include targets to simplify multi build.xml projects
 #include targets to simplify multi <tt>build.xml</tt> projects
 </b><dd>

 You can import XML files into a build file using the XML parser itself.
@@ -760,7 +713,6 @@ equivalent to the #include mechanism of the 'legacy' languages C and
 C++.

 <p>

 There are two inclusion mechanisms, an ugly one for all parsers and a
 clean one. The ugly method is the only one that was available on Ant1.5 and
 earlier:-
@@ -788,32 +740,29 @@ takes place after the main build file is parsed, during execution, whereas
 XML entity expansion is handled during the parsing process.

 <p>

 The <tt>&lt;import&gt;</tt> task does powerful things, such as let you override targets,
 and use ant properties to name the location of the file to import. Consult the
 <a href="manual/CoreTasks/import.html">documentation</a> for the specifics of
 these features.  

 <p>

 Before you go overboard with using XML inclusion, note that the
 <tt>&lt;ant&gt;</tt> task lets you call any target in any other build
 file -with all your property settings propagating down to that target.
 <tt>ant</tt> task lets you call any target in any other build
 file - with all your property settings propagating down to that target.
 So you can actually have a suite of utility targets
 -"deploy-to-stack-a", "email-to-team", "cleanup-installation" which can
 - "<tt>deploy-to-stack-a</tt>", "<tt>email-to-team</tt>", "<tt>cleanup-installation</tt>" which can
 be called from any of your main build files, perhaps with subtly changed
 parameters. Indeed, after a couple of projects you may be able to create
 a re-usable core build file which contains the core targets of a basic
 Java development project -compile, debug, deploy- which project specific
 Java development project - compile, debug, deploy - which project specific
 build files call with their own settings. If you can achieve this then
 you are definitely making your way up the software maturity ladder. With
 a bit of work you may progress from being a SEI CMM Level 0 organisation
 "Individual Heroics are not enough" to SEI CMM Level 1, "Projects only
 succeed due to individual heroics"
 &quot;Individual Heroics are not enough&quot; to SEI CMM Level 1, &quot;Projects only
 succeed due to individual heroics&quot;

 <p>

 NB, <tt>&lt;ant&gt;</tt> copies all your properties unless the
 NB, <tt>ant</tt> copies all your properties unless the
 <i>inheritall</i> attribute is set to false. Before that attribute
 existed you had to carefully name all property definitions in all build
 files to prevent unintentional overwriting of the invoked property by
@@ -826,52 +775,48 @@ Implement complex Ant builds through XSL
 </b><dd>

 XSLT can be used to dynamically generate build.xml files from a source
 xml file, with the <a href="manual/CoreTasks/style.html">&lt;xslt&gt;</a> task controlling
 xml file, with the <a href="manual/CoreTasks/style.html">xslt</a> task controlling
 the transform. This is the current recommended strategy for creating
 complex build files dynamically. However, its use is still apparently
 quite rare -which means you will be on the bleeding edge of technology.
 quite rare - which means you will be on the bleeding edge of technology.


 <dt><b>
 Change the invocation scripts
 </b><dd>

 By writing your own invocation script -using the DOS, Unix or Perl
 script as a starting point- you can modify Ant's settings and behavior for an
 By writing your own invocation script - using the DOS, Unix or Perl
 script as a starting point - you can modify Ant's settings and behavior for an
 individual project. For example, you can use an alternate variable to
 ANT_HOME as the base, extend the classpath differently, or dynamically
 create a new command line property 'project.interfaces' from all .jar
 <tt>ANT_HOME</tt> as the base, extend the classpath differently, or dynamically
 create a new command line property &quot;<tt>project.interfaces</tt>&quot; from all <tt>.jar</tt>
 files in an interfaces directory.

 <p>

 Having a custom invocation script which runs off a CVS controlled
 library tree under PROJECT_HOME also lets you control Ant versions
 across the team -developers can have other copies of Ant if they want,
 library tree under <tt>PROJECT_HOME</tt> also lets you control Ant versions
 across the team - developers can have other copies of Ant if they want,
 but the CVS tree always contains the jar set used to build your project.

 <p>

 You can also write wrapper scripts which invoke the existing Ant
 scripts. This is an easy way to extend them. The wrapper scripts can add
 extra definitions and name explicit targets, redefine ANT_HOME and
 generally make development easier. Note that "ant" in Windows is really
 "ant.bat", so should be invoked from another batch file with a "CALL
 ant" statement -otherwise it never returns to your wrapper.
 extra definitions and name explicit targets, redefine <tt>ANT_HOME</tt> and
 generally make development easier. Note that &quot;ant&quot; in Windows is really
 &quot;ant.bat&quot;, so should be invoked from another batch file with a "CALL
 ant" statement - otherwise it never returns to your wrapper.


 <dt><b>
 Write all code so that it can be called from Ant
 </b><dd>

 This seems a bit strange and idealistic, but what it means is that you should
 write all your java code as if it may be called as a library at some point in
 future. So do not place calls to <tt>System.exit()</tt> deep in the code -if you
 future. So do not place calls to <tt>System.exit()</tt> deep in the code - if you
 want to exit a few functions in, raise an exception instead and have
 <tt>main()</tt> deal with it.

 <p>

 Moving one step further, consider proving an Ant Task interface to the
 code as a secondary, primary or even sole interface to the
 functionality. Ant actually makes a great bootloader for Java apps as it
@@ -880,8 +825,6 @@ preamble and postamble work. Some projects, such as
 <a href="http://xdoclet.sf.net">XDoclet</a> only run under Ant, because
 that is the right place to be.



 <!-- <dt><b>
 Use Antidote as the invocation tool
 </b><dd>
@@ -892,7 +835,7 @@ the XML parsing delays.
 <dt><b>
 Use the replace task to programmatic modify text files in your project.  
 </b><dd>
 Imagine your project has some source files -BAT files, ASPX pages (!), anything
 Imagine your project has some source files - BAT files, ASPX pages(!), anything
 which needs to be statically customised at compile time for particular
 installations, such driven from some properties of the project such as JVM options, or the URL
 to direct errors too. The replace task can be used to modify files, substituting text and creating
@@ -900,8 +843,6 @@ versions customised for that build or destination. Of course, per-destination cu
 should be delayed until installation, but if you are using Ant for the remote installation
 that suddenly becomes feasible.     



 <dt><b>
 Use the mailing lists
 </b><dd>
@@ -909,15 +850,14 @@ There are two
 <a href="http://ant.apache.org/mail.html">mailing lists</a> 
 related to Ant, user and developer. Ant user is where <i>all</i>
 questions related to using Ant should go. Installation, syntax, code
 samples, etc -post your questions there or search the archives for 
 samples, etc - post your questions there or search the archives for 
 whether the query has been posted and answered before. Ant-developer
 is where Ant development takes place -so it is <i>not</i> the place to
 post things like "I get a compilation error when I build my project" or
 "how do I make a zip file". If you are actually extending Ant, on the other
 is where Ant development takes place - so it is <i>not</i> the place to
 post things like &quot;I get a compilation error when I build my project&quot; or
 &quot;how do I make a zip file&quot;. If you are actually extending Ant, on the other
 hand, it is the ideal place to ask questions about how to add new tasks, make
 changes to existing ones -and to post the results of your work, if you want them
 changes to existing ones - and to post the results of your work, if you want them
 incorporated into the Ant source tree.  
   
 </dl>

 <a name="puttingtogether">
@@ -940,8 +880,8 @@ should contain a number of top level targets
 <li>all - clean, fetch, build, test, docs, deploy
 <li>main - the default build process (usually build or build & test)
 </ul>
 Sub projects 'web', 'bean-1', 'bean-2' can be given their own build
 files -web.xml, bean-1.xml, bean-2.xml- with the same entry points.
 Sub projects &quot;web&quot;, &quot;bean-1&quot;, &quot;bean-2&quot; can be given their own build
 files - <tt>web.xml</tt>, <tt>bean-1.xml</tt>, <tt>bean-2.xml</tt> - with the same entry points.
 Extra toplevel tasks related to databases, web site images and the like
 should be considered if they are part of the process.

@@ -972,8 +912,8 @@ being set :-
  &lt;/target&gt;
 </pre>

 You then have dependent targets, such as "compile", depend on this
 conditional target; there the 'default' properties are set, and then the
 You then have dependent targets, such as &quot;compile&quot;, depend on this
 conditional target; there the &quot;default&quot; properties are set, and then the
 property is actually used. Because Ant properties are <i>immutable</i>,
 if the release target was executed its settings will override the
 default values:
@@ -995,29 +935,25 @@ As a result, we now have a build where the release mode only includes
 the filename and line debug information (useful for bug reports), while
 the development system included variables too. 
 <p>

 It is useful to define a project name property which can be echoed in
 the init task. This lets you work out which Ant file is breaking in a
 multi file build.

 <p>

 What goes in to the internal Ant tasks depends on your own projects. One
 very important tactic is 'keep path redefinition down through
 references' - you can reuse paths by giving them an ID and then
 referring to them via the 'refid' attribute you should only need to
 very important tactic is &quot;keep path redefinition down through
 references&quot; - you can reuse paths by giving them an ID and then
 referring to them via the &quot;refid&quot; attribute you should only need to
 define a shared classpath once in the file; filesets can be reused
 similarly.

 <p>

 Once you have set up the directory structures, and defined the Ant tasks
 it is time to start coding. An early priority must be to set up the
 automated test process, as that not only helps ensures that the code
 works, it verifies that the build process is working.

 <p>

 And that's it. The build file shouldn't need changing as new source
 files get added, only when you want to change the deliverables or part
 of the build process. At some point you may want to massively
@@ -1043,7 +979,6 @@ going wrong (a listener class can do that), or support complex
 conditional statements.

 <p>

 If your build needs to handle exceptions then look at the sound listener
 as a simple example of how to write your own listener class. Complex
 conditional statements can be handled by having something else do the
@@ -1054,7 +989,7 @@ this.

 Some of the features of make, specifically inference rules and
 dependency checking are not included in Ant. That's because they are
 'different' ways of doing a build. Make requires you to state
 &quot;different&quot; ways of doing a build. Make requires you to state
 dependencies and the build steps, Ant wants you to state tasks and the
 order between them, the tasks themselves can do dependency checking or
 not. A full java build using Jikes is so fast that dependency checking
@@ -1080,13 +1015,13 @@ people each working on their own bit of the solution. That's even before
 the deadlines loom close, the integration problems become insurmountable,
 weekends become indistinguishable from weekdays in terms of workload and 
 half the team stops talking to the other half. Ant may simplify the
 build and test process, and can eliminate the full time 'makefile engineer'
 role, but that doesn't mean that someone can stop 'owning the build'. 
 Being in charge of the build has to mean more than they type 'ant all' on
 build and test process, and can eliminate the full time &quot;makefile engineer&quot;
 role, but that doesn't mean that someone can stop &quot;owning the build&quot;. 
 Being in charge of the build has to mean more than they type &quot;<tt>ant all</tt>&quot; on
 their system, it means they need to set the standards of what build tools to
 use, what the common targets, what property names and files should be
 and generally oversee the sub projects build processes. On a small project,
 you don't need to do that -but remember: small projects become big projects
 you don't need to do that - but remember: small projects become big projects
 when you aren't looking. If you start off with a little bit of process, then
 you can scale it if needed. If you start with none, by the time you need 
 it will be too late.   
@@ -1104,17 +1039,16 @@ let you have auto-incrementing build counters, and automated file
 update processes. 

 <p>

 You also need some kind of change control process, to resist
 uncontrolled feature creep. Bugzilla is a simple and low cost tool for
 this, using Ant and a continuous test process enables a rapid evolution of code
 to adapt to those changes which are inevitable.  

 <h2>Endpiece</h2>
 <h2>End piece</h2>

 Software development is meant to be fun. Being in the maelstrom of a
 tight project with the stress of integration and trying to code
 everything up for an insane deadline can be fun -it is certainly
 everything up for an insane deadline can be fun - it is certainly
 exhilarating. Adding a bit of automation to the process may make things
 less chaotic, and bit less entertaining, but it is a start to putting
 you in control of your development process. You can still have fun, you
@@ -1136,7 +1070,7 @@ running a continuous integration/testing process.
    Covers JUnit as well as tactics for making some headway with the mess of
    code you will soon have.

 <li><a href="http://manning.com/antbook/"><i>Java Development with
 <li><a href="http://manning.com/hatcher"><i>Java Development with
 Ant</i></a>;
    Erik Hatcher and Steve Loughran. 

@@ -1157,7 +1091,7 @@ Steve Loughran is a research scientist at a corporate R&amp;D lab,
 currently on a sabbatical building production web services against
 implausible deadlines for the fun of it. He is also a committer on
 Apache Ant and Apache Axis, and co-author of 
 <a href="http://manning.com/antbook/"><i>Java Development with Ant</i></a>. 
 <a href="http://manning.com/hatcher"><i>Java Development with Ant</i></a>. 
 He thinks that if you liked this document you'll love that book because
 it doesn't just explain Ant, it goes into processes, deployment and best practices
 and other corners of stuff that really make Ant useful. (It would 
@@ -1165,10 +1099,10 @@ have been easier to just rehash the manual, but that wouldn't have been
 so useful or as much fun).  

 <p>

 For questions related to this document, use the Ant mailing list.

 <hr>
 <p align="center">Copyright &copy; 2000-2004 The Apache Software Foundation. All rights
 <p align="center">Copyright &copy; 2000-2005 The Apache Software Foundation. All rights
 Reserved.</p>
 </body>
 </html>