| 1 | <head>
|
|---|
| 2 | <title>
|
|---|
| 3 | Ant in Anger
|
|---|
| 4 | </title>
|
|---|
| 5 | <link rel="stylesheet" type="text/css" href="manual/stylesheets/antmanual.css">
|
|---|
| 6 | </head>
|
|---|
| 7 |
|
|---|
| 8 | <body bgcolor="#FFFFFF" text="#000000">
|
|---|
| 9 | <h1 align="center">Ant in Anger:
|
|---|
| 10 | </h1>
|
|---|
| 11 | <h2 align="center">
|
|---|
| 12 | Using Apache Ant in a Production Development System
|
|---|
| 13 | </h2>
|
|---|
| 14 |
|
|---|
| 15 | <h4 align="center">
|
|---|
| 16 | Steve Loughran<br>
|
|---|
| 17 | Last updated 2002-11-09
|
|---|
| 18 | </h4>
|
|---|
| 19 |
|
|---|
| 20 | <a name="introduction">
|
|---|
| 21 |
|
|---|
| 22 | <h2>Introduction</h2>
|
|---|
| 23 | </a>
|
|---|
| 24 |
|
|---|
| 25 | <a href="http://ant.apache.org/">Apache Ant</a>
|
|---|
| 26 | can be an invaluable tool in a team development process -or it can
|
|---|
| 27 | be yet another source of problems in that ongoing crises we call
|
|---|
| 28 | development . This
|
|---|
| 29 | document contains some strategies and tactics for making the most of
|
|---|
| 30 | Ant. It is moderately frivolous in places, and lacks almost any actual
|
|---|
| 31 | examples of Ant xml. The lack of examples is entirely deliberate -it
|
|---|
| 32 | keeps document maintenance costs down. Most of the concepts covered
|
|---|
| 33 | don't need the detail about XML representations, as it is processes we
|
|---|
| 34 | are concerned about, not syntax. Finally, please be aware that the
|
|---|
| 35 | comments here are only suggestions which need to be customised to meet
|
|---|
| 36 | your own needs, not strict rules about what should and should not be
|
|---|
| 37 | done.
|
|---|
| 38 |
|
|---|
| 39 | <p>
|
|---|
| 40 | Firstly, here are some assumptions about the projects which this
|
|---|
| 41 | document covers:
|
|---|
| 42 | <ul>
|
|---|
| 43 | <li> Pretty much pure Java, maybe with some legacy cruft on the edges.
|
|---|
| 44 |
|
|---|
| 45 | <li> Team efforts, usually with the petulant prima-donnas all us Java
|
|---|
| 46 | programmers become once we realise how much in demand we are.
|
|---|
| 47 |
|
|---|
| 48 | <li> A fairly distributed development team -spread across locations and
|
|---|
| 49 | maybe time zones.
|
|---|
| 50 |
|
|---|
| 51 | <li> Separate sub projects -from separate beans in a big
|
|---|
| 52 | enterprise application to separate enterprise applications which need to
|
|---|
| 53 | be vaguely aware of each other.
|
|---|
| 54 |
|
|---|
| 55 | <li> Significant mismatch between expectations and time available to
|
|---|
| 56 | deliver. 'Last Week' is the ideal delivery date handed down from above,
|
|---|
| 57 | late next century the date coming up from below.
|
|---|
| 58 |
|
|---|
| 59 | <li> Everyone is struggling to keep up with platform and tool evolution.
|
|---|
| 60 |
|
|---|
| 61 | <li> Extensive use of external libraries, both open and closed source.
|
|---|
| 62 |
|
|---|
| 63 | </ul>
|
|---|
| 64 |
|
|---|
| 65 | What that all means is that there is no time to spend getting things
|
|---|
| 66 | right, you don't have that tight control on how the rest of the team
|
|---|
| 67 | works and the development process is often more one of chaos minimisation
|
|---|
| 68 | than anything else. The role of Ant in such projects is to ensure that
|
|---|
| 69 | the build, test and deploy processes run smoothly, leaving you with all
|
|---|
| 70 | the other problems.
|
|---|
| 71 |
|
|---|
| 72 | <a name="core">
|
|---|
| 73 | <h2>Core Practices</h2>
|
|---|
| 74 | </a>
|
|---|
| 75 | <h3>
|
|---|
| 76 | Clarify what you want Ant to do</h3>
|
|---|
| 77 |
|
|---|
| 78 |
|
|---|
| 79 | Ant is not a silver bullet. It is just another rusty bullet in the armory of
|
|---|
| 80 | development tools available at your disposal. Its primary purpose is to
|
|---|
| 81 | accelerate the construction and deployment of Java projects. You could certainly
|
|---|
| 82 | extend Ant to do anything Java makes possible: it is easy to imagine writing an
|
|---|
| 83 | image processing task to help in web site deployment by shrinking and
|
|---|
| 84 | recompressing jpeg files, for example. But that would be pushing the boundary of
|
|---|
| 85 | what Ant is really intended to do -so should be considered with care.
|
|---|
| 86 |
|
|---|
| 87 | <P>
|
|---|
| 88 |
|
|---|
| 89 | Ant is also a great adjunct to an IDE; a way of doing all the housekeeping of
|
|---|
| 90 | deployment and for clean, automated builds. But a good modern IDE is a
|
|---|
| 91 | productivity tool in its own right -one you should consider keeping using. Ant
|
|---|
| 92 | just lets you give the teams somewhat more freedom in IDE choice -"you can
|
|---|
| 93 | use whatever you want in development, but Ant for the deployment
|
|---|
| 94 | builds" Now that many modern open source and commercial IDEs
|
|---|
| 95 | include Ant support (including jEdit, Forte, Eclipse and IDEA),
|
|---|
| 96 | developers can use a great IDE, with Ant providing a rigorous and portable
|
|---|
| 97 | build process integrated into the tool.
|
|---|
| 98 |
|
|---|
| 99 | <h3>
|
|---|
| 100 | Define standard targets
|
|---|
| 101 | </h3>
|
|---|
| 102 |
|
|---|
| 103 |
|
|---|
| 104 | When you have multiple sub projects, define a standard set of targets.
|
|---|
| 105 | Projects with a split between interface and implementation jar files
|
|---|
| 106 | could consider <b>impl</b> and <b>intf</b> targets -with separate
|
|---|
| 107 | <b>debug-impl</b>and <b>debug-intf</b> targets for the debug version.
|
|---|
| 108 | And of course, the ubiquitous <b>clean</b> target.
|
|---|
| 109 |
|
|---|
| 110 | <P>
|
|---|
| 111 |
|
|---|
| 112 | With standard target names, it is easy to build encompassing Ant build
|
|---|
| 113 | files which just hand off the work to the classes below using the
|
|---|
| 114 | <a href="manual/CoreTasks/ant.html"><ant></a>
|
|---|
| 115 | task. For example. the clean target could be handed down to the <tt>intf</tt> and
|
|---|
| 116 | <tt>impl</tt> subdirectories from a parent directory
|
|---|
| 117 |
|
|---|
| 118 | <pre><target name="clean" depends="clean-intf, clean-impl">
|
|---|
| 119 | </target>
|
|---|
| 120 |
|
|---|
| 121 | <target name="clean-intf" >
|
|---|
| 122 | <ant dir="intf" target="clean" />
|
|---|
| 123 | </target>
|
|---|
| 124 |
|
|---|
| 125 | <target name="clean-impl">
|
|---|
| 126 | <ant dir="impl" target="clean" />
|
|---|
| 127 | </target> </pre>
|
|---|
| 128 |
|
|---|
| 129 | If you give targets a <tt>description</tt> tag, then calling <tt>ant
|
|---|
| 130 | -projecthelp</tt> will list all tasks with their description as 'main targets', and
|
|---|
| 131 | all tasks without a description as subtargets. Describing all your
|
|---|
| 132 | entry points is therefore very useful, even before a project becomes big and complicated.
|
|---|
| 133 |
|
|---|
| 134 | <h3>
|
|---|
| 135 | Extend Ant through new tasks
|
|---|
| 136 | </h3>
|
|---|
| 137 |
|
|---|
| 138 | If Ant does not do what you want, you can use the
|
|---|
| 139 | <a href="manual/CoreTasks/exec.html">exec</a> and
|
|---|
| 140 | <a href="manual/CoreTasks/java.html">java</a> tasks or
|
|---|
| 141 | <a href="manual/OptionalTasks/script.html">inline scripting</a> to extend it. In a
|
|---|
| 142 | project with many build.xml files, you soon find that having a single
|
|---|
| 143 | central place for implementing the functionality keeps maintenance
|
|---|
| 144 | overhead down. Implementing task extensions through Java code seems
|
|---|
| 145 | extra effort at first, but gives extra benefits:-
|
|---|
| 146 |
|
|---|
| 147 | <ul>
|
|---|
| 148 |
|
|---|
| 149 | <li>Cross platform support can be added later without changing any
|
|---|
| 150 | build.xml files</li>
|
|---|
| 151 |
|
|---|
| 152 | <li>The code can be submitted to the Ant project itself, for other
|
|---|
| 153 | people to use and maintain</li>
|
|---|
| 154 |
|
|---|
| 155 | <li>It keeps the build files simpler</li>
|
|---|
| 156 |
|
|---|
| 157 | </ul>
|
|---|
| 158 |
|
|---|
| 159 | In a way, it is it this decoupling of functionality, "the tasks", from
|
|---|
| 160 | the declaration of use, "the build file", that has helped Ant succeed.
|
|---|
| 161 | If you have to get something complex done in Make or an IDE, you have a
|
|---|
| 162 | hairy makefile that everyone is scared of, or an IDE configuration that
|
|---|
| 163 | is invariably very brittle. But an Ant task is reusable and shareable
|
|---|
| 164 | among all Ant users. Many of the core and optional tasks in Ant today,
|
|---|
| 165 | tasks you do or will come to depend on, were written by people trying to
|
|---|
| 166 | solve their own pressing problems.
|
|---|
| 167 |
|
|---|
| 168 | <h3>
|
|---|
| 169 | Embrace Automated Testing
|
|---|
| 170 | </h3>
|
|---|
| 171 |
|
|---|
| 172 | <b>(alternatively "recriminate early, recriminate often")</b>
|
|---|
| 173 | <p>
|
|---|
| 174 |
|
|---|
| 175 | Ant lets you call <a href="manual/OptionalTasks/junit.html">JUnit</a>
|
|---|
| 176 | tasks, which unit test the code your team has written. Automated testing
|
|---|
| 177 | may seem like extra work at first, but JUnit makes writing unit tests so
|
|---|
| 178 | easy that you have almost no reason not to. Invest the time in learning
|
|---|
| 179 | how to use JUnit, write the test cases, and integrate them in a 'test'
|
|---|
| 180 | target from Ant so that your daily or hourly team build can have the
|
|---|
| 181 | tests applied automatically. One of the free to download chapters of
|
|---|
| 182 | <a href="http://manning.com/antbook/">Java Development with Ant</a>
|
|---|
| 183 | shows you how to use JUnit from inside Ant.
|
|---|
| 184 |
|
|---|
| 185 | <p>
|
|---|
| 186 |
|
|---|
| 187 |
|
|---|
| 188 | Once you add a way to fetch code from the SCM system, either as an Ant
|
|---|
| 189 | task, in some shell script or batch file or via some continuous
|
|---|
| 190 | integration tool. the integration test code can be a pure Ant task run
|
|---|
| 191 | on any box dedicated to the task. This is ideal for verifying that the
|
|---|
| 192 | build and unit tests work on different targets from the usual
|
|---|
| 193 | development machines. For example, a Win95/Java1.1 combination could be
|
|---|
| 194 | used even though no developer would willingly use that configuration
|
|---|
| 195 | given the choice.
|
|---|
| 196 |
|
|---|
| 197 | <p>
|
|---|
| 198 |
|
|---|
| 199 | System tests are harder to automate than unit tests, but if you can
|
|---|
| 200 | write java code to stress large portions of the system -even if the code
|
|---|
| 201 | can not run as JUnit tasks- then the <a href= "manual/CoreTasks/java.html">java</a>
|
|---|
| 202 | task can be used to invoke them. It is best to specify that you want a
|
|---|
| 203 | new JVM for these tests, so that a significant crash does not break the
|
|---|
| 204 | full build. The Junit extensions such as
|
|---|
| 205 | <a href="http://httpunit.sourceforge.net/">HttpUnit</a> for web pages, and
|
|---|
| 206 | <a href="http://jakarta.apache.org/cactus/">Cactus</a> for J2EE and servlet
|
|---|
| 207 | testing help to expand the testing framework. To test properly you will still
|
|---|
| 208 | need to invest a lot of effort in getting these to work with your project, and
|
|---|
| 209 | deriving great unit, system and regression tests -but your customers will love
|
|---|
| 210 | you for shipping software that works.
|
|---|
| 211 |
|
|---|
| 212 |
|
|---|
| 213 | <h3>Learn to Use and love the add-ons to Ant</h3>
|
|---|
| 214 | The Ant distribution is not the limit of the Ant universe, it is only
|
|---|
| 215 | the beginning. Look at the
|
|---|
| 216 | <A href="http://ant.apache.org/external.html">
|
|---|
| 217 | External Tools and Tasks page
|
|---|
| 218 | </A> for an up to date list. Here are some of them that .
|
|---|
| 219 |
|
|---|
| 220 | <ul>
|
|---|
| 221 | <li>
|
|---|
| 222 | <a hef="http://checkstyle.sourceforge.net/">Checkstyle</a><br>
|
|---|
| 223 | This tool audits your code and generates HTML reports of wherever any
|
|---|
| 224 | style rule gets broken. Nobody can hide from the code police now! tip:
|
|---|
| 225 | start using this early, so the corrections are less.
|
|---|
| 226 | <li>
|
|---|
| 227 | <A href="http://ant-contrib.sf.net/">Ant-contrib</A><br>
|
|---|
| 228 | This sourceforge project contains helper tasks that are kept separate
|
|---|
| 229 | from core Ant for ideological purity; the foreach and trycatch tasks in
|
|---|
| 230 | particular. These give you iteration and extra error handling. Also on
|
|---|
| 231 | the site is the <cc> task suite, that compile and link native code
|
|---|
| 232 | on a variety of platforms.
|
|---|
| 233 |
|
|---|
| 234 | <li>
|
|---|
| 235 | <a href="http://xdoclet.sourceforge.net/">XDoclet</a>
|
|---|
| 236 |
|
|---|
| 237 | XDoclet adds attributed oriented programming to Java. By adding javadoc
|
|---|
| 238 | tags to your code you can have XDoclet automatically generate web.xml
|
|---|
| 239 | descriptors, taglib descriptors, EJB interfaces, JMX interface classes,
|
|---|
| 240 | Castor XML/SQL bindings, and many more. The key here is that all those
|
|---|
| 241 | fiddly little XML files you need to create, and those interfaces EJB and
|
|---|
| 242 | JMX requires to to implement, all can be autogenerated from your Java
|
|---|
| 243 | code with a few helper attributes. This reduces
|
|---|
| 244 | errors and means you can change your code and have the rest of the app
|
|---|
| 245 | take its cue from the source. Never do EJB, JMX or webapps without it!
|
|---|
| 246 |
|
|---|
| 247 | </ul>
|
|---|
| 248 |
|
|---|
| 249 |
|
|---|
| 250 | <a name="crossplatform">
|
|---|
| 251 | <h2>
|
|---|
| 252 | Cross Platform Ant
|
|---|
| 253 | </h2>
|
|---|
| 254 | </a>
|
|---|
| 255 |
|
|---|
| 256 | Ant is the best foundation for cross platform Java development and
|
|---|
| 257 | testing to date. But if you are not paying attention, it is possible to
|
|---|
| 258 | produce build files which only work on one platform -or indeed, one
|
|---|
| 259 | single workstation.
|
|---|
| 260 |
|
|---|
| 261 | <p>
|
|---|
| 262 |
|
|---|
| 263 | The common barriers to cross-platform Ant are the use of command line
|
|---|
| 264 | tools (exec tasks) which are not portable, path issues, and hard coding
|
|---|
| 265 | in the location of things.
|
|---|
| 266 |
|
|---|
| 267 | <h3>Command Line apps: <a href="manual/CoreTasks/exec.html">Exec</a>/
|
|---|
| 268 | <a href= "manual/CoreTasks/apply.html">Apply</a></h3>
|
|---|
| 269 |
|
|---|
| 270 | The trouble with external invocation is that not all functions are found
|
|---|
| 271 | cross platform, and those that are often have different names -DOS
|
|---|
| 272 | descendants often expect .exe or .bat at the end of files. That can be
|
|---|
| 273 | bad if you explicitly include the extension in the naming of the command
|
|---|
| 274 | (don't!), good when it lets you keep the unix and DOS versions of an
|
|---|
| 275 | executable in the same bin directory of the project without name
|
|---|
| 276 | clashes arising.
|
|---|
| 277 |
|
|---|
| 278 | <p>
|
|---|
| 279 |
|
|---|
| 280 | Both the command line invocation tasks let you specify which platform
|
|---|
| 281 | you want the code to run on, so you could write different tasks for each
|
|---|
| 282 | platform you are targeting. Alternatively, the platform differences
|
|---|
| 283 | could be handled inside some external code which Ant calls. This can be
|
|---|
| 284 | some compiled down java in a new task, or an external script file.
|
|---|
| 285 |
|
|---|
| 286 | <h3>Cross platform paths</h3>
|
|---|
| 287 |
|
|---|
| 288 | Unix paths use forward slashes between directories and a colon to
|
|---|
| 289 | split entries. Thus
|
|---|
| 290 | <i>"/bin/java/lib/xerces.jar:/bin/java/lib/ant.jar"</i> is
|
|---|
| 291 | a path in unix. In Windows the path must use semicolon separators,
|
|---|
| 292 | colons being used to specify disk drives, and backslash separators
|
|---|
| 293 | <i>"c:\bin\java\lib\xerces.jar;c:\bin\java\lib\ant.jar"</i>.
|
|---|
| 294 | <p>
|
|---|
| 295 | This difference between platforms (indeed, the whole java classpath
|
|---|
| 296 | paradigm) can cause hours of fun.
|
|---|
| 297 |
|
|---|
| 298 | <p>
|
|---|
| 299 |
|
|---|
| 300 | Ant reduces path problems; but does not eliminate them entirely. You
|
|---|
| 301 | need to put in some effort too. The rules for handling path names are
|
|---|
| 302 | that 'DOS-like pathnames are handled', 'Unix like paths are handled'.
|
|---|
| 303 | Disk drives -'C:'- are handled on DOS-based boxes, but placing them in
|
|---|
| 304 | the build.xml file ruins all chances of portability. Relative file paths
|
|---|
| 305 | are much more portable. Semicolons work as path separators -a fact which
|
|---|
| 306 | is useful if your Ant invocation wrapper includes a list of jars as a
|
|---|
| 307 | defined property in the command line. In the build files you may find it
|
|---|
| 308 | better to build a classpath by listing individual files (using location=
|
|---|
| 309 | attributes), or by including a fileset of *.jar in the classpath
|
|---|
| 310 | definition.
|
|---|
| 311 | <p>
|
|---|
| 312 | There is also the <a
|
|---|
| 313 | href="manual/CoreTasks/pathconvert.html">PathConvert</a> task which
|
|---|
| 314 | can put a fully resolved path into a property. Why do that? Because then
|
|---|
| 315 | you can use that path in other ways -such as pass it as a parameter to
|
|---|
| 316 | some application you are calling, or use the replace task to patch it
|
|---|
| 317 | into a localised shell script or batch file.
|
|---|
| 318 | <p>
|
|---|
| 319 | Note that DOS descended file systems are case insensitive (apart from
|
|---|
| 320 | the obscure aberration of the WinNT posix subsystem run against NTFS),
|
|---|
| 321 | and that Windows pretends that all file extensions with four or more
|
|---|
| 322 | letters are also three letter extensions (try DELETE *.jav in your java
|
|---|
| 323 | directories to see a disastrous example of this).
|
|---|
| 324 |
|
|---|
| 325 | <p>
|
|---|
| 326 |
|
|---|
| 327 | Ant's policy on case sensitivity is whatever the underlying file system
|
|---|
| 328 | implements, and its handling of file extensions is that *.jav does not
|
|---|
| 329 | find any .java files. The Java compiler is of course case sensitive -you can
|
|---|
| 330 | not have a class 'ExampleThree' implemented in "examplethree.java".
|
|---|
| 331 |
|
|---|
| 332 | <p>
|
|---|
| 333 |
|
|---|
| 334 | Some tasks only work on one platform -<a href= "manual/CoreTasks/chmod.html">
|
|---|
| 335 | Chmod</a> being a classic example. These tasks usually result in just a
|
|---|
| 336 | warning message on an unsupported platform -the rest of the target's
|
|---|
| 337 | tasks will still be called. Other tasks degrade their functionality on
|
|---|
| 338 | platforms or Java versions. In particular, any task which adjusts the
|
|---|
| 339 | timestamp of files can not do so properly on Java 1.1. Tasks which can
|
|---|
| 340 | do that - <a href="manual/CoreTasks/get.html">Get</a>, <a
|
|---|
| 341 | href="manual/CoreTasks/touch.html">Touch</a> and <A href="manual/CoreTasks/unzip.html">
|
|---|
| 342 | Unjar/Unwar/Unzip</a> for example, degrade their functionality on
|
|---|
| 343 | Java1.1, usually resorting to the current timestamp instead.
|
|---|
| 344 |
|
|---|
| 345 |
|
|---|
| 346 | <p>
|
|---|
| 347 |
|
|---|
| 348 | Finally, Perl makes a good place to wrap up Java invocations cross
|
|---|
| 349 | platform, rather than batch files. It is included in most Unix
|
|---|
| 350 | distributions, and is a simple download for <a href=
|
|---|
| 351 | "http://www.activestate.com/Products/ActivePerl/"> Win32 platforms from
|
|---|
| 352 | ActiveState</a>. A Perl file with .pl extension, with the usual Unix
|
|---|
| 353 | path to perl on the line 1 comment and marked as executable can be run
|
|---|
| 354 | on Windows, OS/2 and Unix and hence called from Ant without issues. The
|
|---|
| 355 | perl code can be left to resolve its own platform issues. Dont forget to
|
|---|
| 356 | set the line endings of the file to the appropriate platform when you
|
|---|
| 357 | redistribute Perl code; <a
|
|---|
| 358 | href="manual/CoreTasks/fixcrlf.html"><fixCRLF></a>
|
|---|
| 359 | can do that for you.
|
|---|
| 360 |
|
|---|
| 361 | <a name="team">
|
|---|
| 362 | <h2>Team Development Processes</h2>
|
|---|
| 363 | </a>
|
|---|
| 364 |
|
|---|
| 365 | Even if each team member is allowed their choice of IDE/editor, or even
|
|---|
| 366 | OS, you need to set a baseline of functionality on each box. In
|
|---|
| 367 | particular, the JDKs and jars need to be in perfect sync. Ideally pick
|
|---|
| 368 | the latest stable Java/JDK version available on all developer/target
|
|---|
| 369 | systems and stick with it for a while. Consider assigning one person to
|
|---|
| 370 | be the contact point for all tools coming in -particularly open source
|
|---|
| 371 | tools when a new build is available on a nightly basis. Unless needed,
|
|---|
| 372 | these tools should only really be updated monthly, or when a formal
|
|---|
| 373 | release is made.
|
|---|
| 374 |
|
|---|
| 375 | <p>
|
|---|
| 376 |
|
|---|
| 377 | Another good tactic is to use a unified directory tree, and add on extra
|
|---|
| 378 | tools inside that tree. All references can be made relative to the tree.
|
|---|
| 379 | If team members are expected to add a directory in the project to their
|
|---|
| 380 | path, then command line tools can be included there -including those
|
|---|
| 381 | invoked by Ant exec tasks. Put everything under source code control and
|
|---|
| 382 | you have a one stop shop for getting a build/execute environment purely
|
|---|
| 383 | from CVS or your equivalent.
|
|---|
| 384 |
|
|---|
| 385 |
|
|---|
| 386 | <a name="deploying">
|
|---|
| 387 | <h2>Deploying with Ant</h2>
|
|---|
| 388 | </a>
|
|---|
| 389 |
|
|---|
| 390 | One big difference between Ant and older tools such as Make is that the
|
|---|
| 391 | processes for deploying Java to remote sites are reasonably well
|
|---|
| 392 | evolved in Ant. That is because we all have to do it these days, so
|
|---|
| 393 | many people have put in the effort to make the tasks easier.
|
|---|
| 394 | <p>
|
|---|
| 395 |
|
|---|
| 396 | Ant can <a href="manual/CoreTasks/jar.html">Jar</a>, <a href=
|
|---|
| 397 | "manual/CoreTasks/tar.html"> Tar</a> or <a
|
|---|
| 398 | href="manual/CoreTasks/zip.html">Zip</a> files for deployment, while the
|
|---|
| 399 | <a href="manual/CoreTasks/war.html">War</a> task extends the jar task
|
|---|
| 400 | for better servlet deployment.
|
|---|
| 401 | <a href = "manual/OptionalTasks/jlink.html">Jlink</a> is a
|
|---|
| 402 | jar generation file which lets you merge multiple sub jars. This is
|
|---|
| 403 | ideal for a build process in which separate jars are generated by sub
|
|---|
| 404 | projects, yet the final output is a merged jar. <a href=
|
|---|
| 405 | "manual/OptionalTasks/cab.html">Cab</a> can be used on Win32 boxes to
|
|---|
| 406 | build a cab file which is useful if you still have to target IE deployment.
|
|---|
| 407 |
|
|---|
| 408 | <p>
|
|---|
| 409 |
|
|---|
| 410 | The <a href = "index.html#ftp">ftp</a> task lets you move stuff up to a
|
|---|
| 411 | server. Beware of putting the ftp password in the build file -a property
|
|---|
| 412 | file with tight access control is slightly better. The <a href=
|
|---|
| 413 | "manual/CoreTasks/fixcrlf.html">FixCRLF task</a> is often a useful interim step if
|
|---|
| 414 | you need to ensure that files have Unix file extensions before upload. A
|
|---|
| 415 | WebDav task has long been discussed, which would provide a more secure
|
|---|
| 416 | upload to web servers, but it is still in the todo list. Rumour has it
|
|---|
| 417 | that there is such a task in the jakarta-slide libraries. With MacOS X,
|
|---|
| 418 | Linux and Windows XP all supporting WebDAV file systems, you may even be able
|
|---|
| 419 | to use <a href="manual/CoreTasks/copy.html"><copy></a> to deploy
|
|---|
| 420 | though a firewall.
|
|---|
| 421 |
|
|---|
| 422 | <p>
|
|---|
| 423 |
|
|---|
| 424 | EJB deployment is aided by the <a href="manual/OptionalTasks/ejb.html">ejb tasks</a>,
|
|---|
| 425 | while the
|
|---|
| 426 | <a
|
|---|
| 427 | href="manual/OptionalTasks/serverdeploy.html"><serverdeploy></a>
|
|---|
| 428 | suite can deploy to multiple servers. The popularity of Ant has
|
|---|
| 429 | encouraged vendors to produce their own deployment tasks which they
|
|---|
| 430 | redistribute with their servers. For example, the Tomcat4.1 installation
|
|---|
| 431 | includes tasks to deploy, undeploy and reload web applications.
|
|---|
| 432 |
|
|---|
| 433 | <p>
|
|---|
| 434 |
|
|---|
| 435 | Finally, there are of course the fallbacks of just copying files to a
|
|---|
| 436 | destination using <a href="manual/CoreTasks/copy.html">Copy</a> and <a href =
|
|---|
| 437 | "index.html#copydir">Copydir</a> , or just sending them to a person or
|
|---|
| 438 | process using <a href= "manual/CoreTasks/mail.html">Mail</a> or the attachment
|
|---|
| 439 | aware <a href= "manual/OptionalTasks/mimemail.html">MimeMail</a>.
|
|---|
| 440 | In one project our team even used Ant to build CD images through a build followed
|
|---|
| 441 | by a long set of Copy tasks, which worked surprisingly well, certainly
|
|---|
| 442 | easier than when we mailed them to the free email service on
|
|---|
| 443 | myrealbox.com, then pulled them down from the far end's web browser, which we
|
|---|
| 444 | were running over WinNT remote desktop connection, that being tunneled
|
|---|
| 445 | through SSH.
|
|---|
| 446 |
|
|---|
| 447 | <a name="directories">
|
|---|
| 448 | <h2> Directory Structures</h2>
|
|---|
| 449 | </a>
|
|---|
| 450 |
|
|---|
| 451 | How you structure your directory tree is very dependent upon the
|
|---|
| 452 | project. Here are some directory layout patterns which can be used as
|
|---|
| 453 | starting points. All the jakarta projects follow a roughly similar
|
|---|
| 454 | style, which makes it easy to navigate around one form one project to
|
|---|
| 455 | another, and easy to clean up when desired.
|
|---|
| 456 |
|
|---|
| 457 | <h3>Simple Project</h3>
|
|---|
| 458 |
|
|---|
| 459 | The project contains sub directories
|
|---|
| 460 | <table width="100%">
|
|---|
| 461 | <tr>
|
|---|
| 462 | <td><b>bin</b>
|
|---|
| 463 | </td>
|
|---|
| 464 | <td>common binaries, scripts -put this on the path.
|
|---|
| 465 | </td>
|
|---|
| 466 | </tr>
|
|---|
| 467 |
|
|---|
| 468 | <tr>
|
|---|
| 469 | <td><b>build</b>
|
|---|
| 470 | </td>
|
|---|
| 471 | <td>This is the tree for building; Ant creates it and can empty it
|
|---|
| 472 | in the 'clean' project.
|
|---|
| 473 | </td>
|
|---|
| 474 | </tr>
|
|---|
| 475 | <tr>
|
|---|
| 476 | <td><b>dist</b>
|
|---|
| 477 | </td>
|
|---|
| 478 | <td>Distribution outputs go in here; the directory is created in Ant
|
|---|
| 479 | and clean empties it out
|
|---|
| 480 | </td>
|
|---|
| 481 | </tr>
|
|---|
| 482 | <tr>
|
|---|
| 483 | <td><b>doc</b>
|
|---|
| 484 | </td>
|
|---|
| 485 | <td>Hand crafted documentation
|
|---|
| 486 | </td>
|
|---|
| 487 | </tr>
|
|---|
| 488 | <tr>
|
|---|
| 489 | <td><b>lib</b>
|
|---|
| 490 | </td>
|
|---|
| 491 | <td>Imported Java libraries go in to this directory
|
|---|
| 492 | </td>
|
|---|
| 493 | </tr>
|
|---|
| 494 | <tr>
|
|---|
| 495 | <td><b>src</b>
|
|---|
| 496 | </td>
|
|---|
| 497 | <td>source goes in under this tree <i>in a heirarchy which matches
|
|---|
| 498 | the package names<i>. The dependency rules of <javac> requires this.
|
|---|
| 499 | </td>
|
|---|
| 500 | </tr>
|
|---|
| 501 | </table>
|
|---|
| 502 |
|
|---|
| 503 | The bin, lib, doc and src directories should be under source code control.
|
|---|
| 504 | Slight variations include an extra tree of content to be included in the
|
|---|
| 505 | distribution jars -inf files, images, etc. These can go under source
|
|---|
| 506 | too, with a <tt>metadata</tt> directory for web.xml and similar
|
|---|
| 507 | manifests, and a <tt>web</tt> folder for web content -JSP, html, images
|
|---|
| 508 | and so on. Keeping the content in this folder (or sub heirarchy)
|
|---|
| 509 | together makes it easier to test links before deployment. The actual
|
|---|
| 510 | production of a deployment image -such as a war file- can be left to the
|
|---|
| 511 | appropriate Ant task: there is no need to completely model your source tree
|
|---|
| 512 | upon the deployment heirarchy.
|
|---|
| 513 | <p>
|
|---|
| 514 |
|
|---|
| 515 | Javadoc output can be
|
|---|
| 516 | directed to a doc/ folder beneath build/, or to doc/javadoc.
|
|---|
| 517 |
|
|---|
| 518 | <h3>Interface and Implementation split</h3>
|
|---|
| 519 |
|
|---|
| 520 | If the interface is split from the implementation code then this can be
|
|---|
| 521 | supported with minor changes just by having a separate build path for
|
|---|
| 522 | the interface directory -or better still just in the jar construction:
|
|---|
| 523 | one jar for interface and one jar for implementation.
|
|---|
| 524 |
|
|---|
| 525 |
|
|---|
| 526 | <h3>Loosely Coupled Sub Projects</h3>
|
|---|
| 527 |
|
|---|
| 528 | In the loosely coupled approach multiple projects can have their own
|
|---|
| 529 | copy of the tree, with their own source code access rights.
|
|---|
| 530 | One difference to consider is only having one instance of the bin and
|
|---|
| 531 | lib directories across all projects. This is sometimes good -it helps
|
|---|
| 532 | keep copies of xerces.jar in sync, and sometimes bad -it can update
|
|---|
| 533 | foundational jar files before unit testing is complete.
|
|---|
| 534 |
|
|---|
| 535 | <p>
|
|---|
| 536 |
|
|---|
| 537 | To still have a single build across the sub projects, use parent
|
|---|
| 538 | build.xml files which call down into the sub projects.
|
|---|
| 539 |
|
|---|
| 540 | <p>
|
|---|
| 541 |
|
|---|
| 542 | This style works well if different teams have different code
|
|---|
| 543 | access/commitment rights. The risk is that by giving extra leeway to the
|
|---|
| 544 | sub projects, you can end up with incompatible source, libraries, build
|
|---|
| 545 | processes and just increase your workload and integration grief all round.
|
|---|
| 546 | <p>
|
|---|
| 547 | The only way to retain control over a fairly loosely integrated
|
|---|
| 548 | collection of projects is to have a fully automated build
|
|---|
| 549 | and test process which verifies that everything is still compatible. Sam
|
|---|
| 550 | Ruby runs one for all the apache java libraries and emails everyone when
|
|---|
| 551 | something breaks; your own project may be able to make use of
|
|---|
| 552 | <A href="http://cruisecontrol.sourceforge.net/">Cruise Control</a> for
|
|---|
| 553 | an automated, continuous, background build process.
|
|---|
| 554 |
|
|---|
| 555 | <h3>Integrated sub projects</h3>
|
|---|
| 556 |
|
|---|
| 557 | Tightly coupled projects have all the source in the same tree; different
|
|---|
| 558 | projects own different subdirectories. Build files can be moved down to
|
|---|
| 559 | those subdirectores (say src/com/iseran/core and src/com/iseran/extras),
|
|---|
| 560 | or kept at the top -with independent build files named core.xml and
|
|---|
| 561 | extras.xml
|
|---|
| 562 |
|
|---|
| 563 | <p>
|
|---|
| 564 |
|
|---|
| 565 | This project style works well if everyone trusts each other and the
|
|---|
| 566 | sub projects are not too huge or complex. The risk is that a split to a
|
|---|
| 567 | more loosely coupled design will become a requirement as the projects
|
|---|
| 568 | progress -but by the time this is realised schedule pressure and
|
|---|
| 569 | intertwined build files make executing the split well nigh impossible.
|
|---|
| 570 | If that happens then just keep with it until there is the time to
|
|---|
| 571 | refactor the project directory structures.
|
|---|
| 572 |
|
|---|
| 573 | <a name="antupdate">
|
|---|
| 574 | <h2>
|
|---|
| 575 | Ant Update Policies
|
|---|
| 576 | </h2>
|
|---|
| 577 | </a>
|
|---|
| 578 |
|
|---|
| 579 | Once you start using Ant, you should have a policy on when and how the
|
|---|
| 580 | team updates their copies. A simple policy is "every official release
|
|---|
| 581 | after whatever high stress milestone has pushed all unimportant tasks
|
|---|
| 582 | (like sleep and seeing daylight) on the back burner". This insulates you
|
|---|
| 583 | from the changes and occasional instabilities that Ant goes through
|
|---|
| 584 | during development. Its main disadvantage is that it isolates you from
|
|---|
| 585 | the new tasks and features that Ant is constantly adding.
|
|---|
| 586 |
|
|---|
| 587 | <p>
|
|---|
| 588 |
|
|---|
| 589 | Often an update will require changes to the build.xml files. Most
|
|---|
| 590 | changes are intended to be backwards compatible, but sometimes an
|
|---|
| 591 | incompatible change turns out to be
|
|---|
| 592 | necessary. That is why doing the update in the lull after a big
|
|---|
| 593 | milestone is important. It is also why including ant.jar and related
|
|---|
| 594 | files in the CVS tree helps ensure that old versions of your software
|
|---|
| 595 | can be still be built.
|
|---|
| 596 |
|
|---|
| 597 | <p>
|
|---|
| 598 |
|
|---|
| 599 | The most aggressive strategy is to get a weekly or daily snapshot of the
|
|---|
| 600 | ant source, build it up and use it. This forces you to tweak the
|
|---|
| 601 | build.xml files more regulary, as new tasks and attributes can take
|
|---|
| 602 | while to stabilise. You really have to want the new features, enjoy
|
|---|
| 603 | gratuitous extra work or take pleasure in upsetting your colleagues to
|
|---|
| 604 | take this approach.
|
|---|
| 605 |
|
|---|
| 606 | <p>
|
|---|
| 607 |
|
|---|
| 608 | Once you start extending Ant with new tasks, it suddenly becomes much
|
|---|
| 609 | more tempting to pull down regular builds. The most recent Ant builds
|
|---|
| 610 | are invariably the the best platform for writing your extensions, as you
|
|---|
| 611 | can take advantage of the regular enhancements to the foundational
|
|---|
| 612 | classes. It also prevents you from wasting time working on something
|
|---|
| 613 | which has already been done. A newly submitted task to do something
|
|---|
| 614 | complex such as talk to EJB engines, SOAP servers or just convert a text
|
|---|
| 615 | file to uppercase may be almost exactly what you need -so take it,
|
|---|
| 616 | enhance it and offer up the enhancements to the rest of the world. This
|
|---|
| 617 | is certainly better than starting work on your 'text case converter'
|
|---|
| 618 | task on Ant 0.8 in isolation, announcing its existence six months latter
|
|---|
| 619 | and discovering that instead of adulation all you get are helpful
|
|---|
| 620 | pointers to the existing implementation. The final benefit of being
|
|---|
| 621 | involved with the process is that it makes it easier for your tasks to
|
|---|
| 622 | be added with the Ant CVS tree, bringing forward the date when Ant has
|
|---|
| 623 | taken on all the changes you needed to make to get your project to work.
|
|---|
| 624 | If that happens you can revert to an official Ant release, and get on
|
|---|
| 625 | with all the other crises.
|
|---|
| 626 |
|
|---|
| 627 | <p>
|
|---|
| 628 |
|
|---|
| 629 | You should also get on the <a href =
|
|---|
| 630 | "mailto:[email protected]" > dev mailing list
|
|---|
| 631 | </a>, as it is where the other developers post their work, problems and
|
|---|
| 632 | experience. The volume can be quite high: 40+ messages a day, so
|
|---|
| 633 | consider routing it to an email address you don't use for much else. And
|
|---|
| 634 | don't make everyone on the team subscribe; it can be too much of a
|
|---|
| 635 | distraction.
|
|---|
| 636 |
|
|---|
| 637 | <a name="install">
|
|---|
| 638 | <h2>
|
|---|
| 639 | Installing with Ant.
|
|---|
| 640 | </h2>
|
|---|
| 641 | </a>
|
|---|
| 642 |
|
|---|
| 643 | Because Ant can read environment variables, copy, unzip and delete files
|
|---|
| 644 | and make java and OS calls, it can be used for simple installation
|
|---|
| 645 | tasks. For example, an installer for tomcat could extract the
|
|---|
| 646 | environment variable TOMCAT_HOME, stop tomcat running, and copy a war
|
|---|
| 647 | file to TOMCAT_HOME/webapps. It could even start tomcat again, but the
|
|---|
| 648 | build wouldn't complete until tomcat exited, which is probably not what
|
|---|
| 649 | was wanted.
|
|---|
| 650 |
|
|---|
| 651 | <p>
|
|---|
| 652 |
|
|---|
| 653 | The advantage of using Ant is firstly that the same install targets
|
|---|
| 654 | can be used from your local build files (via an <tt>ant</tt> invocation
|
|---|
| 655 | of the install.xml file), and secondly that a basic install target is
|
|---|
| 656 | quite easy to write. The disadvantages of this approach are that the
|
|---|
| 657 | destination must have an up to date version of Ant correctly
|
|---|
| 658 | pre-installed, and Ant doesn't allow you to handle failures well -and a
|
|---|
| 659 | good installer is all about handling when things go wrong, from files
|
|---|
| 660 | being in use to jar versions being different. This means that Ant is not
|
|---|
| 661 | suited for shrink wrapped software, but it does work for deployment and
|
|---|
| 662 | installation to your local servers.
|
|---|
| 663 |
|
|---|
| 664 | <p>
|
|---|
| 665 |
|
|---|
| 666 | One major build project I was involved in had an Ant install build file
|
|---|
| 667 | for the bluestone application server, which would shutdown all four
|
|---|
| 668 | instances of the app server on a single machine, copy the new version of
|
|---|
| 669 | the war file (with datestamp and buildstamp) to an archive directory,
|
|---|
| 670 | clean up the current deployed version of the war and then install the
|
|---|
| 671 | new version. Because bluestone restarted JVMs on demand, this script was
|
|---|
| 672 | all you needed for web service deployment. On the systems behind the
|
|---|
| 673 | firewall, we upped the ante in the deployment process by using the ftp
|
|---|
| 674 | task to copy out the war and build files, then the telnet task to
|
|---|
| 675 | remotely invoke the build file. The result was we had automated
|
|---|
| 676 | recompile and redeploy to local servers from inside our IDE (Jedit) or
|
|---|
| 677 | the command line, which was simply invaluable. Imagine pressing a button
|
|---|
| 678 | on your IDE toolbar to build, unit test, deploy and then functional test
|
|---|
| 679 | your webapp.
|
|---|
| 680 |
|
|---|
| 681 | <p>
|
|---|
| 682 |
|
|---|
| 683 | One extra trick I added later was a junit test case to run through the
|
|---|
| 684 | install check list. With tests to verify access permissions on network
|
|---|
| 685 | drives, approximate clock synchronisation between servers, DNS
|
|---|
| 686 | functionality, ability to spawn executables and all the other trouble
|
|---|
| 687 | spots, the install script could automatically do a system health test
|
|---|
| 688 | during install time and report problems. [The same tests could also be
|
|---|
| 689 | invoked from a JMX MBean, but that's another story].
|
|---|
| 690 |
|
|---|
| 691 | <p>
|
|---|
| 692 |
|
|---|
| 693 | So, Ant is not a substitute for a real installer tool, except in the
|
|---|
| 694 | special case of servers you control, but in that context it does let
|
|---|
| 695 | you integrate remote installation with your build.
|
|---|
| 696 |
|
|---|
| 697 |
|
|---|
| 698 | <a name="tips">
|
|---|
| 699 | <h2>
|
|---|
| 700 | Tips and Tricks</h2>
|
|---|
| 701 | </a>
|
|---|
| 702 | <dl>
|
|---|
| 703 | <dt><b>
|
|---|
| 704 | get
|
|---|
| 705 | </b><dd>
|
|---|
| 706 |
|
|---|
| 707 | The <a href="manual/CoreTasks/get.html"><get></a> task can fetch any URL, so be used
|
|---|
| 708 | to trigger remote server side code during the build process, from remote
|
|---|
| 709 | server restarts to sending SMS/pager messages to the developer
|
|---|
| 710 | cellphones.
|
|---|
| 711 |
|
|---|
| 712 | <dt><b>
|
|---|
| 713 | i18n
|
|---|
| 714 | </b><dd>
|
|---|
| 715 |
|
|---|
| 716 |
|
|---|
| 717 | Internationalisation is always trouble. Ant helps here with the <A href=
|
|---|
| 718 | "manual/OptionalTasks/native2ascii.html">native2ascii</a> task which can escape out all non
|
|---|
| 719 | ascii characters into unicode. You can use this to write java files
|
|---|
| 720 | which include strings (and indeed comments) in your own non-ASCII
|
|---|
| 721 | language and then use native2ascii to convert to ascii prior to feeding
|
|---|
| 722 | through javac. The rest of i18n and l12n is left to you...
|
|---|
| 723 |
|
|---|
| 724 | <dt><b>
|
|---|
| 725 | Use Property Files
|
|---|
| 726 | </b><dd>
|
|---|
| 727 |
|
|---|
| 728 | Use external property files to keep per-user settings out the build
|
|---|
| 729 | files -especially passwords. Property files can also be used to
|
|---|
| 730 | dynamically set a number of properties based on the value of a single
|
|---|
| 731 | property, simply by dyamically generating the property filename from the
|
|---|
| 732 | source property. They can also be used as a source of constants across
|
|---|
| 733 | multiple build files.
|
|---|
| 734 |
|
|---|
| 735 | <dt><b>
|
|---|
| 736 | Faster compiles with Jikes
|
|---|
| 737 | </b><dd>
|
|---|
| 738 |
|
|---|
| 739 | The <a href="http://www.jikes.org/">jikes compiler</a> is usually much
|
|---|
| 740 | faster than javac, does dependency checking and has better error
|
|---|
| 741 | messages (usually). Get it. Then set
|
|---|
| 742 | build.compiler to "jikes" for it to be used in your build files.
|
|---|
| 743 | Doing this explicitly in your build files is a bit dubious as it requires the
|
|---|
| 744 | whole team (and sub projects) to be using jikes too -something you can only
|
|---|
| 745 | control in small, closed source projects. But if you set
|
|---|
| 746 | <tt>ANT_OPTS = -Dbuild.compiler=jikes</tt>
|
|---|
| 747 | in your environment, then all your builds on your system will use
|
|---|
| 748 | Jikes automatically, while others can choose their own compiler, or let
|
|---|
| 749 | ant choose whichever is appropriate for the current version of Java.
|
|---|
| 750 |
|
|---|
| 751 | <dt><b>
|
|---|
| 752 | #include targets to simplify multi build.xml projects
|
|---|
| 753 | </b><dd>
|
|---|
| 754 |
|
|---|
| 755 | You can import XML files into a build file using the XML parser itself.
|
|---|
| 756 | This lets a multi-project development program share code through reference,
|
|---|
| 757 | rather than cut and paste re-use. It also lets one build up a file of
|
|---|
| 758 | standard tasks which can be reused over time. Because the import
|
|---|
| 759 | mechanism is at a level below which Ant is aware, treat it as
|
|---|
| 760 | equivalent to the #include mechanism of the 'legacy' languages C and
|
|---|
| 761 | C++.
|
|---|
| 762 |
|
|---|
| 763 | <p>
|
|---|
| 764 |
|
|---|
| 765 | There are two inclusion mechanisms, an ugly one for all parsers and a
|
|---|
| 766 | clean one. The ugly method is the only one that was available on Ant1.5 and
|
|---|
| 767 | earlier:-
|
|---|
| 768 | <pre>
|
|---|
| 769 | <!DOCTYPE project [
|
|---|
| 770 | <!ENTITY propertiesAndPaths SYSTEM "propertiesAndPaths.xml">
|
|---|
| 771 | <!ENTITY taskdefs SYSTEM "taskdefs.xml">
|
|---|
| 772 | ]>
|
|---|
| 773 |
|
|---|
| 774 | &propertiesAndPaths;
|
|---|
| 775 | &taskdefs;
|
|---|
| 776 | </pre>
|
|---|
| 777 | The cleaner method in Ant1.6 is the <tt><import></tt> task that imports
|
|---|
| 778 | whole build files into other projects. The entity inclusion example
|
|---|
| 779 | could <i>almost</i> be replaced by two import statements:-
|
|---|
| 780 | <pre>
|
|---|
| 781 | <import file="propertiesAndPaths.xml">
|
|---|
| 782 | <import file="taskdefs.xml">
|
|---|
| 783 | </pre>
|
|---|
| 784 |
|
|---|
| 785 | We say almost as top level declarations (properties and taskdefs)
|
|---|
| 786 | do not get inserted into the XML file exactly where the import statement
|
|---|
| 787 | goes, but added to the end of the file. This is because the import process
|
|---|
| 788 | takes place after the main build file is parsed, during execution, whereas
|
|---|
| 789 | XML entity expansion is handled during the parsing process.
|
|---|
| 790 |
|
|---|
| 791 | <p>
|
|---|
| 792 |
|
|---|
| 793 | The <tt><import></tt> task does powerful things, such as let you override targets,
|
|---|
| 794 | and use ant properties to name the location of the file to import. Consult the
|
|---|
| 795 | <a href="manual/CoreTasks/import.html">documentation</a> for the specifics of
|
|---|
| 796 | these features.
|
|---|
| 797 |
|
|---|
| 798 | <p>
|
|---|
| 799 |
|
|---|
| 800 | Before you go overboard with using XML inclusion, note that the
|
|---|
| 801 | <tt><ant></tt> task lets you call any target in any other build
|
|---|
| 802 | file -with all your property settings propagating down to that target.
|
|---|
| 803 | So you can actually have a suite of utility targets
|
|---|
| 804 | -"deploy-to-stack-a", "email-to-team", "cleanup-installation" which can
|
|---|
| 805 | be called from any of your main build files, perhaps with subtly changed
|
|---|
| 806 | parameters. Indeed, after a couple of projects you may be able to create
|
|---|
| 807 | a re-usable core build file which contains the core targets of a basic
|
|---|
| 808 | Java development project -compile, debug, deploy- which project specific
|
|---|
| 809 | build files call with their own settings. If you can achive this then
|
|---|
| 810 | you are definately making your way up the software maturity ladder. With
|
|---|
| 811 | a bit of work you may progress from being a SEI CMM Level 0 organisation
|
|---|
| 812 | "Individual Heroics are not enough" to SEI CMM Level 1, "Projects only
|
|---|
| 813 | succeed due to individual heroics"
|
|---|
| 814 |
|
|---|
| 815 | <p>
|
|---|
| 816 |
|
|---|
| 817 | NB, <tt><ant></tt> copies all your properties unless the
|
|---|
| 818 | <i>inheritall</i> attribute is set to false. Before that attribute
|
|---|
| 819 | existed you had to carefully name all property definitions in all build
|
|---|
| 820 | files to prevent unintentional overwriting of the invoked property by
|
|---|
| 821 | that of the caller, now you just have to remember to set
|
|---|
| 822 | <tt>inheritall="false"</tt> on all uses of the <ant> task.
|
|---|
| 823 |
|
|---|
| 824 |
|
|---|
| 825 | <dt><b>
|
|---|
| 826 | Implement complex Ant builds through XSL
|
|---|
| 827 | </b><dd>
|
|---|
| 828 |
|
|---|
| 829 | XSLT can be used to dynamically generate build.xml files from a source
|
|---|
| 830 | xml file, with the <a href="manual/CoreTasks/style.html"><xslt></a> task controlling
|
|---|
| 831 | the transform. This is the current recommended strategy for creating
|
|---|
| 832 | complex build files dynamically. However, its use is still apparently
|
|---|
| 833 | quite rare -which means you will be on the bleeding edge of technology.
|
|---|
| 834 |
|
|---|
| 835 |
|
|---|
| 836 | <dt><b>
|
|---|
| 837 | Change the invocation scripts
|
|---|
| 838 | </b><dd>
|
|---|
| 839 |
|
|---|
| 840 | By writing your own invocation script -using the DOS, Unix or Perl
|
|---|
| 841 | script as a starting point- you can modify Ant's settings and behavior for an
|
|---|
| 842 | individual project. For example, you can use an alternate variable to
|
|---|
| 843 | ANT_HOME as the base, extend the classpath differently, or dynamically
|
|---|
| 844 | create a new command line property 'project.interfaces' from all .jar
|
|---|
| 845 | files in an interfaces directory.
|
|---|
| 846 |
|
|---|
| 847 | <p>
|
|---|
| 848 |
|
|---|
| 849 | Having a custom invocation script which runs off a CVS controlled
|
|---|
| 850 | library tree under PROJECT_HOME also lets you control Ant versions
|
|---|
| 851 | across the team -developers can have other copies of Ant if they want,
|
|---|
| 852 | but the CVS tree always contains the jar set used to build your project.
|
|---|
| 853 |
|
|---|
| 854 | <p>
|
|---|
| 855 |
|
|---|
| 856 | You can also write wrapper scripts which invoke the existing Ant
|
|---|
| 857 | scripts. This is an easy way to extend them. The wrapper scripts can add
|
|---|
| 858 | extra definitions and name explicit targets, redefine ANT_HOME and
|
|---|
| 859 | generally make development easier. Note that "ant" in Windows is really
|
|---|
| 860 | "ant.bat", so should be invoked from another batch file with a "CALL
|
|---|
| 861 | ant" statement -otherwise it never returns to your wrapper.
|
|---|
| 862 |
|
|---|
| 863 |
|
|---|
| 864 | <dt><b>
|
|---|
| 865 | Write all code so that it can be called from Ant
|
|---|
| 866 | </b><dd>
|
|---|
| 867 |
|
|---|
| 868 | This seems a bit strange and idealistic, but what it means is that you should
|
|---|
| 869 | write all your java code as if it may be called as a library at some point in
|
|---|
| 870 | future. So do not place calls to <tt>System.exit()</tt> deep in the code -if you
|
|---|
| 871 | want to exit a few functions in, raise an exception instead and have
|
|---|
| 872 | <tt>main()</tt> deal with it.
|
|---|
| 873 |
|
|---|
| 874 | <p>
|
|---|
| 875 |
|
|---|
| 876 | Moving one step further, consider proving an Ant Task interface to the
|
|---|
| 877 | code as a secondary, primary or even sole interface to the
|
|---|
| 878 | functionality. Ant actually makes a great bootloader for Java apps as it
|
|---|
| 879 | handles classpath setup, and you can re-use all the built in tasks for
|
|---|
| 880 | preamble and postamble work. Some projects, such as
|
|---|
| 881 | <a href="http://xdoclet.sf.net">XDoclet</a> only run under Ant, because
|
|---|
| 882 | that is the right place to be.
|
|---|
| 883 |
|
|---|
| 884 |
|
|---|
| 885 |
|
|---|
| 886 | <!-- <dt><b>
|
|---|
| 887 | Use Antidote as the invocation tool
|
|---|
| 888 | </b><dd>
|
|---|
| 889 | Even if you edit Ant files by hand, Antidote makes a good execution tool
|
|---|
| 890 | because it eliminates the startup time of the JVM, perhaps even some of
|
|---|
| 891 | the XML parsing delays.
|
|---|
| 892 | -->
|
|---|
| 893 | <dt><b>
|
|---|
| 894 | Use the replace task to programmatic modify text files in your project.
|
|---|
| 895 | </b><dd>
|
|---|
| 896 | Imagine your project has some source files -BAT files, ASPX pages (!), anything
|
|---|
| 897 | which needs to be statically customised at compile time for particular
|
|---|
| 898 | installations, such driven from some properties of the project such as JVM options, or the URL
|
|---|
| 899 | to direct errors too. The replace task can be used to modify files, substituting text and creating
|
|---|
| 900 | versions customised for that build or destination. Of course, per-destination customisation
|
|---|
| 901 | should be delayed until installation, but if you are using Ant for the remote installation
|
|---|
| 902 | that suddenly becomes feasible.
|
|---|
| 903 |
|
|---|
| 904 |
|
|---|
| 905 |
|
|---|
| 906 | <dt><b>
|
|---|
| 907 | Use the mailing lists
|
|---|
| 908 | </b><dd>
|
|---|
| 909 | There are two
|
|---|
| 910 | <a href="http://ant.apache.org/mail.html">mailing lists</a>
|
|---|
| 911 | related to Ant, user and developer. Ant user is where <i>all</i>
|
|---|
| 912 | questions related to using Ant should go. Installation, syntax, code
|
|---|
| 913 | samples, etc -post your questions there or search the archives for
|
|---|
| 914 | whether the query has been posted and answered before. Ant-developer
|
|---|
| 915 | is where Ant development takes place -so it is <i>not</i> the place to
|
|---|
| 916 | post things like "I get a compilation error when I build my project" or
|
|---|
| 917 | "how do I make a zip file". If you are actually extending Ant, on the other
|
|---|
| 918 | hand, it is the ideal place to ask questions about how to add new tasks, make
|
|---|
| 919 | changes to existing ones -and to post the results of your work, if you want them
|
|---|
| 920 | incorporated into the Ant source tree.
|
|---|
| 921 |
|
|---|
| 922 | </dl>
|
|---|
| 923 |
|
|---|
| 924 | <a name="puttingtogether">
|
|---|
| 925 | <h2>
|
|---|
| 926 | Putting it all together
|
|---|
| 927 | </h2>
|
|---|
| 928 | </a>
|
|---|
| 929 |
|
|---|
| 930 | What does an Ant build process look like in this world? Assuming a
|
|---|
| 931 | single directory structure for simplicity, the build file
|
|---|
| 932 | should contain a number of top level targets
|
|---|
| 933 | <ul>
|
|---|
| 934 | <li>build - do an (incremental) build
|
|---|
| 935 | <li>test - run the junit tests
|
|---|
| 936 | <li>clean - clean out the output directories
|
|---|
| 937 | <li>deploy - ship the jars, wars, whatever to the execution system
|
|---|
| 938 | <li>publish - output the source and binaries to any distribution site
|
|---|
| 939 | <li>fetch - get the latest source from the cvs tree
|
|---|
| 940 | <li>docs/javadocs - do the documenation
|
|---|
| 941 | <li>all - clean, fetch, build, test, docs, deploy
|
|---|
| 942 | <li>main - the default build process (usually build or build & test)
|
|---|
| 943 | </ul>
|
|---|
| 944 | Sub projects 'web', 'bean-1', 'bean-2' can be given their own build
|
|---|
| 945 | files -web.xml, bean-1.xml, bean-2.xml- with the same entry points.
|
|---|
| 946 | Extra toplevel tasks related to databases, web site images and the like
|
|---|
| 947 | should be considered if they are part of the process.
|
|---|
| 948 |
|
|---|
| 949 | <p>
|
|---|
| 950 | Debug/release switching can be handled with separate initialisation
|
|---|
| 951 | targets called before the compile tasks which define the appropriate
|
|---|
| 952 | properties. Antcall is the trick here, as it allows you to have two paths
|
|---|
| 953 | of property initialisation in a build file.
|
|---|
| 954 |
|
|---|
| 955 | <p>
|
|---|
| 956 | Internal targets should be used to structure the process
|
|---|
| 957 | <ul>
|
|---|
| 958 | <li> init - initialise properties, extra-tasks, read in per-user
|
|---|
| 959 | property files.
|
|---|
| 960 | <li> init-release - initialise release properties
|
|---|
| 961 | <li> compile - do the actual compilation
|
|---|
| 962 | <li> link/jar - make the jars or equivalent
|
|---|
| 963 | <li> staging - any pre-deployment process in which the output is dropped
|
|---|
| 964 | off then tested before being moved to the production site.
|
|---|
| 965 | </ul>
|
|---|
| 966 |
|
|---|
| 967 | The switching between debug and release can be done by making
|
|---|
| 968 | init-release conditional on a property, such as <tt>release.build</tt>
|
|---|
| 969 | being set :-
|
|---|
| 970 |
|
|---|
| 971 | <pre><target name="init-release" if="release.build">
|
|---|
| 972 | <property name="build.debuglevel" value="lines,source"/>
|
|---|
| 973 | </target>
|
|---|
| 974 | </pre>
|
|---|
| 975 |
|
|---|
| 976 | You then have dependent targets, such as "compile", depend on this
|
|---|
| 977 | conditional target; there the 'default' properties are set, and then the
|
|---|
| 978 | property is actually used. Because Ant properties are <i>immutable</i>,
|
|---|
| 979 | if the release target was executed its settings will override the
|
|---|
| 980 | default values:
|
|---|
| 981 |
|
|---|
| 982 | <pre><target name="compile" depends="init,init-release">
|
|---|
| 983 | <property name="build.debuglevel" value="lines,vars,source"/>
|
|---|
| 984 | <echo>debug level=${build.debuglevel}</echo>
|
|---|
| 985 | <javac destdir="${build.classes.dir}"
|
|---|
| 986 | debug="true"
|
|---|
| 987 | debuglevel="${build.debuglevel}"
|
|---|
| 988 | includeAntRuntime="false"
|
|---|
| 989 | srcdir="src">
|
|---|
| 990 | <classpath refid="compile.classpath"/>
|
|---|
| 991 | </javac>
|
|---|
| 992 | </target>
|
|---|
| 993 | </pre>
|
|---|
| 994 |
|
|---|
| 995 | As a result, we now have a build where the release mode only includes
|
|---|
| 996 | the filename and line debug information (useful for bug reports), while
|
|---|
| 997 | the development system included variables too.
|
|---|
| 998 | <p>
|
|---|
| 999 |
|
|---|
| 1000 | It is useful to define a project name property which can be echoed in
|
|---|
| 1001 | the init task. This lets you work out which Ant file is breaking in a
|
|---|
| 1002 | multi file build.
|
|---|
| 1003 |
|
|---|
| 1004 | <p>
|
|---|
| 1005 |
|
|---|
| 1006 | What goes in to the internal Ant tasks depends on your own projects. One
|
|---|
| 1007 | very important tactic is 'keep path redefinition down through
|
|---|
| 1008 | references' - you can reuse paths by giving them an ID and then
|
|---|
| 1009 | referring to them via the 'refid' attribute you should only need to
|
|---|
| 1010 | define a shared classpath once in the file; filesets can be reused
|
|---|
| 1011 | similarly.
|
|---|
| 1012 |
|
|---|
| 1013 | <p>
|
|---|
| 1014 |
|
|---|
| 1015 | Once you have set up the directory structures, and defined the Ant tasks
|
|---|
| 1016 | it is time to start coding. An early priority must be to set up the
|
|---|
| 1017 | automated test process, as that not only helps ensures that the code
|
|---|
| 1018 | works, it verifies that the build process is working.
|
|---|
| 1019 |
|
|---|
| 1020 | <p>
|
|---|
| 1021 |
|
|---|
| 1022 | And that's it. The build file shouldn't need changing as new source
|
|---|
| 1023 | files get added, only when you want to change the deliverables or part
|
|---|
| 1024 | of the build process. At some point you may want to massively
|
|---|
| 1025 | restructure the entire build process, restructuring projects and the
|
|---|
| 1026 | like, but even then the build file you have should act as a foundation
|
|---|
| 1027 | for a split build file process -just pull out the common properties into
|
|---|
| 1028 | a properties file all build files read in, keep the target names unified
|
|---|
| 1029 | and keep going with the project. Restructuring the source code control
|
|---|
| 1030 | system is often much harder work.
|
|---|
| 1031 |
|
|---|
| 1032 | <h2>The Limits of Ant</h2>
|
|---|
| 1033 |
|
|---|
| 1034 | Before you start adopting Ant as the sole mechanism for the build
|
|---|
| 1035 | process, you need to be aware of what it doesn't do.
|
|---|
| 1036 | <p>
|
|---|
| 1037 |
|
|---|
| 1038 | <h3>It's not a scripting language</h3>
|
|---|
| 1039 |
|
|---|
| 1040 | Ant lets you declare what you want done, with a bit of testing of the
|
|---|
| 1041 | platform and class libraries first to enable some platform specific
|
|---|
| 1042 | builds to take place. It does not let you specify how to handle things
|
|---|
| 1043 | going wrong (a listener class can do that), or support complex
|
|---|
| 1044 | conditional statements.
|
|---|
| 1045 |
|
|---|
| 1046 | <p>
|
|---|
| 1047 |
|
|---|
| 1048 | If your build needs to handle exceptions then look at the sound listener
|
|---|
| 1049 | as a simple example of how to write your own listener class. Complex
|
|---|
| 1050 | conditional statements can be handled by having something else do the
|
|---|
| 1051 | tests and then build the appropriate Ant task. XSLT can be used for
|
|---|
| 1052 | this.
|
|---|
| 1053 |
|
|---|
| 1054 | <h3>It's not Make</h3>
|
|---|
| 1055 |
|
|---|
| 1056 | Some of the features of make, specifically inference rules and
|
|---|
| 1057 | dependency checking are not included in Ant. That's because they are
|
|---|
| 1058 | 'different' ways of doing a build. Make requires you to state
|
|---|
| 1059 | dependencies and the build steps, Ant wants you to state tasks and the
|
|---|
| 1060 | order between them, the tasks themselves can do depedency checking or
|
|---|
| 1061 | not. A full java build using Jikes is so fast that dependency checking
|
|---|
| 1062 | is relatively moot, while many of the other tasks (but not all), compare
|
|---|
| 1063 | the timestamp of the source file with that of the destination file
|
|---|
| 1064 | before acting.
|
|---|
| 1065 |
|
|---|
| 1066 | <h3>It's not meant to be a nice language for humans</h3>
|
|---|
| 1067 |
|
|---|
| 1068 | XML isn't a nice representation of information for humans. It's a
|
|---|
| 1069 | reasonable representation for programs, and text editors and source code
|
|---|
| 1070 | management systems can all handle it nicely. But a complex Ant file can
|
|---|
| 1071 | get ugly because XML is a bit ugly, and a complex build is, well,
|
|---|
| 1072 | complicated. Use XML comments so that the file you wrote last month
|
|---|
| 1073 | still makes sense when you get back to it, and use Antidote to edit the
|
|---|
| 1074 | files if you prefer it.
|
|---|
| 1075 |
|
|---|
| 1076 | <h3>Big projects still get complicated fast</h3>
|
|---|
| 1077 |
|
|---|
| 1078 | Large software projects create their own complexity, with inter-dependent
|
|---|
| 1079 | libraries, long test cycles, hard deployment processes and a multitude of
|
|---|
| 1080 | people each working on their own bit of the solution. That's even before
|
|---|
| 1081 | the deadlines loom close, the integration problems become insurmountable,
|
|---|
| 1082 | weekends become indistinguishable from weekdays in terms of workload and
|
|---|
| 1083 | half the team stops talking to the other half. Ant may simplify the
|
|---|
| 1084 | build and test process, and can eliminate the full time 'makefile engineer'
|
|---|
| 1085 | role, but that doesn't mean that someone can stop 'owning the build'.
|
|---|
| 1086 | Being in charge of the build has to mean more than they type 'ant all' on
|
|---|
| 1087 | their system, it means they need to set the standards of what build tools to
|
|---|
| 1088 | use, what the common targets, what property names and files should be
|
|---|
| 1089 | and generally oversee the sub projects build processes. On a small project,
|
|---|
| 1090 | you don't need to do that -but remember: small projects become big projects
|
|---|
| 1091 | when you aren't looking. If you start off with a little bit of process, then
|
|---|
| 1092 | you can scale it if needed. If you start with none, by the time you need
|
|---|
| 1093 | it it will be too late.
|
|---|
| 1094 |
|
|---|
| 1095 | <h3>You still need all the other foundational bits of a software
|
|---|
| 1096 | project</h3>
|
|---|
| 1097 |
|
|---|
| 1098 | If you don't have an source code management system, you are going to end
|
|---|
| 1099 | up hosed. If you don't have everything under SCM, including web pages,
|
|---|
| 1100 | dependent jars, installation files, you are still going to end up hosed,
|
|---|
| 1101 | it's just a question of when it's going to happen.
|
|---|
| 1102 | CVS is effectively free and works well with Ant, but Sourcesafe, Perforce,
|
|---|
| 1103 | Clearcase and StarTeam also have Ant tasks. These tasks
|
|---|
| 1104 | let you have auto-incrementing build counters, and automated file
|
|---|
| 1105 | update processes.
|
|---|
| 1106 |
|
|---|
| 1107 | <p>
|
|---|
| 1108 |
|
|---|
| 1109 | You also need some kind of change control process, to resist
|
|---|
| 1110 | uncontrolled feature creep. Bugzilla is a simple and low cost tool for
|
|---|
| 1111 | this, using Ant and a continuous test process enables a rapid evolution of code
|
|---|
| 1112 | to adapt to those changes which are inevitable.
|
|---|
| 1113 |
|
|---|
| 1114 | <h2>Endpiece</h2>
|
|---|
| 1115 |
|
|---|
| 1116 | Software development is meant to be fun. Being in the maelstrom of a
|
|---|
| 1117 | tight project with the stress of integration and trying to code
|
|---|
| 1118 | everything up for an insane deadline can be fun -it is certainly
|
|---|
| 1119 | exhilirating. Adding a bit of automation to the process may make things
|
|---|
| 1120 | less chaotic, and bit less entertaining, but it is a start to putting
|
|---|
| 1121 | you in control of your development process. You can still have fun, you
|
|---|
| 1122 | should just have less to worry about, a shorter build/test/deploy cycle
|
|---|
| 1123 | and more time to spend on feature creep or important things like skiing.
|
|---|
| 1124 | So get out there and have fun!
|
|---|
| 1125 |
|
|---|
| 1126 | <a name="reading">
|
|---|
| 1127 | <h2>Further Reading</h2>
|
|---|
| 1128 | </a>
|
|---|
| 1129 | <ul>
|
|---|
| 1130 | <li>
|
|---|
| 1131 | <a
|
|---|
| 1132 | href="http://www.martinfowler.com/articles/continuousIntegration.html">
|
|---|
| 1133 | <i>Continuous Integration</i></a>; Martin Fowler. <br>
|
|---|
| 1134 | A paper on using Ant within a software project
|
|---|
| 1135 | running a continuous integration/testing proces.
|
|---|
| 1136 | <li><i> Refactoring</i>; Martin Fowler, ISBN: 0201485672 <br>
|
|---|
| 1137 | Covers JUnit as well as tactics for making some headway with the mess of
|
|---|
| 1138 | code you will soon have.
|
|---|
| 1139 |
|
|---|
| 1140 | <li><a href="http://manning.com/antbook/"><i>Java Development with
|
|---|
| 1141 | Ant</i></a>;
|
|---|
| 1142 | Erik Hatcher and Steve Loughran.
|
|---|
| 1143 |
|
|---|
| 1144 |
|
|---|
| 1145 | <li>
|
|---|
| 1146 | <a href="http://www.iseran.com/Steve/papers/when_web_services_go_bad.html">
|
|---|
| 1147 | <i>When Web Services Go Bad</i></a>; Steve Loughran.<br>
|
|---|
| 1148 | One of the projects this paper is based on.
|
|---|
| 1149 |
|
|---|
| 1150 |
|
|---|
| 1151 | </ul>
|
|---|
| 1152 |
|
|---|
| 1153 | <a name="author">
|
|---|
| 1154 | <h3>About the Author</h3>
|
|---|
| 1155 | </a>
|
|---|
| 1156 |
|
|---|
| 1157 | Steve Loughran is a research scientist at a corporate R&D lab,
|
|---|
| 1158 | currently on a sabbatical building production web services against
|
|---|
| 1159 | implausible deadlines for the fun of it. He is also a committer on
|
|---|
| 1160 | Apache Ant and Apache Axis, and co-author of
|
|---|
| 1161 | <a href="http://manning.com/antbook/"><i>Java Development with Ant</i></a>.
|
|---|
| 1162 | He thinks that if you liked this document you'll love that book because
|
|---|
| 1163 | it doesn't just explain Ant, it goes into processes, deployment and best practices
|
|---|
| 1164 | and other corners of stuff that really make Ant useful. (It would
|
|---|
| 1165 | have been easier to just rehash the manual, but that wouldn't have been
|
|---|
| 1166 | so useful or as much fun).
|
|---|
| 1167 |
|
|---|
| 1168 | <p>
|
|---|
| 1169 |
|
|---|
| 1170 | For questions related to this document, use the Ant mailing list.
|
|---|
| 1171 |
|
|---|
| 1172 | <hr>
|
|---|
| 1173 | <p align="center">Copyright © 2000-2003 Apache Software Foundation. All rights
|
|---|
| 1174 | Reserved.</p>
|
|---|
| 1175 | </body>
|
|---|
