Listing Phing Targets In A Project

Providing a Phing build file along with a project is a good way of allowing automation of certain aspects of the project. The only trouble is that users won't know what's in the build file unless they open it or just run it. You could provide documentation along with the build file so that users know what to use the file for, but a better approach is to list out the targets available in a project. This can be done easily by using the -l (lower case L) or list flag, which will just list the available targets in the supplied build file.

Running this on a build file will produce this sort of output from a build file with two targets, one of which is run as a default.

Default target:
-------------------------------------------------------------------------------
 build          Build the project.

Main targets:
-------------------------------------------------------------------------------
 dosomething   This target does something.

The list flag uses the information from the targets in the project to produce this list. The name attribute of the target is used to label each target and the description of each target is used to give a description of the target function. This is why adding descriptions to your targets is useful.

Rather than launch into something potentially dangerous with the default target of a build file it is good practice provide a default target that doesn't do all that much. Users who are new to the project (as well as Phing) might just run the build file to see what it does. Instead of printing out a message suggesting the user read the build file for more information you could print out a list of Phing targets and their descriptions that the user could use. This can easily be done by using an exec task to call the Phing program using the list flag on the same build file from within the project itself. The following build file will print out a list of the available targets in the project if no target name is given.

<?xml version="1.0"?>
<project name="projectbuild" default="default">

  <target name="default" description="The default target used when no arguments have been given.">
    <exec command="phing -f ${phing.file} -l" outputProperty="phing_targets" />
    <echo>Please select a target.</echo>
    <echo>${phing_targets}</echo>
  </target>

  <target name="dosomething" description="This target does something">
    <echo>Running target....</echo>
  </target>
</project>

This will produce the following output.

philipnorton42@norton42-vbox:/var/www/project$ phing -f scripts/build.xml
Buildfile: /var/www/project/scripts/build.xml

projectbuild > default:

     [echo] Please select a target.
     [echo] Buildfile: /var/www/project/scripts/build.xml
Default target:
-------------------------------------------------------------------------------
 default      The default target used when no arguments have been given.

Main targets:
-------------------------------------------------------------------------------
 default      The default target used when no arguments have been given.
 dosomething  This target does something


BUILD FINISHED

Total time: 0.1888 seconds

This approach gives the more information and is much safer for the user if they were to run the build file without checking what it did first.