ant/docs/ant_task_guidelines.html

<html><head>
<title>
Ant Task Design Guidelines
</title>
</head><body>

<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
writing tasks for personal use as the issues it addresses are still
there in such a case.


<h2>Use built in helper classes</h2>

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.

<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
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
use execute) or in the same VM -with or without a different classloader. 

<h4>Project</h4>

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.


<h2>Obey the Sun/Java style guidelines</h2>

The Ant codebase aims to have a single unified coding standard, and that
standard is the
<a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">
Sun Java coding guidelines
</a>
<p>

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.

<p>

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.

<p>

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.

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

failonerror, source, dest...

<h2>Design for controlled re-use</h2>

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

The other common re-use mechanism in ant is for one task to create and
configure another. This is fairly simple. (TODO: example)

<h2>Refactor</h2>

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.


<h2>Test</h2>

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!

<p>

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.

<p>

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 <code>ant run-single-test
-Dtestcase=${testname}</code> where ${testname} is the name of your test class.


<p>

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. 

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

<h2>Document</h2>

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.

<h2>Licensing and Copyright</h2>

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.

<p>
This is important.

<p>

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.

<p>

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.

<p>

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.

<h3>Dont re-invent the wheel</h3>

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. 

<p>

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. 


<h2>Submitting to Ant</h2>

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.
It helps to be on this list, as you will see other submissions, and
any debate about your own submission.
<p>

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

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. 

<h2>Checklists</h2>

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. 

<h3>Checklist before submitting a patch</h3>
<ul>
<li>Added code complies with style guidelines
<li>New member variables are private, and provide public accessor methods
	if access is actually needed. 
<li>Existing test cases succeed.
<li>New test cases written and succeed.
<li>Documentation page extended as appropriate.
<li>Example task declarations in the documentation tested.
<li>Diff files generated using cvs diff -u
<li>Message to ant-dev contains [PATCH], task name and patch reason in
subject.
<li>Message body contains a rationale for the patch.
<li>Message attachment contains the patch file(s).
</ul>

<h3>Checklist before submitting a new task</h3>
<ul>
<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>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
<li>New test cases written and succeed
<li>Documentation page written
<li>Example task declarations in the documentation tested.
<li>Patch files generated using cvs diff -u
<li>patch files include a patch to defaults.properties to register the
tasks
<li>patch files include a patch to coretasklist.html or
optionaltasklist.html to link to the new task page
<li>Message to ant-dev contains [SUBMIT] and task name in subject
<li>Message body contains a rationale for the task
<li>Message attachments contain the required files -source, documentation,
test and patches
</ul>
<hr>
<p align="center">Copyright &copy; 2001 Apache Software Foundation. All rights
Reserved.</p>

</body></html>
First cut at a task writer guildline. Submitted by: Steve Loughran <steve_l@iseran.com> git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@268917 13f79535-47bb-0310-9956-ffa450edef68 2001-04-06 08:33:55 +00:00			`<html><head>`
			`<title>`
			`Ant Task Design Guidelines`
			`</title>`
			`</head><body>`

			`<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`
			`writing tasks for personal use as the issues it addresses are still`
			`there in such a case.`


			`<h2>Use built in helper classes</h2>`

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

			`<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`
			`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`
			`use execute) or in the same VM -with or without a different classloader.`

			`<h4>Project</h4>`

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


			`<h2>Obey the Sun/Java style guidelines</h2>`

			`The Ant codebase aims to have a single unified coding standard, and that`
			`standard is the`
			`<a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">`
			`Sun Java coding guidelines`
			`</a>`
			`<p>`

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

			`<p>`

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

			`<p>`

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

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

			`failonerror, source, dest...`

			`<h2>Design for controlled re-use</h2>`

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

			`The other common re-use mechanism in ant is for one task to create and`
			`configure another. This is fairly simple. (TODO: example)`

			`<h2>Refactor</h2>`

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


			`<h2>Test</h2>`

			`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!`

			`<p>`

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

			`<p>`

			`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 <code>ant run-single-test`
minor correction for run-single-test git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@268918 13f79535-47bb-0310-9956-ffa450edef68 2001-04-06 08:35:27 +00:00			`-Dtestcase=${testname}</code> where ${testname} is the name of your test class.`
First cut at a task writer guildline. Submitted by: Steve Loughran <steve_l@iseran.com> git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@268917 13f79535-47bb-0310-9956-ffa450edef68 2001-04-06 08:33:55 +00:00

			`<p>`

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

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

			`<h2>Document</h2>`

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

			`<h2>Licensing and Copyright</h2>`

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

			`<p>`
			`This is important.`

			`<p>`

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

			`<p>`

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

			`<p>`

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

			`<h3>Dont re-invent the wheel</h3>`

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

			`<p>`

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


			`<h2>Submitting to Ant</h2>`

			`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.`
			`It helps to be on this list, as you will see other submissions, and`
			`any debate about your own submission.`
			`<p>`

			`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]`
			`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.`
			`<p>`
			`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.`
			`<p>`

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

			`<h2>Checklists</h2>`

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

			`<h3>Checklist before submitting a patch</h3>`
			`<ul>`
			`<li>Added code complies with style guidelines`
			`<li>New member variables are private, and provide public accessor methods`
			`if access is actually needed.`
			`<li>Existing test cases succeed.`
			`<li>New test cases written and succeed.`
			`<li>Documentation page extended as appropriate.`
			`<li>Example task declarations in the documentation tested.`
			`<li>Diff files generated using cvs diff -u`
			`<li>Message to ant-dev contains [PATCH], task name and patch reason in`
			`subject.`
			`<li>Message body contains a rationale for the patch.`
			`<li>Message attachment contains the patch file(s).`
			`</ul>`

			`<h3>Checklist before submitting a new task</h3>`
			`<ul>`
			`<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>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`
			`<li>New test cases written and succeed`
			`<li>Documentation page written`
			`<li>Example task declarations in the documentation tested.`
			`<li>Patch files generated using cvs diff -u`
			`<li>patch files include a patch to defaults.properties to register the`
			`tasks`
			`<li>patch files include a patch to coretasklist.html or`
			`optionaltasklist.html to link to the new task page`
			`<li>Message to ant-dev contains [SUBMIT] and task name in subject`
			`<li>Message body contains a rationale for the task`
			`<li>Message attachments contain the required files -source, documentation,`
			`test and patches`
			`</ul>`
			`<hr>`
			`<p align="center">Copyright © 2001 Apache Software Foundation. All rights`
			`Reserved.</p>`

			`</body></html>`