ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ste...@apache.org
Subject cvs commit: jakarta-ant/docs ant_task_guidelines.html
Date Sun, 14 Oct 2001 04:23:29 GMT
stevel      01/10/13 21:23:29

  Modified:    docs     ant_task_guidelines.html
  Log:
  Revisiting of these. Some proofing; more on Java1.1 to 1.4 compatibility needs.
  
  Revision  Changes    Path
  1.3       +81 -21    jakarta-ant/docs/ant_task_guidelines.html
  
  Index: ant_task_guidelines.html
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/docs/ant_task_guidelines.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- ant_task_guidelines.html	2001/04/06 08:35:27	1.2
  +++ ant_task_guidelines.html	2001/10/14 04:23:29	1.3
  @@ -7,7 +7,7 @@
   <h1>Ant Task Design Guidelines</h1>
   
   This document covers how to write ant tasks to a standard required to be
  -incorporated into the ant distribution. You may find it useful when
  +incorporated into the Ant distribution. You may find it useful when
   writing tasks for personal use as the issues it addresses are still
   there in such a case.
   
  @@ -22,14 +22,17 @@
   <h4>Execute</h4>
   
   Execute will spawn off separate programs under all the platforms which
  -ant supports, dealing with java version sublties as well as platform
  +ant supports, dealing with Java version issues as well as platform
   issues. Always use this task to invoke other programs. 
   
   <h4>Java, ExecuteJava</h4>
   
  -These classes can be used to spawn java programs in a separate VM (they
  +These classes can be used to spawn Java programs in a separate VM (they
   use execute) or in the same VM -with or without a different classloader. 
  +When deriving tasks from this, it often benefits users to permit the 
  +classpath to be specified, and for forking to be an optional attribute.
   
  +
   <h4>Project</h4>
   
   Project has some helper functions to touch a file, to
  @@ -61,21 +64,41 @@
   
   <p>
   
  -One controversial rule is 'no tabs'. Use four spaces instead. Not two,
  +One important rule is 'no tabs'. Use four spaces instead. Not two,
   not eight, four. Even if your editor is configured to have a tab of four
   spaces, lots of others aren't -spaces have more consistency across
   editors and platforms.
   
   <h2>Recommended Names for attributes and elements</h2>
  -
  -The ant1.x tasks are fairly inconsistent regarding naming of attributes
  --some tasks use source, others src. Here is a list of what is likely to
  -be the preferred attribute names for ant 2.0. 
   
  -<i>TODO: list attribute/element names which should be standardised, and meaning</i>
  +The ant1.x tasks are very inconsistent regarding naming of attributes
  +-some tasks use source, others src. Here is a list of preferred attribute
  +names. 
  +
  +<table>
  +<tr>
  +<td>
  +    failonerror
  +</td>
  +<td>
  +    boolean to control whether failure to execute should throw a 
  +    <tt>BuildException</tt> or just print an error.
  +    Parameter validation failures should always throw an error, regardless
  +    of this flag
  +</td>
  +</tr>
  +<tr>
  +<td>
  +    destdir
  +</td>
  +<td>
  +    destination directory for output
  +</td>
  +</tr>
  +</table>
  +Yes, this is a very short list. Try and be vaguely consistent with the core
  +tasks, at the very least.
   
  -failonerror, source, dest...
  -
   <h2>Design for controlled re-use</h2>
   
   Keep member variables private. If read access by subclasses is required.
  @@ -85,8 +108,37 @@
   <p>
   
   The other common re-use mechanism in ant is for one task to create and
  -configure another. This is fairly simple. (TODO: example)
  +configure another. This is fairly simple. 
  +
  +<h2>Support Java 1.1 through Java 1.4</h2>
   
  +Ant is designed to support Java1.1: to build on it, to run on it. Sometimes
  +functionality of tasks have to degrade in that environment -&lt;touch&gt;
  +is a case in point- this is usually due to library limitations; 
  +such behaviour change must always be noted in the documentation.
  +<p>
  +What is problematic is code which is dependent on Java1.2 features
  +-Collections, Reader and Writer classes, extra methods in older classes.
  +These can not be used directly by any code and still be able to compile
  +and run on a Java 1.1 system. So please stick to the older collection
  +classes, and the older IO classes. If a new method in an existing class
  +is to be used, it must be used via reflection and the 
  +<tt>NoSuchMethodException</tt> handled somehow. 
  +<p>
  +What if code simply does not work on Java1.1? It can happen. It will 
  +probably be OK to have the task as an optional task, with compilation 
  +restricted to Java1.2 or later through build.xml modifications. 
  +Better still, use reflection to link to the classes at run time.
  +<p>
  +Java 1.4 adds a new optional change to the language itself, the 
  +<tt>assert</tt> keyword, which is only enabled if the compiler is told
  +to compile 1.4 version source. Clearly with the 1.1 compatibility requirement,
  +Ant tasks can not use this keyword. They also need to move away from
  +using the JUnit <tt>assert()</tt> method and start calling <tt>assertTrue()</tt>
  +instead.    
  +
  +
  +
   <h2>Refactor</h2>
   
   If the changes made to a task are making it too unwieldy, split it up
  @@ -106,14 +158,14 @@
   
   <h2>Test</h2>
   
  -Look in jakarta-ant/src/testcases and you will find Junit tests for the
  +Look in <tt>jakarta-ant/src/testcases</tt> and you will find JUnit tests for
the
   shipping ant tasks, to see how it is done and what is expected of a new
   task. Most of them are rudimentary, and no doubt you could do better for
   your task -feel free to do so!
   
   <p>
   
  -A well written set of test cases will break the ant task while it is in
  +A well written set of test cases will break the Ant task while it is in
   development, until the code is actually complete. And every bug which 
   surfaces later should have a test case added to demonstrate the problem,
   and to fix it.
  @@ -135,11 +187,9 @@
   
   <p>
   
  -Remember also that ant 1.x is designed to compile and run on Java1.1, so
  -you should test on java 1.1 as well as any later version which you use.
  -If you are developing on Windows you may well have the Microsoft JVM at
  -hand for this, otherwise you can download an old SDK or runtime from
  -Sun.
  +Remember also that Ant 1.x is designed to compile and run on Java1.1, so
  +you should test on Java 1.1 as well as any later version which you use.
  +You can download an old SDK from Sun for this purpose.
   
   <h2>Document</h2>
   
  @@ -207,7 +257,7 @@
   
   <h2>Submitting to Ant</h2>
   
  -The process for submitting an ant task is documented on the
  +The process for submitting an Ant task is documented on the
   <a href="http://jakarta.apache.org/site/guidelines.html">
   jakarta web site</a>.
   The basic mechanism is to mail it to the ant-dev mailing list.
  @@ -215,7 +265,8 @@
   any debate about your own submission.
   <p>
   
  -Patches to existing files should be generated with <code>cvs diff -u filename</code>
  +Patches to existing files should be generated with 
  +<code>cvs diff -u filename</code>
    and save the output to a file. If you want to get
   the changes made to multiple files in a directory , just use <code>cvs
   diff -u</code>. The patches should be sent as an attachment to a message titled [PATCH]
  @@ -234,7 +285,14 @@
   will reject any messages over 100KB, so any large update should be
   zipped up. If your submission is bigger than that, why not break it up
   into separate tasks. 
  +<p>
   
  +If you hear nothing after a couple of weeks, remind the mailing list. 
  +Sometimes really good submissions get lost in the noise of other issues.
  +This is particularly the case just prior to a new point release of 
  +the product. At that time anything other than bug fixes will tend
  +to be neglected.
  + 
   <h2>Checklists</h2>
   
   These are the things you should verify before submitting patches and new
  @@ -249,6 +307,7 @@
   <h3>Checklist before submitting a patch</h3>
   <ul>
   <li>Added code complies with style guidelines
  +<li>Code compiles and runs on Java1.1
   <li>New member variables are private, and provide public accessor methods
   	if access is actually needed. 
   <li>Existing test cases succeed.
  @@ -267,6 +326,7 @@
   <li>Java file begins with Apache copyright and license statement.
   <li>Task does not depend on GPL or LGPL code.
   <li>Source code complies with style guidelines
  +<li>Code compiles and runs on Java1.1
   <li>Member variables are private, and provide public accessor methods
   	if access is actually needed. 
   <li><i>Maybe</i> Task has failonerror attribute to control failure behaviour
  
  
  

Mime
View raw message