|
Fri
28
Jan '05
|
|
Here’s a little addon to Eric M. Burke pretty good article “Top 15 Ant Best Practices”.
Concerning help he wrote:
4. Provide Good Help
Strive to make the buildfile self-documenting. Adding target descriptions is the easiest way to accomplish this. When you type ant -projecthelp, you see a listing of each target containing a description. For example, you might define a target like this:<target name="compile" description="Compiles code, output goes to the build dir.">The simple rule is to include descriptions for all of the targets you wish programmers to invoke from the command line. Internal targets should not include description attributes. Internal targets may include targets that perform intermediate processing, such as generating code or creating output directories.
Another way to provide help is to include XML comments in the buildfile. Or, define a target named help that prints detailed usage information when programmers type ant help.
<target name="help" description="Display detailed usage information"> <echo>Detailed help...</echo> </target>
You can combine these two things to get a simple help target without much effort. You call ant -p/-projecthelp ‘from the inside’ via the exec task. This way you don’t have to write a seperate help target.
<project name="whatever" default="help" basedir="."> <target name="compile" description="compile my code"/> <target name="jar" description="build my jar"/> <target name="clean" description="cleanup"/>
<target name="help" description="print this help"> <exec executable="ant"> <arg value="-p"/> </exec> </target> </project>
prints
$ ant Buildfile: build.xml
help: [exec] Buildfile: build.xml
[exec] Main targets:
[exec] clean cleanup [exec] compile compile my code [exec] help print this help [exec] jar build my jar [exec] Default target: help
BUILD SUCCESSFUL Total time: 1 second
who doesn’t know he can call “ant -projecthelp” from the commandline to get help shouldn’t be allowed to use ant anyway…
I bet a lot of ant users don’t know about -projecthelp. IIRC I used it for quite some time before I found out. Anyway, if it’s no extra effort why not provide an additional ‘help’ target.
A help target that merges “ant -p” output with other top-level information (or possibly just have a description on the project, and display that together with the target descriptions). If there was a sane formatting, so long descriptions — even multi-paragraph descriptions — would be readable in ant -p output, this would actually be useful …
Thanks Frank. In support of your comment/premise, not everybody has time for training courses or learns all the basics before the more advanced stuff they need. I’ve used Ant to do lots of useful and funky stuff in the past, and I didn’t know about this. Nor did the people who created most (if not all) of the Ant files I’ve borrowed or inherited. And if the author doesn’t know to put descriptions in, “ant -projecthelp” won’t be of much use to anyone. I thought there must be a better way, and Google brought me here, and you helped me out. Schlumpf, why are you wasting your precious time here? Get back to work! (especially if you’re still here nearly 5 years later)
.
Just a minor addition, I had to add the “path” to ANT.