ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject cvs commit: jakarta-ant/docs/manual/OptionalTasks ftp.html
Date Tue, 19 Nov 2002 13:28:02 GMT
bodewig     2002/11/19 05:28:02

  Modified:    docs     Tag: ANT_15_BRANCH ant_in_anger.html
               docs/manual Tag: ANT_15_BRANCH cover.html
               docs/manual/CoreTasks Tag: ANT_15_BRANCH get.html
               docs/manual/OptionalTasks Tag: ANT_15_BRANCH ftp.html
  Log:
  Merge Steve's doc patches from HEAD
  
  Revision  Changes    Path
  No                   revision
  
  
  No                   revision
  
  
  1.7.2.2   +332 -188  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.7.2.1
  retrieving revision 1.7.2.2
  diff -u -r1.7.2.1 -r1.7.2.2
  --- ant_in_anger.html	12 Jul 2002 13:59:06 -0000	1.7.2.1
  +++ ant_in_anger.html	19 Nov 2002 13:28:02 -0000	1.7.2.2
  @@ -1,6 +1,6 @@
   <head>
   <title>
  -	Apache Ant in Anger
  +    Ant in Anger
   </title>
   </head>
   
  @@ -8,11 +8,12 @@
   <h1 align="center">Ant in Anger:
   </h1>
   <h2 align="center">
  -	Using Apache Ant in a Production Development System
  +        Using Apache Ant in a Production Development System
   </h2>
   
   <h4  align="center">
  -Steve Loughran
  +Steve Loughran<br>
  +Last updated 2002-11-09
   </h4>
   
   <a name="introduction">
  @@ -25,8 +26,8 @@
   be yet another source of problems in that ongoing crises we call
   development . This
   document contains some strategies and tactics for making the most of
  -ant. It is moderately frivolous in places, and lacks almost any actual
  -examples of ant xml. The lack of examples is entirely deliberate -it
  +Ant. It is moderately frivolous in places, and lacks almost any actual
  +examples of Ant xml. The lack of examples is entirely deliberate -it
   keeps document maintenance costs down. Most of the concepts covered
   don't need the detail about XML representations, as it is processes we
   are concerned about, not syntax. Finally, please be aware that the
  @@ -36,7 +37,7 @@
   
   <p>
   Firstly, here are some assumptions about the projects which this
  -document covers
  +document covers:
   <ul>
   <li> Pretty much pure Java, maybe with some legacy cruft on the edges.
   
  @@ -63,7 +64,7 @@
   What that all means is that there is no time to spend getting things
   right, you don't have that tight control on how the rest of the team
   works and the development process is often more one of chaos minimisation
  -than anything else. The role of ant in such projects is to ensure that
  +than anything else. The role of Ant in such projects is to ensure that
   the build, test and deploy processes run smoothly, leaving you with all
   the other problems.
   
  @@ -71,25 +72,28 @@
   <h2>Core Practices</h2>
   </a>
   <h3>
  -Clarify what you want ant to do</h3>
  +Clarify what you want Ant to do</h3>
   
   
   Ant is not a silver bullet. It is just another rusty bullet in the armory of
   development tools available at your disposal. Its primary purpose is to
   accelerate the construction and deployment of Java projects. You could certainly
  -extend ant to do anything Java makes possible -it is easy to imagine writing an
  +extend Ant to do anything Java makes possible: it is easy to imagine writing an
   image processing task to help in web site deployment by shrinking and
   recompressing jpeg files, for example. But that would be pushing the boundary of
  -what ant is really intended to do -so should be considered with care.
  +what Ant is really intended to do -so should be considered with care.
   
   <P>
   
  -Ant is also a great adjunct to an IDE -a way of doing all the housekeeping of
  +Ant is also a great adjunct to an IDE; a way of doing all the housekeeping of
   deployment and for clean, automated builds. But a good modern IDE is a
   productivity tool in its own right -one you should consider keeping using. Ant
   just lets you give the teams somewhat more freedom in IDE choice -&quot;you can
  -use whatever you want in development, but ant for the deployment
  -builds&quot;
  +use whatever you want in development, but Ant for the deployment
  +builds&quot; Now that many modern open source and commercial IDEs
  +include Ant support (including jEdit, Forte, Eclipse and IDEA),
  +developers can use a great IDE, with Ant providing a rigorous and portable 
  +build process integrated into the tool. 
   
   <h3>
   Define standard targets
  @@ -104,9 +108,9 @@
   
   <P>
   
  -With standard target names, it is easy to build encompassing ant build
  +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>
  +<a href="manual/CoreTasks/ant.html">&lt;ant&gt;</a>
   task. For example. the clean target could be handed down to the <tt>intf</tt> and
   <tt>impl</tt> subdirectories from a parent directory
   
  @@ -114,11 +118,11 @@
   &lt;/target&gt;
   
   &lt;target name=&quot;clean-intf&quot; &gt;
  -	&lt;ant dir=&quot;intf&quot; target=&quot;clean&quot; /&gt;
  +    &lt;ant dir=&quot;intf&quot; target=&quot;clean&quot; /&gt;
   &lt;/target&gt;
   
   &lt;target name=&quot;clean-impl&quot;&gt;
  -	&lt;ant dir=&quot;impl&quot; target=&quot;clean&quot; /&gt;
  +    &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
  @@ -127,30 +131,39 @@
   entry points is therefore very useful, even before a project becomes big and complicated.
     
   <h3>
  -	Extend ant through new tasks
  +    Extend Ant through new tasks
   </h3>
   
  -If ant does not do what you want, you can use the
  +If Ant does not do what you want, you can use the
   <a href="manual/CoreTasks/exec.html">exec</a> and
   <a href="manual/CoreTasks/java.html">java</a> tasks or
   <a href="manual/OptionalTasks/script.html">inline scripting</a> to extend it. In a
   project with many build.xml files, you soon find that having a single
   central place for implementing the functionality keeps maintenance
  -overhead down. Implementing task extensions through java code seems
  +overhead down. Implementing task extensions through Java code seems
   extra effort at first, but gives extra benefits:-
   
  - <ul>
  +<ul>
   
   <li>Cross platform support can be added later without changing any
   build.xml files</li>
   
  -<li>The code can be submitted to the ant project itself, for other
  +<li>The code can be submitted to the Ant project itself, for other
   people to use and maintain</li>
   
   <li>It keeps the build files simpler</li>
   
   </ul>
   
  +In a way, it is it this decoupling of functionality, "the tasks", from
  +the declaration of use, "the build file", that has helped Ant succeed.
  +If you have to get something complex done in Make or an IDE, you have a
  +hairy makefile that everyone is scared of, or an IDE configuration that
  +is invariably very brittle. But an Ant task is reusable and shareable
  +among all Ant users. Many of the core and optional tasks in Ant today,
  +tasks you do or will come to depend on, were written by people trying to
  +solve their own pressing problems. 
  +
   <h3>
   Embrace Automated Testing
   </h3>
  @@ -158,23 +171,27 @@
   <b>(alternatively "recriminate early, recriminate often")</b>
   <p>
   
  -Ant lets you call <a href="manual/OptionalTasks/junit.html">JUnit</a> tasks, which unit test
  -the code your team has written. Automated testing may seem like extra
  -work at first, but JUnit makes writing unit tests so 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.
  +Ant lets you call <a href="manual/OptionalTasks/junit.html">JUnit</a>
  +tasks, which unit test the code your team has written. Automated testing
  +may seem like extra work at first, but JUnit makes writing unit tests so
  +easy that you have almost no reason not to. Invest the time in learning
  +how to use JUnit, write the test cases, and integrate them in a 'test'
  +target from Ant so that your daily or hourly team build can have the
  +tests applied automatically. One of the free to download chapters of
  +<a href="http://manning.com/antbook/">Java Development with Ant</a>
  +shows you how to use JUnit from inside Ant.  
   
   <p>
   
  -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.
  +
  +Once you add a way to fetch code from the SCM system, either as an Ant
  +task, in some shell script or batch file or via some continuous
  +integration tool. the integration test code can be a pure Ant task run
  +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.
   
   <p>
   
  @@ -192,6 +209,43 @@
   you for shipping software that works.   
   
   
  +<h3>Learn to Use and love the add-ons to Ant</h3>
  +The Ant distribution is not the limit of the Ant universe, it is only
  +the beginning. Look at the 
  +<A href="http://jakarta.apache.org/ant/external.html">
  +External Tools and Tasks page
  +</A> for an up to date list. Here are some of them that .
  +
  +<ul>
  +<li>
  +<a hef="http://checkstyle.sourceforge.net/">Checkstyle</a><br>
  +This tool audits your code and generates HTML reports of wherever any
  +style rule gets broken. Nobody can hide from the code police now! tip:
  +start using this early, so the corrections are less.
  +<li>
  +<A href="http://ant-contrib.sf.net/">Ant-contrib</A><br>
  +This sourceforge project contains helper tasks that are kept separate
  +from core Ant for ideological purity; the foreach and trycatch tasks in
  +particular. These give you iteration and extra error handling. Also on
  +the site is the &lt;cc&gt; task suite, that compile and link native code
  +on a variety of platforms.
  +
  +<li>
  +<a href="http://xdoclet.sourceforge.net/">XDoclet</a>
  +
  +XDoclet adds attributed oriented programming to Java. By adding javadoc
  +tags to your code you can have XDoclet automatically generate web.xml
  +descriptors, taglib descriptors, EJB interfaces, JMX interface classes,
  +Castor XML/SQL bindings, and many more. The key here is that all those
  +fiddly little XML files you need to create, and those interfaces EJB and
  +JMX requires to to implement, all can be autogenerated from your Java
  +code with a few helper attributes. This reduces
  +errors and means you can change your code and have the rest of the app
  +take its cue from the source. Never do EJB, JMX or webapps without it!
  +
  +</ul>
  +
  +
   <a name="crossplatform">
   <h2>
   Cross Platform Ant
  @@ -205,12 +259,12 @@
   
   <p>
   
  -The common barriers to cross-platform ant are the use of command line
  +The common barriers to cross-platform Ant are the use of command line
   tools (exec tasks) which are not portable, path issues, and hard coding
   in the location of things.
   
  -<h3>Command Line apps: <a href="manual/CoreTasks/exec.html">Exec</a>/ <a href=
  -"manual/CoreTasks/apply.html">Apply</a></h3>
  +<h3>Command Line apps: <a href="manual/CoreTasks/exec.html">Exec</a>/
  + <a href= "manual/CoreTasks/apply.html">Apply</a></h3>
   
   The trouble with external invocation is that not all functions are found
   cross platform, and those that are often have different names -DOS
  @@ -225,7 +279,7 @@
   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
  +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.
   
   <h3>Cross platform paths</h3>
  @@ -248,7 +302,7 @@
   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
  +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
  @@ -297,7 +351,11 @@
   ActiveState</a>. 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.
  +perl code can be left to resolve its own platform issues. Dont forget to
  +set the line endings of the file to the appropriate platform when you
  +redistribute Perl code; <a
  +href="manual/CoreTasks/fixcrlf.html">&lt;fixCRLF&gt;</a> 
  +can do that for you.
   
   <a name="team">
   <h2>Team Development Processes</h2>
  @@ -319,7 +377,7 @@
   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
  +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.
   
  @@ -328,21 +386,22 @@
   <h2>Deploying with Ant</h2>
   </a>
   
  -One big difference between ant and older tools such as make is that the
  -processes for deploying java to remote sites are reasonably well
  -evolved in ant. That is because we all have to do it these days, so
  +One big difference between Ant and older tools such as Make is that the
  +processes for deploying Java to remote sites are reasonably well
  +evolved in Ant. That is because we all have to do it these days, so
   many people have put in the effort to make the tasks easier.
   <p>
   
  -Ant can <a href="manual/CoreTasks/jar.html">Jar</a>, <a href= "manual/CoreTasks/tar.html">
  -Tar</a> or <a href="manual/CoreTasks/zip.html">Zip</a> files for deployment, while
  -the <a href="manual/CoreTasks/war.html">War</a> task extends the jar task for
  -better servlet deployment. <a href = "jlink.html" >Jlink</a> is a jar
  -generation file which lets you merge multiple sub jars. This is ideal
  -for a build process in which separate jars are generated by sub
  +Ant can <a href="manual/CoreTasks/jar.html">Jar</a>, <a href=
  +"manual/CoreTasks/tar.html"> Tar</a> or <a
  +href="manual/CoreTasks/zip.html">Zip</a> files for deployment, while the
  +<a href="manual/CoreTasks/war.html">War</a> task extends the jar task
  +for better servlet deployment. <a href = "jlink.html" >Jlink</a> is a
  +jar generation file which lets you merge multiple sub jars. This is
  +ideal for a build process in which separate jars are generated by sub
   projects, yet the final output is a merged jar. <a href=
  -"manual/OptionalTasks/cab.html">Cab</a> can be used on Win32 boxes to build a cab file
  -which is useful if you have to target IE deployment.
  +"manual/OptionalTasks/cab.html">Cab</a> can be used on Win32 boxes to
  +build a cab file which is useful if you still have to target IE deployment.
   
   <p>
   
  @@ -350,17 +409,24 @@
   server. Beware of putting the ftp password in the build file -a property
   file with tight access control is slightly better. The <a href=
   "manual/CoreTasks/fixcrlf.html">FixCRLF task</a> is often a useful interim step if
  -you need to ensure that files have unix file extensions before upload. A
  +you need to ensure that files have Unix file extensions before upload. A
   WebDav task has long been discussed, which would provide a more secure
   upload to web servers, but it is still in the todo list. Rumour has it
  -that there is such a task in the jakarta-slide libraries.
  +that there is such a task in the jakarta-slide libraries. With MacOS X,
  +Linux and Windows XP all supporting WebDAV file systems, you may even be able
  +to use <a href="manual/CoreTasks/copy.html">&lt;copy&gt;</a> to deploy
  +though a firewall. 
   
   <p>
   
  -EJB deployment is aided by the <a href="manual/OptionalTasks/ejb.html">ejb tasks</a>. 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.
  +EJB deployment is aided by the <a href="manual/OptionalTasks/ejb.html">ejb tasks</a>,
  +while the 
  +<a
  +href="manual/OptionalTasks/serverdeploy.html">&lt;serverdeploy&gt;</a>
  +suite can deploy to multiple servers. The popularity of Ant has
  +encouraged vendors to produce their own deployment tasks which they
  +redistribute with their servers. For example, the Tomcat4.1 installation
  +includes tasks to deploy, undeploy and reload web applications.
   
   <p>
   
  @@ -369,8 +435,13 @@
   "index.html#copydir">Copydir</a> , or just sending them to a person or
   process using <a href= "manual/CoreTasks/mail.html">Mail</a> or the attachment
   aware <a href= "manual/OptionalTasks/mimemail.html">MimeMail</a>.
  -In one project our team even used ant to build CD images through a build followed
  -by a long set of Copy tasks, which worked surprisingly well.
  +In one project our team even used Ant to build CD images through a build followed
  +by a long set of Copy tasks, which worked surprisingly well, certainly
  +easier than when we mailed them to the free email service on
  +myrealbox.com, then pulled them down from the far end's web browser, which we
  +were running over WinNT remote desktop connection, that being tunneled
  +through SSH.
  +
   <a name="directories">
   <h2> Directory Structures</h2>
   </a>
  @@ -386,44 +457,44 @@
   The project contains sub directories
   <table width="100%">
   <tr>
  -	<td><b>bin</b>
  -	</td>
  -	<td>common binaries, scripts -put this on the path.
  -	</td>
  +    <td><b>bin</b>
  +    </td>
  +    <td>common binaries, scripts -put this on the path.
  +    </td>
   </tr>
   
   <tr>
  -	<td><b>build</b>
  -	</td>
  -	<td>This is the tree for building; ant creates it and can empty it
  -	in the 'clean' project.
  -	</td>
  +    <td><b>build</b>
  +    </td>
  +    <td>This is the tree for building; Ant creates it and can empty it
  +    in the 'clean' project.
  +    </td>
   </tr>
   <tr>
  -	<td><b>dist</b>
  -	</td>
  -	<td>Distribution outputs go in here; the directory is created in ant
  -	and clean empties it out
  -	</td>
  +    <td><b>dist</b>
  +    </td>
  +    <td>Distribution outputs go in here; the directory is created in Ant
  +    and clean empties it out
  +    </td>
   </tr>
   <tr>
  -	<td><b>doc</b>
  -	</td>
  -	<td>Hand crafted documentation
  -	</td>
  +    <td><b>doc</b>
  +    </td>
  +    <td>Hand crafted documentation
  +    </td>
   </tr>
   <tr>
  -	<td><b>lib</b>
  -	</td>
  -	<td>Imported Java libraries go in to this directory
  -	</td>
  +    <td><b>lib</b>
  +    </td>
  +    <td>Imported Java libraries go in to this directory
  +    </td>
   </tr>
   <tr>
  -	<td><b>src</b>
  -	</td>
  -	<td>source goes in under this tree <i>in a heirarchy which matches
  -	the package names<i>. The dependency compilation of javac requires this.  
  -	</td>
  +    <td><b>src</b>
  +    </td>
  +    <td>source goes in under this tree <i>in a heirarchy which matches
  +    the package names<i>. The dependency rules of &lt;javac&gt; requires this.  
  +    </td>
   </tr>
   </table>
   
  @@ -435,7 +506,7 @@
   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 
  +appropriate Ant task: there is no need to completely model your source tree 
   upon the deployment heirarchy. 
   <p> 
   
  @@ -499,17 +570,17 @@
   
   <a name="antupdate">
   <h2>
  -	Ant Update Policies
  +    Ant Update Policies
   </h2>
   </a>
   
  -Once you start using ant, you should have a policy on when and how the
  +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
  +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.
  +the new tasks and features that Ant is constantly adding.
   
   <p>
   
  @@ -532,8 +603,8 @@
   
   <p>
   
  -Once you start extending ant with new tasks, it suddenly becomes much
  -more tempting to pull down regular builds. The most recent ant builds
  +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
  @@ -546,9 +617,9 @@
   and discovering that instead of adulation all you get are helpful
   pointers to the existing implementation. The final benefit of being
   involved with the process is that it makes it easier for your tasks to 
  -be added with the ant CVS tree, bringing forward the date when ant has
  +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
  +If that happens you can revert to an official Ant release, and get on
   with all the other crises. 
   
   <p>
  @@ -567,7 +638,7 @@
   </h2>
   </a>
   
  -Because ant can read environment variables, copy, unzip and delete files
  +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
  @@ -577,20 +648,20 @@
   
   <p>
   
  -The advantage of using ant is firstly that the same install targets
  +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
  +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
  +being in use to jar versions being different. This means that Ant is not
   suited for shrink wrapped software, but it does work for deployment and
   installation to your local servers.
   
   <p>
   
  -One major build project I was involved in had an ant install build file
  +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,
  @@ -601,32 +672,37 @@
   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. 
  +the command line, which was simply invaluable. Imagine pressing a button
  +on your IDE toolbar to build, unit test, deploy and then functional test
  +your webapp. 
   
   <p>
   
  -One extra trick I added later was a junit test case to run through 
  -the install check list. With tests to verify access permissions on network
  -drives, approximate clock synchronisation between servers, DNS 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]. 
  +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]. 
  +
   <p>
   
  -So, ant is not a substitute for a real installer tool, except in the
  +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">
   <h2>
   Tips and Tricks</h2>
   </a>
   <dl>
   <dt><b>
  -	get
  +    get
   </b><dd>
   
  -The <a href="manual/CoreTasks/get.html">get</a> task can fetch any URL, so be used
  +The <a href="manual/CoreTasks/get.html">&lt;get&gt;</a> task can fetch any URL, so be used
   to trigger remote server side code during the build process, from remote
   server restarts to sending SMS/pager messages to the developer
   cellphones.
  @@ -678,7 +754,7 @@
   This lets a multi-project development program share code through reference,
   rather than cut and paste re-use. It also lets one build up a file of
   standard tasks which can be reused over time. Because the import
  -mechanism is at a level below which ant is aware, treat it as
  +mechanism is at a level below which Ant is aware, treat it as
   equivalent to the #include mechanism of the 'legacy' languages C and
   C++.
   
  @@ -688,15 +764,13 @@
   clean one. For now, the ugly
   method is the most portable:-
   <pre>
  -	&lt;!DOCTYPE project [
  -	  &lt;!ENTITY IncludeBuildCore SYSTEM &quot;buildCore.xml&quot;&gt;
  -	  &lt;!ENTITY IncludeBuildSecondary SYSTEM &quot;buildSecondary.xml&quot;&gt;
  -	]&gt;  
  -	
  -	&lt;target name=&quot;includedBuild&quot;&gt;
  -		&amp;IncludeBuildCore;
  -		&amp;IncludeBuildSecondary;
  -	&lt;/target&gt;
  +    &lt;!DOCTYPE project [
  +      &lt;!ENTITY propertiesAndPaths SYSTEM &quot;propertiesAndPaths.xml&quot;&gt;
  +      &lt;!ENTITY taskdefs SYSTEM &quot;taskdefs.xml&quot;&gt;
  +    ]&gt;  
  +    
  +        &amp;propertiesAndPaths;
  +        &amp;taskdefs;
   </pre>
   The cleaner method using XInclude/Xpath will let you include named 
   targets from one build file or another, using
  @@ -704,27 +778,40 @@
   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.
  +
   <p>
  -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", "email-to-team", 
  -"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
  +
  +Before you go overboard with using XML inclusion, note that the
  +<tt>&lt;ant&gt;</tt> task lets you call any target in any other build
  +file -with all your property settings propagating down to that target.
  +So you can actually have a suite of utility targets
  +-"deploy-to-stack-a", "email-to-team", "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.   
  +you are definately making your way up the software maturity ladder. With
  +a bit of work you may progress from being a SEI CMM Level 0 organisation
  +"Individual Heroics are not enough" to SEI CMM Level 1, "Projects only
  +succeed due to individual heroics"
   
  -	
  +<p>
  +
  +NB, <tt>&lt;ant&gt;</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 &lt;ant&gt; task.
  +
  +    
   <dt><b>
   Implement complex Ant builds through XSL
   </b><dd>
   
   XSLT can be used to dynamically generate build.xml files from a source
  -xml file, with the <a href="manual/CoreTasks/style.html">Style</a> task controlling
  +xml file, with the <a href="manual/CoreTasks/style.html">&lt;xslt&gt;</a> task controlling
   the transform. This is the current recommended strategy for creating
   complex build files dynamically. However, its use is still apparently
   quite rare -which means you will be on the bleeding edge of technology.
  @@ -735,7 +822,7 @@
   </b><dd>
   
   By writing your own invocation script -using the DOS, Unix or Perl
  -script as a starting point- you can modify a ant behavior for an
  +script as a starting point- you can modify Ant's settings and behavior for an
   individual project. For example, you can use an alternate variable to
   ANT_HOME as the base, extend the classpath differently, or dynamically
   create a new command line property 'project.interfaces' from all .jar
  @@ -744,13 +831,13 @@
   <p>
   
   Having a custom invocation script which runs off a CVS controlled
  -library tree under PROJECT_HOME also lets you control ant versions
  -across the team -developers can have other copies of ant if they want,
  +library tree under 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.
   
   <p>
   
  -You can also write wrapper scripts which invoke the existing ant
  +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
  @@ -764,53 +851,67 @@
   
   This seems a bit strange and idealistic, but what it means is that you should
   write all your java code as if it may be called as a library at some point in
  -future. So do not place calls to <b>System.exit()</b> deep in the code -if you
  +future. So do not place calls to <tt>System.exit()</tt> deep in the code -if you
   want to exit a few functions in, raise an exception instead and have
  -<b>main()</b> deal with it.
  +<tt>main()</tt> deal with it.
   
  -<dt><b>
  +<p>
  +
  +Moving one step further, consider proving an Ant Task interface to the
  +code as a secondary, primary or even sole interface to the
  +functionality. Ant actually makes a great bootloader for Java apps as it
  +handles classpath setup, and you can re-use all the built in tasks for
  +preamble and postamble work. Some projects, such as 
  +<a href="http://xdoclet.sf.net">XDoclet</a> only run under Ant, because
  +that is the right place to be.
  +
  +
  +
  +<!-- <dt><b>
   Use Antidote as the invocation tool
   </b><dd>
  -Even if you edit ant files by hand, Antidote makes a good execution tool
  +Even if you edit Ant files by hand, Antidote makes a good execution tool
   because it eliminates the startup time of the JVM, perhaps even some of
   the XML parsing delays. 
  -
  + -->
   <dt><b>
   Use the replace task to programmatic modify text files in your project.  
   </b><dd>
  -Imagine your project has some source files -BAT files, ASP pages (!), anything
  +Imagine your project has some source files -BAT files, ASPX pages (!), anything
   which needs to be statically customised at compile time for particular
   installations, such driven from some properties of the project such as JVM options, or the URL
   to direct errors too. The replace task can be used to modify files, substituting text and creating
   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
  +should be delayed until installation, but if you are using Ant for the remote installation
   that suddenly becomes feasible.     
   
  +
  +
   <dt><b>
   Use the mailing lists
   </b><dd>
   There are two 
   <a href="http://jakarta.apache.org/site/mail.html">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
  +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
  +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
  +"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.  
  +incorporated into the Ant source tree.  
      
   </dl>
   
   <a name="puttingtogether">
  -	<h2>
  -		Putting it all together
  -	</h2>
  +    <h2>
  +        Putting it all together
  +    </h2>
   </a>
   
  -What does an ant build process look like in this world? Assuming a
  +What does an Ant build process look like in this world? Assuming a
   single directory structure for simplicity, the build file
   should contain a number of top level targets
   <ul>
  @@ -840,27 +941,53 @@
   <ul>
   <li> init - initialise properties, extra-tasks, read in per-user
   property files.
  -<li> init-debug - initialise debug properties
   <li> init-release - initialise release properties
   <li> compile - do the actual compilation
   <li> link/jar - make the jars or equivalent
   <li> staging - any pre-deployment process in which the output is dropped
  -	off then tested before being moved to the production site.
  +    off then tested before being moved to the production site.
   </ul>
   
  -The switching between debug and release can be done using the 'if' and
  -'unless' conditional flags on the targets, so that debug gets called
  -unless 'project.mode.release' is defined.
  +The switching between debug and release can be done by making
  +init-release conditional on a property, such as <tt>release.build</tt> 
  +being set :-
  +
  +<pre>&lt;target name=&quot;init-release&quot; if=&quot;release.build&quot;&gt;
  +    &lt;property name=&quot;build.debuglevel&quot; value=&quot;lines,source&quot;/&gt;    
  +  &lt;/target&gt;
  +</pre>
  +
  +You then have dependent targets, such as "compile", depend on this
  +conditional target; there the 'default' properties are set, and then the
  +property is actually used. Because Ant properties are <i>immutable</i>,
  +if the release target was executed its settings will override the
  +default values:
  +
  +<pre>&lt;target name=&quot;compile&quot; depends=&quot;init,init-release&quot;&gt;
  +    &lt;property name=&quot;build.debuglevel&quot; value=&quot;lines,vars,source&quot;/&gt; 
  +    &lt;echo&gt;debug level=${build.debuglevel}&lt;/echo&gt;
  +    &lt;javac destdir=&quot;${build.classes.dir}&quot;
  +       debug=&quot;true&quot;
  +       debuglevel=&quot;${build.debuglevel}&quot;
  +       includeAntRuntime=&quot;false&quot;
  +       srcdir=&quot;src&quot;&gt;
  +      &lt;classpath refid=&quot;compile.classpath&quot;/&gt;
  +    &lt;/javac&gt;
  +  &lt;/target&gt;
  +</pre>
   
  +As a result, we now have a build where the release mode only includes
  +the filename and line debug information (useful for bug reports), while
  +the development system included variables too. 
   <p>
   
   It is useful to define a project name property which can be echoed in
  -the init task. This lets you work out which ant file is breaking in a
  +the init task. This lets you work out which Ant file is breaking in a
   multi file build.
   
   <p>
   
  -What goes in to the internal ant tasks depends on your own projects. One
  +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
  @@ -869,7 +996,7 @@
   
   <p>
   
  -Once you have set up the directory structures, and defined the ant tasks
  +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.
  @@ -888,7 +1015,7 @@
   
   <h2>The Limits of Ant</h2>
   
  -Before you start adopting ant as the sole mechanism for the build
  +Before you start adopting Ant as the sole mechanism for the build
   process, you need to be aware of what it doesn't do.
   <p>
   
  @@ -905,15 +1032,15 @@
   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
  +tests and then build the appropriate Ant task. XSLT can be used for
   this.
   
   <h3>It's not Make</h3>
   
   Some of the features of make, specifically inference rules and
  -dependency checking are not included in ant. That's because they are
  +dependency checking are not included in Ant. That's because they are
   'different' ways of doing a build. Make requires you to state
  -dependencies and the build steps, ant wants you to state tasks and the
  +dependencies and the build steps, Ant wants you to state tasks and the
   order between them, the tasks themselves can do depedency checking or
   not. A full java build using Jikes is so fast that dependency checking
   is relatively moot, while many of the other tasks (but not all), compare
  @@ -924,7 +1051,7 @@
   
   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
  +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,
   complicated. Use XML comments so that the file you wrote last month
   still makes sense when you get back to it, and use Antidote to edit the
  @@ -946,7 +1073,7 @@
   and generally oversee the sub projects build processes. On a small project,
   you don't need to do that -but remember: small projects become big projects
   when you aren't looking. If you start off with a little bit of process, then
  -you can scale it if needed. Ff you start with none, by the time you need 
  +you can scale it if needed. If you start with none, by the time you need 
   it it will be too late.   
   
   <h3>You still need all the other foundational bits of a software
  @@ -956,8 +1083,8 @@
   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
  +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. 
   
  @@ -965,7 +1092,7 @@
   
   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
  +this, using Ant and a continuous test process enables a rapid evolution of code
   to adapt to those changes which are inevitable.  
   
   <h2>Endpiece</h2>
  @@ -987,13 +1114,25 @@
   <li>
   <a
   href="http://www.martinfowler.com/articles/continuousIntegration.html">
  -Continuous Integration</a>; Martin Fowler. <br>
  -A paper on using ant within a software project
  +<i>Continuous Integration</i></a>; Martin Fowler. <br>
  +A paper on using Ant within a software project
   running a continuous integration/testing proces.
  -<li> Refactoring; Martin Fowler, ISBN: 0201485672 <br>
  -	Covers JUnit as well as tactics for making some headway with the mess of
  -	code you will soon have.
  -
  +<li><i> Refactoring</i>; Martin Fowler, ISBN: 0201485672 <br>
  +    Covers JUnit as well as tactics for making some headway with the mess of
  +    code you will soon have.
  +
  +<li><a href="http://manning.com/antbook/"><i>Java Development with
  +Ant</i></a>;
  +    Erik Hatcher and Steve Loughran. <br>
  +    Arguably the only book on Ant worth owning; 
  +    certainly it's the only one written by Ant developers.
  +    
  +<li>
  +<a href="http://www.iseran.com/Steve/papers/when_web_services_go_bad.html">
  +    <i>When Web Services Go Bad</i></a>; Steve Loughran.<br>
  +    One of the projects this paper is based on.    
  +    
  +    
   </ul>
   
   <a name="author">
  @@ -1002,13 +1141,18 @@
   
   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
  -instead. 
  +implausible deadlines for the fun of it. He is also a committer on
  +Apache Ant and Apache Axis, and co-author of 
  +<a href="http://manning.com/antbook/"><i>Java Development with Ant</i></a>. 
  +He thinks that if you liked this document you'll love that book because
  +it doesn't just explain Ant, it goes into processes, deployment and best practices
  +and other corners of stuff that really make Ant useful. (It would 
  +have been easier to just rehash the manual, but that wouldn't have been
  +so useful or as much fun).  
  +
  +<p>
  +
  +For questions related to this document, use the Ant mailing list.
   
   <hr>
   <p align="center">Copyright &copy; 2000-2002 Apache Software Foundation. All rights
  
  
  
  No                   revision
  
  
  No                   revision
  
  
  1.3.2.3   +1 -1      jakarta-ant/docs/manual/cover.html
  
  Index: cover.html
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/docs/manual/cover.html,v
  retrieving revision 1.3.2.2
  retrieving revision 1.3.2.3
  diff -u -r1.3.2.2 -r1.3.2.3
  --- cover.html	2 Oct 2002 14:48:48 -0000	1.3.2.2
  +++ cover.html	19 Nov 2002 13:28:02 -0000	1.3.2.3
  @@ -2,7 +2,7 @@
   
   <head>
   <meta http-equiv="Content-Language" content="en-us">
  -<title>Apache Ant 1.5.1 User Manual - Credits</title>
  +<title>Apache Ant 1.5.1 User Manual</title>
   </head>
   
   <body bgcolor="#FFFFFF">
  
  
  
  No                   revision
  
  
  No                   revision
  
  
  1.7.2.3   +4 -0      jakarta-ant/docs/manual/CoreTasks/get.html
  
  Index: get.html
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/docs/manual/CoreTasks/get.html,v
  retrieving revision 1.7.2.2
  retrieving revision 1.7.2.3
  diff -u -r1.7.2.2 -r1.7.2.3
  --- get.html	4 Sep 2002 11:21:12 -0000	1.7.2.2
  +++ get.html	19 Nov 2002 13:28:02 -0000	1.7.2.3
  @@ -29,6 +29,10 @@
   A username and password can be specified, in which case basic 'slightly encoded
   plain text' authentication is used. This is only a secure authentication
   mechanism over an HTTPS link.
  +<p>
  +If you need to go through a firewall, use
  +<a href="../OptionalTasks/setproxy.html">&lt;setproxy&gt;</a>
  +to set up the proxy first. 
   </p>
    
   <h3>Parameters</h3>
  
  
  
  No                   revision
  
  
  No                   revision
  
  
  1.10.2.3  +4 -0      jakarta-ant/docs/manual/OptionalTasks/ftp.html
  
  Index: ftp.html
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/docs/manual/OptionalTasks/ftp.html,v
  retrieving revision 1.10.2.2
  retrieving revision 1.10.2.3
  diff -u -r1.10.2.2 -r1.10.2.3
  --- ftp.html	4 Sep 2002 11:21:14 -0000	1.10.2.2
  +++ ftp.html	19 Nov 2002 13:28:02 -0000	1.10.2.3
  @@ -24,6 +24,10 @@
   tasks</a>, on how the inclusion/exclusion of files works, and how to
   write patterns.</p>
   <p>
  +This task does not currently use the proxy information set by the
  +<a href="setproxy.html">&lt;setproxy&gt;</a> task, and cannot go through
  +a firewall via socks. 
  +<p>
   <b>Warning: </b> for the get and delete actions to work properly 
   with a Windows 2000 ftp server, it needs to be configured to generate
   Unix style listings, and not the default MS-DOS listing. Or someone needs to write
  
  
  

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message