ant2dot.xsl - ANT script visualization

ant2dot.xsl
ANT script visualization

mailto:pvandenberk@users.sourceforge.net
http://sourceforge.net/projects/ant2dot/

Table of Contents

What? How? Download Quick Start Examples Features Options FAQ To Do Version History Miscellaneous Acknowledgements Mailing Lists

What?

The ant2dot.xsl stylesheet provides a means to visualize the targets in an ANT build script and their dependencies.

How?

More specifically, ant2dot.xsl is an XSL stylesheet that transforms an ANT build script (written in XML) into a DOT file, which in turn can be transformed into a unidirected graph (as a GIF, JPG or PNG image) using the GraphViz toolkit.

Download

The goodies you want

Use "Save target as..." (or "Save link as..." depending which browser you are using) to download the ant2dot.xsl stylesheet onto your disk.

A good place to save the stylesheet to is the ${ANT_HOME}/etc directory (this is where the Ant distro keeps a bunch of stylesheets used by some of the core and optional tasks).

Other stuff you need

To use the ant2dot.xsl stylesheet you will need a XSLT processor (like Xalan) and the GraphViz toolkit.

Note that JDK 1.4.x includes the Xalan XSLT processor, so if you're using this version of Java, you only need to download and install the GraphViz toolkit.

Also note that Pixelglow Software maintains a superb Mac OS X port of the Graphviz toolkit.

The Quick Start section of this document describes a number of ways to generate the unidirected graph using the stylesheet.

Quick Start

There are two ways to generate the image containing the unidirected graph: the first one generates the image from the command line, while the second one generates the image using an ANT target. As mentioned in the Download section, you will need to download and install an XSLT processor and the GraphViz toolkit onto your system for all this to work.

From the command line

First, the DOT file needs to be generated.

If you are using JDK1.3.x or lower, download and install the Xalan XSLT processor onto your system. Assuming xalan.jar and ant2dot.xsl have been copied into the directory containing the ANT script you want to visualize, the DOT file can be generated using the Xalan processor as follows:

  > java -cp xalan.jar org.apache.xalan.xslt.Process
         -IN build.xml
         -XSL ant2dot.xsl
         -OUT build.dot

If you are using JDK1.4.x you already have a copy of the Xalan processor on your system, and the following command can be used to generate the DOT file:

  > java org.apache.xalan.xslt.Process
         -IN build.xml
         -XSL ant2dot.xsl
         -OUT build.dot

The above command instructs the Xalan processor to apply the ant2dot.xsl stylesheet to the build.xml ANT script, and to write the output to the build.dot DOT file.

Next, the unidirected graph needs to be generated.

To do this, download and install the GraphViz toolkit onto your system. Assuming the dot(.exe) executable can be found on your PATH, the unidirected graph can be generated using the GraphViz dot utility as follows:

  > dot -Tpng build.dot -o build.png

The above command instructs the dot utility to generate the unidirected graph into the build.png image using the build.dot DOT file generated in the first step as input. You can now open and view build.png using your preferred image viewer. Other image formats are supported by the dot utility, and can be generated as follows:

  > dot -Tgif build.dot -o build.gif
  > dot -Tjpg build.dot -o build.jpg

No matter the output format, you always use the same build.dot input file.

Using an ANT target

If your version of ANT supports the XSLT task, and a compatible XSLT processor can be found in ANT's sysclasspath (which will be the case if either you use JDK1.4.x or if you copy xalan.jar to ${ANT_HOME}/lib on Unix platforms or %ANT_HOME%\lib on Windoze), then you can visualize any ANT build script by adding the following target to it:

  <target name="ant2dot">

    <!-- STEP 1: set some ANT properties -->
    <property name="build.xml" value="${ant.file}"/><!-- ie. this ANT script -->
    <property name="ant2dot.xsl" value="${basedir}/ant2dot.xsl"/><!-- the stylesheet -->
    <basename property="basename.script" file="${build.xml}" suffix=".xml"/>
    <property name="dot.file" value="${basename.script}.dot"/>
    <property name="png.file" value="${basename.script}.png"/>

    <!-- STEP 2: generate the DOT file ("build.dot" or something similar) -->
    <xslt in="${build.xml}" out="${dot.file}" style="${ant2dot.xsl}" force="true" />

    <!-- STEP 3: generate the PNG file ("build.png" or something similar) -->
    <exec executable="dot.exe" dir="${basedir}" os="Windows 2000">
      <arg value="-Tpng"/>
      <arg value="${dot.file}"/>
      <arg value="-o"/>
      <arg value="${png.file}"/>
    </exec>

  </target>

