ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: jakarta-ant/docs ant_in_anger.html
Date Fri, 10 Aug 2001 09:58:13 GMT
bodewig     01/08/10 02:58:13

  Modified:    docs     Tag: ANT_14_BRANCH ant_in_anger.html
  Some updates by Steve:
   -bit more on deployment
   -more on installation, including an anecdote on how you can have one build
  file doing an ftp then a telnet to run a remote install with junit tests.
  Does anyone else do this yet?
   -refer to some more new tasks
   -clarified how to include stuff into an build file, emphasising that <ant>
  usually works better.
  Submitted by:	Steve Loughran <>
  <execon> is now <apply>
  Revision  Changes    Path
  No                   revision
  No                   revision   +207 -32   jakarta-ant/docs/ant_in_anger.html
  Index: ant_in_anger.html
  RCS file: /home/cvs/jakarta-ant/docs/ant_in_anger.html,v
  retrieving revision 1.3
  retrieving revision
  diff -u -r1.3 -r1.3.2.1
  --- ant_in_anger.html	2001/02/13 12:31:47	1.3
  +++ ant_in_anger.html	2001/08/10 09:58:13
  @@ -12,7 +12,7 @@
   <h4  align="center">
  -Steve Loughran (<a href=""></a>)
  +Steve Loughran
   <a name="introduction">
  @@ -38,7 +38,7 @@
   Firstly, here are some assumptions about the projects which this
   document covers
  -<li> Pretty much pure Java.
  +<li> Pretty much pure Java, maybe with some legacy cruft on the edges.
   <li> Team efforts, usually with the petulant prima-donnas all us Java
   programmers become once we realise how much in demand we are.
  @@ -52,7 +52,7 @@
   <li> Significant mismatch between expectations and time available to
   deliver. 'Last Week' is the ideal delivery date handed down from above,
  -next century the date coming up from below.
  +late next century the date coming up from below.
   <li> Everyone is struggling to keep up with platform and tool evolution.
  @@ -107,8 +107,8 @@
   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">ant</a>
  -task. For example. the clean target could be handed down to the intf and
  -impl subdirectories from a parent directory
  +task. For example. the clean target could be handed down to the <tt>intf</tt>
  +<tt>impl</tt> subdirectories from a parent directory
   <pre>&lt;target name=&quot;clean&quot;  depends=&quot;clean-intf,
  @@ -121,6 +121,11 @@
   	&lt;ant dir=&quot;impl&quot; target=&quot;clean&quot; /&gt;
   &lt;/target&gt;  </pre>
  +If you give targets a <tt>description</tt> tag, then calling <tt>ant
  +-projecthelp</tt> will list all tasks with their description as 'main targets', and

  +all tasks without a description as subtargets. Describing all your
  +entry points is therefore very useful, even before a project becomes big and complicated.
   	Extend ant through new tasks
  @@ -178,7 +183,13 @@
   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.
  +full build. The Junit extensions such as 
  +<a href="">HttpUnit</a> for web pages, and

  +<a href="">Cactus</a> for J2EE and
  +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 
  +you for shipping software that works.   
   <a name="crossplatform">
  @@ -199,7 +210,7 @@
   in the location of things.
   <h3>Command Line apps: <a href="manual/CoreTasks/exec.html">Exec</a>/
