+Firstly, here are some assumptions about the projects which this +document covers +
+ +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 -"you can +use whatever you want in development, but ant for the deployment +builds" + +
+ +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 +ant +task. For example. the clean target could be handed down to the intf and +impl subdirectories from a parent directory + +
<target name="clean" depends="clean-intf, clean-impl"> +</target> + +<target name="clean-intf" > + <ant dir="intf" target="clean" /> +</target> + +<target name="clean-impl"> + <ant dir="impl" target="clean" /> +</target>+ +
+ +Ant lets you call JUnit 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 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. + +
+ +Once code fetches from the code control system are added as another ant +target, the integration test code can be a pure ant task run on any box +dedicated to the task. This is ideal for verifying that the build and +unit tests work on different targets from the usual development +machines. For example, a Win95/Java1.1 combination could be used even +though no developer would willingly use that configuration given the +choice. + +
+
+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 java
+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.
+
+
+
+
+Cross Platform Ant
+
+
+
+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
+single workstation.
+
+
+ +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. + +
+ +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 +could be handled inside some external code which ant calls. This can be +some compiled down java in a new task, or an external script file. + +
+ +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 +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 +definition. + + +
+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 +directories to see a disastrous example of this). + +
+ +Ant's policy on case sensitivity is whatever the underlying file system +implements *VERIFY*, 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 +not have a class 'ExampleThree' implemented in "examplethree.java". + +
+ +Some tasks only work on one platform - +Chmod being a classic example. These tasks usually result in just a +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 +do that - Get, Touch and +Unjar/Unwar/Unzip for example, degrade their functionality on +Java1.1, usually resorting to the current timestamp instead. + + +
+
+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 Win32 platforms from
+ActiveState. A Perl file with .pl extension, with 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.
+
+
+Team Development Processes
+
+
+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
+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.
+
+
+
+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
+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.
+
+
+
+Deploying with Ant
+
+
+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.
+
+ +Ant can Jar, +Tar or Zip files for deployment, while +the War task extends the jar task for +better servlet deployment. Jlink 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. Cab can be used on Win32 boxes to build a cab file +which is useful if you have to target IE deployment. + +
+ +The ftp 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 FixCRLF 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. If DAV is your +required upload mechanism, why not take up the challenge? + +
+ +EJB deployment is aided by the ejb tasks. At the +time of writing, only WebLogic was supported with these tasks -if your +EJB server is not supported, extending the ejb tasks would benefit your +project and the rest of the ant community. + +
+
+Finally, there are of course the fallbacks of just copying files to a
+destination using Copy and Copydir , or just sending them to a person or
+process using Mail.
+
+
+ Directory Structures
+
+
+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.
+
+
| bin + | +common binaries, scripts -put this on the path. + | +
| build + | +This is the tree for building; ant creates it and can empty it + in the 'clean' project. + | +
| dist + | +Distribution outputs go in here; the directory is created in ant + and clean empties it out + | +
| doc + | +Hand crafted documentation + | +
| lib + | +Imported Java libraries go in to this directory + | +
| src + | +source goes in under this tree + | +
+ +To still have a single build across the sub projects, use parent +build.xml files which call down into the sub projects. + +
+ +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 +processes and just increase your workload and integration grief all round. + +
+
+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
+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.
+
+
+
+ Ant Update Policies
+
+
+
+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
+after whatever high stress milestone has pushed all unimportant tasks
+(like sleep and seeing daylight) on the back burner". 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.
+
+
+ +Often an update will require changes to the build.xml 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 +files in the CVS tree helps ensure that old versions of your software +can be still be built. + +
+ +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 regulary, 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. + +
+ +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 the best platform for writing your extensions, as you +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, +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 +and discovering that instead of adulation all you get are helpful +pointers to the existing implementation. + +
+
+You should also get on the ant-dev mailing list
+, 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
+don't make everyone on the team subscribe; it can be too much of a
+distraction.
+
+
+
+
+Tips and Tricks
+
+
+ +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, +but the CVS tree always contains the jar set used to build your project. + +
+ +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. + + +
+Debug/release switching can be handled with separate initialisation +targets called before the compile tasks which define the appropriate +properties. + +
+Internal targets should be used to structure the process +
+ +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. + +
+ +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 +define a shared classpath once in the file; filesets can be reused +similarly. + +
+ +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. + +
+ +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 +restructure the entire build process, restructuring projects and the +like, but even then the build file you have should act as a foundation +for a split build file process -just pull out the common properties into +a properties file all build files read in, keep the target names unified +and keep going with the project. Restructuring the source code control +system is often much harder work. + +
+ +
+ +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 +tests and then build the appropriate ant task. XSLT can be used for +this. + +
Copyright © 2000 Apache Software Foundation. All rights +Reserved.
+ +