This target makes the same assumptions as the command line approach, namely that the GraphViz toolkit is installed on your system and that the dot(.exe) executable can be found on your PATH. To generate the build.dot and the build.png files, use the following ANT command:

  > ant -buildfile build.xml ant2dot

The above command invokes the ant2dot target, which generates the unidirected graph into the build.png image using the build.dot DOT file generated in the second step as input. You can now open and view build.png using your preferred image viewer.

Examples

The table below shows an example ANT script with targets and dependencies that are quite typical for a Java project. The corresponding unidirected graph consists of nodes that correspond to ANT targets and edges that correspond to target dependencies.

ANT script

<project name="simple" default="junit" basedir=".">

    <target name="init"/>
    <target name="clean" depends="init"/>
    <target name="compile" depends="init"/>
    <target name="junit" depends="compile"/>
    <target name="javadoc" depends="compile"/>
    <target name="install" depends="junit, javadoc"/>

</project>

graph

The next table shows an ANT script in which some of the targets use the ant and antcall tasks. The antcall tasks are visualized using a dashed edge between the two nodes involved. The ant tasks are also visualized using a dashed edge; and in addition the external target is visualized as a record node, containing not only the target name, but also the directory and file name of the external ANT script.

ANT script

<project name="complex" default="deploy" basedir=".">

    <target name="init"/>
    <target name="clean" depends="init"/>
    <target name="junit">
        <ant antfile="simple.xml" target="junit"/>
    </target>
    <target name="javadoc">
        <ant antfile="simple.xml" target="javadoc"/>
    </target>
    <target name="deploy" depends="junit, javadoc">
        <antcall target="clean"/>
    </target>

</project>

graph

The Options section below has other examples illustrating the various parameters that can be passed into the stylesheet.

Features

ANT-related features

the various TARGETS in the build script are visualized as rectangular nodes
the default TARGET in the script is highlighted as a node with a dashed border
the target DEPENDENCIES are visualized as solid edges between the nodes
the target DEPENDENCIES are numbered on the graph
ANT/ANTCALL tasks are numbered on the graph
ANTCALL tasks are differently colored nodes
ANTCALL tasks are represented as record nodes
creates a PROJECT node (optionally)
uses ANT SCRIPT NAME as graph label (optionally)
generates default attribute values (for PROJECT/ANT/ANTCALL tasks)

XSLT-related features

ANT SCRIPT NAME passed in as parameter and used as graph label
boolean flag to optionally include TARGET descriptions
boolean flag to optionally generate a PROJECT node

DOT-related features

settings/parameters are reported as DOT comments

Options

The following examples illustrate some of the more advanced options supported by the stylesheet; all examples are based on the same ANT build script used in the Examples section above, but by passing one of the supported parameters into the stylesheet, a slightly different graph is generated in each case. The following stylesheet parameters are currently supported:

graph.label

results in a border around the graph, with the value of the graph.label parameter used to generate a label below the graph

create.project.node

results in a record node on the graph containing basic information about the ANT project taken from the ANT build script

use.target.description

results in target nodes containing not only the target name, but also the target description (if present in the build scripts)

use.target.conditions

results in target nodes containing the "if" and "unless" target conditions specified in the ANT build script

When using the command line approach for generating the DOT file, you pass in an XSL parameter as follows:

  > java org.apache.xalan.xslt.Process
         -PARAM graph.label simple.xml
         -IN build.xml
         -XSL ant2dot.xsl
         -OUT build.dot

When using the ANT target approach for generating the DOT file, you pass in an XSL parameter as follows:

  ...

    <!-- STEP 2: generate the DOT file ("build.dot" or something similar) -->
    <xslt in="${build.xml}" out="${dot.file}" style="${ant2dot.xsl}" force="true">
        <param name="graph.label" expression="simple.xml"/>
    </xslt>

  ...

These stylesheet parameters are illustrated below; note that these parameters can be combined at random.

parameter	graph
`<no options>`

`-PARAM graph.label simple.xml` `<param name="graph.label" expression="simple.xml"/>`