<a href=
   The trouble with external invocation is that not all functions are found
   cross platform, and those that are often have different names -DOS
  @@ -225,7 +236,7 @@
   a path in unix. In Windows the path must use semicolon separators,
   colons being used to specify disk drives, and backslash separators
   This difference between platforms (indeed, the whole java classpath
   paradigm) can cause hours of fun.
  @@ -242,8 +253,13 @@
   better to build a classpath by listing individual files (using location=
   attributes), or by including a fileset of *.jar in the classpath
  +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 
  +some application you are calling, or use the replace task to patch it
  +into a localised shell script or batch file.
   Note that DOS descended file systems are case insensitive (apart from
   the obscure aberration of the WinNT posix subsystem run against NTFS),
  @@ -254,7 +270,7 @@
   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
  +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
   not have a class 'ExampleThree' implemented in "".
  @@ -336,8 +352,8 @@
   "manual/CoreTasks/fixcrlf.html">FixCRLF task</a> is often a useful interim step
   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?
  +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.
  @@ -351,15 +367,19 @@
   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>.
  +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.
   <a name="directories">
   <h2> Directory Structures</h2>
   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.
  +starting points. All the jakarta projects follow a roughly similar
  +style, which makes it easy to navigate around one form one project to
  +another, and easy to clean up when desired. 
   <h3>Simple Project</h3>
  @@ -401,14 +421,25 @@
  -	<td>source goes in under this tree
  +	<td>source goes in under this tree <i>in a heirarchy which matches
  +	the package names<i>. The dependency compilation of javac requires this.  
   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. Javadoc output can be
  +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
  +and so on. Keeping the content in this folder (or sub heirarchy)
  +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
  +appropriate ant task: there is no need to completely model your source tree 
  +upon the deployment heirarchy. 
  +Javadoc output can be
   directed to a doc/ folder beneath build/, or to doc/javadoc.
   <h3>Interface and Implementation split</h3>
  @@ -439,6 +470,14 @@
   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.
  +The only way to retain control over a fairly loosely integrated
  +collection of projects is to have a fully automated  build 
  +and test process which verifies that everything is still compatible. Sam
  +Ruby runs one for all the apache java libraries and emails everyone when
  +something breaks; your own project may be able to make use of 
  +<A href="">Cruise Control</a> for
  +an automated, continuous, background build process. 
   <h3>Integrated sub projects</h3>
  @@ -456,7 +495,7 @@
   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.
  +refactor the project directory structures. 
   <a name="antupdate">
  @@ -505,7 +544,12 @@
   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.
  +pointers to the existing implementation. The final benefit of being
  +involved with the process is that it makes it easier for your tasks to 
  +be added with the ant CVS tree, bringing forward the date when ant has
  +taken on all the changes you needed to make to get your project to work.
  +If that happens you can revert to an official ant release, and get on
  +with all the other crises. 
  @@ -517,7 +561,62 @@
   don't make everyone on the team subscribe; it can be too much of a
  +<a name="install">
  +Installing with Ant.
  +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
  +build wouldn't complete until tomcat exited, which is probably not what
  +was wanted. 
  +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
  +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
  +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.
  +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
  +the war file (with datestamp and buildstamp) to an archive directory,
  +clean up the current deployed version of the war and then install the
  +new version. Because bluestone restarted JVMs on demand, this script was
  +all you needed for web service deployment. On the systems behind the
  +firewall, we upped the ante in the deployment process by using the ftp
  +task to copy out the war and build files, then the telnet task to
  +remotely invoke the build file. The result was we had automated
  +recompile and redeploy to local servers from inside our IDE (Jedit) or
  +the command line, which was simply invalualbe. 
  +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 functionality,
  +ability to spawn executables and all the other trouble spots
  +, the install script could automatically do
  +a system health test during install time and report problems. [The same tests
  +could also be invoked from a JMX MBean, but that's another story]. 
  +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. 
   <a name="tips">
   Tips and Tricks</h2>
  @@ -530,7 +629,7 @@
   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
  @@ -561,7 +660,9 @@
   The <a href="">jikes compiler</a> is usually much
   faster than javac, and does dependency checking. Get it. Then set
  -build.compiler to "jikes" for it to be used in your build files.
  +build.compiler to "jikes" for it to be used in your build files. Better
  +yet, set the JIKES_HOME environment variable for jikes to automatically
  +get used, without changing your build files to only work with jikes.
   #include targets to simplify multi build.xml projects
  @@ -584,8 +685,6 @@
   	&lt;!DOCTYPE project [
   	  &lt;!ENTITY IncludeBuildCore SYSTEM &quot;buildCore.xml&quot;&gt;
   	  &lt;!ENTITY IncludeBuildSecondary SYSTEM &quot;buildSecondary.xml&quot;&gt;
  -	%IncludeBuildCore;
  -	%IncludeBuildSecondary;
   	&lt;target name=&quot;includedBuild&quot;&gt;
  @@ -593,12 +692,27 @@
  -The clean method using XInclude/Xpath will let you include named 
  +The cleaner method using XInclude/Xpath will let you include named 
   targets from one build file or another, using
   <a href=""> 
   the xpointer syntax</a>. You'll need to wait for the W3C proposals
   to finalise and the java XML parsers to implement it before
  -using xpointer references.  
  +using xpointer references.
  +Before you go overboard with using XML inclusion, note that the <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",
  +"cleanup-installation" 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
  +build files call with their own settings. If you can achive this then
  +you are definately making your way up the software maturity ladder. 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 that of the caller, now you just have to remember
to set
  +<tt>inheritall="false"</tt> on all uses of the ant task.   
   Implement complex Ant builds through XSL
  @@ -606,7 +720,8 @@
   XSLT can be used to dynamically generate build.xml files from a source
   xml file, with the <a href="manual/CoreTasks/style.html">Style</a> task controlling
   the transform. This is the current recommended strategy for creating
  -complex build files dynamically.
  +complex build files dynamically. However, its use is still apparently
  +quite rare -which means you will be on the bleeding edge of technology.
  @@ -654,6 +769,33 @@
   because it eliminates the startup time of the JVM, perhaps even some of
   the XML parsing delays. 
  +Use the replace task to programmatic modify text files in your project.  
  +Imagine your project has some source files -BAT files, ASP 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
  +versions customised for that build or destination. Of course, per-destination customisation
  +should be delayed until installation, but if you are using ant for the remote installation
  +that suddenly becomes feasible.     
  +Use the mailing lists
  +There are two 
  +<a href="">mailing lists</a> 
  +related to ant, ant-user and ant-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 
  +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
  +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
  +incorporated into the ant source tree.  
   <a name="puttingtogether">
  @@ -684,7 +826,8 @@
   Debug/release switching can be handled with separate initialisation
   targets called before the compile tasks which define the appropriate
  +properties. Antcall is the trick here, as it allows you to have two paths
  +of property initialisation in a build file.   
   Internal targets should be used to structure the process
  @@ -773,7 +916,7 @@
   <h3>It's not meant to be a nice language for humans</h3>
  -XML isnt a nice representation of information for humans. It's a
  +XML isn't a nice representation of information for humans. It's a
   reasonable representation for programs, and text editors and source code
   management systems can all handle it nicely. But a complex ant file can
   get ugly because XML is a bit ugly, and a complex build is, well,
  @@ -781,7 +924,25 @@
   still makes sense when you get back to it, and use Antidote to edit the
   files if you prefer it. 
  +<h3>You still need all the other foundational bits of a software
  +If you don't have an source code management system, you are going to end
  +up hosed. If you don't have everything under SCM, including web pages,
  +dependent jars, installation files, you are still going to end up hosed,
  +it's just a question of when it's going to happen.
  +CVS is effectively free and works well with ant, but Sourcesafe, Perforce,
  +Clearcase and StarTeam also have ant tasks. These tasks
  +let you have auto-incrementing build counters, and automated file
  +update processes. 
  +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.  
   Software development is meant to be fun. Being in the maelstrom of a
  @@ -809,8 +970,22 @@
   	code you will soon have.
  -<p align="center">Copyright &copy; 2000 Apache Software Foundation. All rights
  +<a name="author">
  +<h3>About the Author</h3>
  +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. Because of those implausible
  +deadlines, email questions related to this document are generally, and
  +regretfully unwelcome, unless they are corrections to the content,
  +advanced discourse on how to evolve software engineering processes to
  +meet the next generation of challenges, or from someone he knows. Even
  +then, a timely response is unlikely. Please use the mailing lists
  +<p align="center">Copyright &copy; 2000, 2001 Apache Software Foundation. All
  \ No newline at end of file

View raw message