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.
- You are using the ApacheAnt build tool to build your system.
- 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.
- Create the default task of an Ant build script as the usage task, which explains what targets are available and what they do.
Usage: build target-name
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.
Then at the top of the build script set the default task:
<project name="project1" default="usage" basedir=".">
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.