`-PARAM create.project.node true` `<param name="create.project.node" expression="true"/>`

`-PARAM use.target.description true` `<param name="use.target.description" expression="true"/>`

`-PARAM use.target.conditions true` `<param name="use.target.conditions" expression="true"/>`

FAQ

Q. dot(.exe) issues the following warning: Could not find/open font : Courier in <some path>

This warning message indicates that dot(.exe) cannot locate the descriptor file for the Courier font (which is the font specified in the ant2dot.xsl stylesheet); on Windows, this message can be ignored, as dot(.exe) will use its default font instead; on Solaris (and possibly other *nix platforms) this warning can be fixed by making sure the DOTFONTPATH environment variable correctly includes the platform-specific fonts directory; see the GRAPHVIZ FAQ for more info.

To Do

better formatting of the generated DOT output
ant2html stylesheet that generates HTML pages with CMAP-enabled graphs
support for the new <import> task introduced in version 1.6 of ANT
support for the new <subant> task introduced in version 1.6 of ANT
better ranking/sorting/grouping of the graph's nodes and edges
certify ant2dot.xsl with other XSLT processors (e.g. Altova and xsltproc)
document all stylesheet options (e.g. colour options)

Version History

Version 0.6 (Tuesday January 2nd 2007)
[BUGFIX] minor changes to the ant2dot.xsl script to avoid errors from the XSLT processor, which correctly complains about the redefinition of template variables (referred to as "shadowing" of template variables and template parameters in the XSLT 1.0 W3C standard) - these errors were issued by: Java 1.5 built-in XSLT processor, AltovaXSLT on Windows, xsltproc on Darwin.
Version 0.5 (Wednesday April 27th 2005)
[BUGFIX] the ant2dot.xsl script now avoids "node duplication" in the generated DOT file for targets that are both top-level project targets as well as antcall targets; as a side effect, the "description" field for antcall targets is now correctly rendered in the generated graph.
Version 0.4 (Thursday May 13th 2004)
[ENHANCEMENT] the ant2dot.xsl script now supports the "use.target.conditions" option that can be used to include the "if" and "unless" target conditions that may be specified in the ANT build script.
Version 0.3 (Friday September 12th 2003)
[BUGFIX] for the "ant" task: the stylesheet now picks up and uses the value for the "antfile" attribute if it is explicitly specified on "ant" tasks; in previous versions, the stylesheet was *always* using the default value ("build.xml") for this attribute, even if it was explicitly set to another value on the "ant" task; this bug ultimately resulted in black rectangles showing up on the DOT graph.
Version 0.2 (Wednesday April 2nd 2003)
[ENHANCEMENT] for the "ant" task: the stylesheet now uses the correct default values for the "dir", "antfile" and "target" attributes if these aren't explicitly specified on "ant" tasks.
Version 0.1 (Thursday March 27th 2003)
First public beta release

Miscellaneous

Coming soon...

Acknowledgements

The following people have adopted and tested ant2dot.xsl, provided valuable feedback, and suggested useful improvements which have been incorporated already or else put on the To Do list: Gary Frost, David Gardner, Johannes Schaback, Ulrich Shäfer.

Tilaye Y Alemu has developed an Eclipse plugin that uses ant2dot.xsl to visualize ANT build scripts within the Eclipse IDE... head over to http://eclipseant2dot.ertale.com/ to download the goodies!

"A great idea is usually original to more than one discoverer."
(Elizabeth Stuart Phelps)

As it turns out, I wasn't the first person to consider the idea of transforming an Ant build script into a DOT file by means of an XSL stylesheet: long before I put ant2dot.xsl on SF, Stefan Kost posted a similar stylesheet with the same name to the ANT-USER mailing list ("xsl script to generate graphical representation of build.xml"), and Vadim Nasardinov put yet another but also similar stylesheet with the same name up on the RedHat website ("a result of my semi-annual exercise in XSLT programming").

Another ANT visualization framework is available from www.softwaresecretweapons.com; on this site you can generate a diagrammatic representation of your ANT build script on-line!

Mailing Lists

Two mailing lists have been set up: new releases of the ant2dot.xsl stylesheet will be announced on ant2dot-announce, and general discussions of the stylesheet can be posted to ant2dot-discuss. You can subscribe to one or both of these mailing lists using the following forms:

Table of Contents