When inheriting an Ant build file to maintain, it is useful to get a feel for the flow and structure. Sketching the dependencies between targets is a useful way to do this. While it is time consuming to do so by hand, there are a number of tools to help.
I tried three different tools to generate the output. All of them generate a .dot file which needs to be run through the Graphviz tool to be converted to a useful format. Graphviz can covert to all image formats among many others. Each tool is described below with an example of how to call it. I've also included two sample images: from our build script to Pick Winners in the weekly book/software promotion and a contrived example designed to show how antCall and forEach work.
-
Ant2Dot - Ant2Dot is an XSLT file that converts your Ant build file into a .dot file. Each target becomes a rectangle and dependencies between targets are shown. The instructions for using it are a bit old and only apply to Java 1.3 and 1.4. They don't work on Java 5/6 without modification. The website lists a "to do" for adding support for Ant 1.6's import and subant features. Similarly, 1.7 features aren't supported yet. Ant2Dot is good for simple build files, but doesn't scale up to handle use advanced features. Running was as simple as downloading a stylesheet and running the command:
C:\j2re1.4.2_03\bin\java org.apache.xalan.xslt.Process -IN build.xml -XSL ant2dot.xsl -OUT build.dot
Output of JavaRanch's book promotion pick a winner dependency structure and a contrived sample:
-
Vizant - Vizant is a Java library that creates a .dot file by using a SAX parser on your Ant build file. Each target becomes an oval and dependencies between targets are shown. Vizant supports antcalls and allows you to drill down to generate only part of the build tree. You can also drill down to show part of your build tree. Vizant was easy to use. I wanted the dependency ordering so continued looking for a library to meet my needs. In order to run Vizant, you need to download a jar containing the source and build it using Ant. They provide the build.xml to do so. Since this is a library for Ant documentation, it is reasonable to assume people know how to run Ant. You also call it through a simple Ant build file:
<?xml version="1.0"?> <project name="Vizant" basedir="." default="vizant"> <taskdef name="vizant" classname="net.sourceforge.vizant.Vizant" classpath="build/vizant.jar" /> <target name="vizant"> <vizant antfile="build.xml" outfile="build.dot" uniqueref="true" /> </target> </project>
Output of JavaRanch's book promotion pick a winner dependency structure and a contrived sample:
-
Grand - Grand is also a Java library that creates a .dot file. It takes a different approach and actually creates the Ant directory structure using Ant's Java libraries. It can support anything in your classpath including ant-contrib and Ant 1.6's import feature. The logic doesn't capture the subtleties of Ant-Contrib like the forEach loop though. The graph is a bit more detailed. The default target is a yellow hexagon. Targets with a description are marked in blue so you can show entry points. The remaining targets are shown as ovals. You can also drill down to show part of your build tree. You can use a Grand UI tool instead of the dot file, but I wasn't able to get the UI. Like Ant2Dot, dependencies are numbered. Grand was as easy to use as Vizant. They provide you with a jar for download. You call it through a simple Ant build file adding any other jars used to the classpath:
<?xml version="1.0"?> <project name="Grand" basedir="." default="grand"> <typedef resource="net/ggtools/grand/antlib.xml" classpath="grand.jar" /> <target name="grand"> <grand output="grand-build.dot" buildfile="build.xml" /> </target> </project>
Output of JavaRanch's book promotion pick a winner dependency structure and a contrived sample:
