Java Extreme Programming Cookbook

Providing Help

Problem

You want to provide help messages in your buildfiles.

Solution

Include a description attribute on the <project> and <target> tags. Also consider writing a help target, and use XML comments throughout the buildfile.

Discussion

Example 3-2 shows several techniques for providing additional help in Ant buildfiles. In this example, the help target is listed as the default target and is executed when the user types ant at the command line.

Example 3-2. Various ways to provide help

<?xml version="1.0"?>

<!-- You can document the buildfile using XML comments -->
<project name="My Big Project" default="help" basedir=".">
  <description>Shows how to provide help in an Ant buildfile.</description>

  <property name="dir.src" value="src"/>

  <target name="help">
    <echo message="This buildfile shows how to get help."/>
    <echo>(Type 'ant -projecthelp' for more info)</echo>
    <echo><![CDATA[  
       Here is a block of text
       that you want to format
       in a very specific way!]]></echo>
  </target>

  <!-- Here is an example of a subtarget -->
  <target name="prepare">
    <mkdir dir="${dir.build}"/>
    <mkdir dir="${dir.dist}"/>
  </target>

  <!-- Here is an example of a main target -->
  <target name="clean"
          description="Remove all generated files.">
    <delete dir="${dir.build}"/>
    <delete dir="${dir.dist}"/>
  </target>

  <target name="compile" depends="prepare"
          description="Compile all source code.">
    <javac srcdir="${dir.src}" destdir="${dir.build}"/>
  </target>
</project>

The help target uses the echo task to print some ...