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 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. Some IDEs (JEdit) can highlight tabs, to stop you accidentally inserting them
The ant1.x tasks are very inconsistent regarding naming of attributes
-some tasks use source, others srctt>.
Here is a list of preferred attribute names.
Yes, this is a very short list. Try and be vaguely consistent with the core
tasks, at the very least.
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
destfile
destination file for output
srcdir
source directory
srcfile
source file
Support classpaths
Try and make it possible for people to supply a classpath to your task,
if you need external libraries, rather than make them add everything to
the ANT_HOME\lib directory. This lets people keep the external libraries
in their ant-based project, rather than force all users to make changes
to their ant system configuration.
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.
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 call assertTrue() instead.
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 'build 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
-Dtestcase=${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. To be precise, we hate submissions without test cases, as it means we have to write them ourselves. This is something that only gets done if we need the task or it is perceived as utterly essential to many users.
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.
Finally, run a full build test
before and after you start
developing your project, to make sure you havent broken anything else by
accident.
You can use the xdocs stuff in proposal/xdocs to autogenerate your documentation page from the javadocs of the source; this makes life easier and will make the transition to a full xdoclet generated documentation build process trivial.
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. These licenses have stricter terms, "copyleft", which are not in the Apache Software Foundation license. This 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 indirectly supporting [L]GPL code, but still no tasks directly subject to the Gnu licenses can be included in the Ant CVS tree.
If you link to a GPL or LGPL library, by import
or
reflection, your task must be licensed under the same terms. So tasks
linking to (L)GPL code can't go into the Apache managed codebase.
Tasks calling such code can use the 'exec' or 'java' tasks to run the
programs, as you are just executing them at this point, not linking to
them.
Even if we cannot include your task into the Apache codebase, we can still point to where you host it -just submit a diff to xdocs/external.html pointing to your task. If your task links directly to proprietary code, we have a differnt problem: it is really hard to build the tasks. Please use reflection.
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.
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.
We also like submissions to be added to bugzilla, so that they dont get lost. Please submit them by first filing the report with a meaningful name, then adding files as attachments. Use CVS diff files please!
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.
Copyright © 2001-2002 Apache Software Foundation. All rights Reserved.