Ant Usage Task

This is a proposed DesignPattern for the ApacheAnt build tool -- to have a default "usage" target to describe the usage of the given build file.

Be sure to consider the discussion below, which suggests that users use the '-projecthelp' (or '-p') command line option to print metadata about the project, and that build script writers should use the <description> element and the description attribute of the target element to document each target.

Context:

: You are using the ApacheAnt build tool to build your system.

Problem:

: It is useful if all team members are using the ant tool to build, test and deploy a system. However, often only the author of the build script knows what targets are available and it requires them to either ask the author or examine the build script to find out.

Therefore:

: Create the default task of an Ant build script as the usage task, which explains what targets are available and what they do.

Example:

 <target name="usage">
   <echo>
     Usage:    build target-name
     Available targets:
     target 1  - this target does blah blah blah. Don't forget to blah blah blah
     target 2  - this target does blah blah blah. 
     target 3  - this target does blah blah blah. 
   </echo>
 </target>

Then at the top of the build script set the default task:

 <project name="project1" default="usage" basedir=".">

--RussFreeman

Or... you can give all the user-level tasks description attributes, and then use ant -projecthelp.

Make the default task useful... save yourself some key strokes.

Use ant -p to list the description attribute of each task. If those are maintained it might be enough for a simple project. If you have a huge project (and which ones aren't these days), usage sounds like a winning idea. -- RobertField

Once you have a description attribute on a task, ant -p will only list those tasks with a description; the others are hidden. *Unless* you use ant -p -v , which lists everything.

You can also have a <description> element under a project, which is a generic 'what this build file does'.

Overall then, there is little need for an Ant Usage Target (its a target, not a task), and only increases maintenance costs just like any other document that is not synchronized with the source.

Also, adding a <description> element enables you to provide descriptive text for the file as a whole.

CategoryAnt