diff --git a/docs/ant_task_guidelines.html b/docs/ant_task_guidelines.html new file mode 100644 index 000000000..3dd47b449 --- /dev/null +++ b/docs/ant_task_guidelines.html @@ -0,0 +1,291 @@ + + +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 +writing tasks for personal use as the issues it addresses are still +there in such a case. + + +

Use built in helper classes

+ +Ant includes helper tasks to simplify mauch of your work. Be warned that +these helper classes will look very different in ant2.0 from these 1.x +versions. However it is still better to use them than roll your own, for +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 +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 +use execute) or in the same VM -with or without a different classloader. + +

Project

+ +Project has some helper functions to touch a file, to +copy a file and the like. Use these instead of trying to code them +yourself -or trying to use tasks which may be less stable and fiddlier +to use. + + +

Obey the Sun/Java style guidelines

+ +The Ant codebase aims to have a single unified coding standard, and that +standard is the + +Sun Java coding guidelines + +

+ +It's not that they are better than any alternatives, but they are a +standard and they are what is consistently used in the rest of the +tasks. Code will not be incorporated into the database until it complies +with these. + +

+ +If you are writing a task for your personal or organisational use, you +are free to use whatever style you like. But using the Sun Java style +will help you to become comfortable with the rest of the Ant source, +which may be important. + +

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

Design for controlled re-use

+ +Keep member variables private. If read access by subclasses is required. +add accessor methods rather than change the accessiblity of the member. +This enables subclasses to access the contents, yet +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) + +

Refactor

+ +If the changes made to a task are making it too unwieldy, split it up +into a cleaner design, refactor the code and submit not just feature +creep but cleaner tasks. A common design pattern which tends to occur in +the ant process is the adoption of the adapter pattern, in which a base +class (say Javac or Rmi) starts off simple, then gets convoluted with +support for multiple back ends -javac, jikes, jvc. A refactoring to +split the programmable front end from the classes which provide the back +end cleans up the design and makes it much easier to add new back ends. +But to carry this off one needs to keep the interface and behaviour of +the front end identical, and to be sure that no subclasses have been +accessing data members directly -because these data members may not +exist in the refactored design. Which is why having private data members +is so important. + + +

Test

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

+ +The test cases are a great way of testing your task during development. +A simple call to 'ant run-test' in the ant source tree will run all ant +tests, to verify that your changes don't break anything. +To test a single task, use the one shot ant run-single-test +${testname} where ${testname} is the name of your test class. + + +

+ +The test cases are also used by the committers to verify that changes +and patches do what they say. If you've got test cases it increases your +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. + +

Document

+ +Without documentation, the task can't be used. So remember to provide a +succint and clear html (soon, xml) page describing the task in a similar +style to that of existing tasks. It should include a list of attributes +and elements, and at least one working example of the task. Many users +cut and paste the examples into their build files as a starting point, +so make the examples practical and test them too. + +

Licensing and Copyright

+ +Any code submitted to the Apache project must be compatible with the +Apache Software License, and the act of submission must be viewed as an +implicit transfer of ownership of the submitted code to the Apache +Software Foundation. + +

+This is important. + +

+ +The fairly laissez-faire license of Apache is not compabitible with +either the GPL or the Lesser GPL of the Free Software Foundation -the +Gnu project. Their license requires all changes to the source to be made +public, and give the licensee of any software the right to distribute +copies. It also requires derivative works to be made available under the +same license terms. None of these requirements are in the Apache Software +Foundation license, which permits people and organisations to build +commercial and closed source applications atop the Apache libraries and +source -but not use the Apache, Ant or Jakarta Project names without +permission. + +

+ +Because the Gnu GPL license immediately extends to cover any larger +application (or library, in the case of GLPL) into which it is +incorporated, the Ant team can not incorporate any task based upon GPL +or LGPL source into the Ant codebase. You are free to submit it, but it +will be politely and firmly rejected. + +

+ +Once ant-2 adds better dynamic task incorporation, it may be possible to +provide a framework for supporting [L]GPL code, but still no tasks +direcely subject to the Gnu licenses will ever be included in the Ant +CVS tree. + +

Dont re-invent the wheel

+ +We've all done it: written and submitted a task only to discover it +was already implemented in a small corner of another task, or it has +been submitted by someone else and not committed. You can avoid this +by being aware of what is in the latest CVS tree -keep getting the daily +source updates, look at manual changes and subscribe to the ant-dev +mailing list. + +

+ +If you are thinking of writing a task, posting a note on your thoughts +to the list can be informative -you well get other peoples insight and +maybe some half written task to do the basics, all without writing a +line of code. + + +

Submitting to Ant

+ +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. +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 + 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] +and distinctive one-line summary in the subject of the patch. The +filename/task and the change usually suffices. It's important to include +the changes as an attachment, as too many mailers reformat the text +pasted in, which breaks the patch. +

+Then you wait for one of the committers to commit the patch, if it is +felt appropriate to do so. Bug fixes go in quickly, other changes +often spark a bit of discussion before a (perhaps revised) commit is +made. +

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

Checklists

+ +These are the things you should verify before submitting patches and new +tasks. Things don't have to be perfect, it may take a couple of +iterations before a patch or submission is committed, and these items +can be addressed in the process. But by the time the code is committed, +everything including the documentation and some test cases will have +been done, so by getting them out the way up front can save time. +The committers look more favourably on patches and submissions with test +cases, while documentation helps sell the reason for a task. + +

Checklist before submitting a patch

+ + +

Checklist before submitting a new task

+ +
+

Copyright © 2001 Apache Software Foundation. All rights +Reserved.

+ + +