diff --git a/docs/ant_task_guidelines.html b/docs/ant_task_guidelines.html index 7666f56fc..77a101695 100644 --- a/docs/ant_task_guidelines.html +++ b/docs/ant_task_guidelines.html @@ -7,7 +7,7 @@ Ant Task Design Guidelines

Ant Task Design Guidelines

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,13 +22,16 @@ development, maintenance and code size reasons.

Execute

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.

Java, ExecuteJava

-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. +

Project

@@ -61,20 +64,40 @@ which may be important.

-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.

Recommended Names for attributes and elements

-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. - -TODO: list attribute/element names which should be standardised, and meaning - -failonerror, source, dest... +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. + + + + + + + + + + +
+ failonerror + + boolean to control whether failure to execute should throw a + BuildException or just print an error. + Parameter validation failures should always throw an error, regardless + of this flag +
+ destdir + + destination directory for output +
+Yes, this is a very short list. Try and be vaguely consistent with the core +tasks, at the very least.

Design for controlled re-use

@@ -85,7 +108,36 @@ still be decoupled from the actual implementation.

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. + +

Support Java 1.1 through Java 1.4

+ +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 -<touch> +is a case in point- this is usually due to library limitations; +such behaviour change must always be noted in the documentation. +

+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 +NoSuchMethodException handled somehow. +

+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. +

+Java 1.4 adds a new optional change to the language itself, the +assert 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 assert() method and start calling assertTrue() +instead. + +

Refactor

@@ -106,14 +158,14 @@ is so important.

Test

-Look in jakarta-ant/src/testcases and you will find Junit tests for the +Look in jakarta-ant/src/testcases 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!

-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 @@ credibility significantly.

-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.

Document

@@ -207,7 +257,7 @@ line of code.

Submitting to Ant

-The process for submitting an ant task is documented on the +The process for submitting an Ant task is documented on the jakarta web site. The basic mechanism is to mail it to the ant-dev mailing list. @@ -215,7 +265,8 @@ It helps to be on this list, as you will see other submissions, and any debate about your own submission.

-Patches to existing files should be generated with cvs diff -u filename +Patches to existing files should be generated with +cvs diff -u filename and save the output to a file. If you want to get the changes made to multiple files in a directory , just use cvs diff -u. The patches should be sent as an attachment to a message titled [PATCH] @@ -234,7 +285,14 @@ New submissions should be proceeded with [SUBMIT]. The mailer-daemon 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. +

+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. +

Checklists

These are the things you should verify before submitting patches and new @@ -249,6 +307,7 @@ cases, while documentation helps sell the reason for a task.

Checklist before submitting a patch