Visual Documentation of Ant Dependencies in 3 Simple Steps

An automated build process with Ant is one of the most crucial things required in any CI process. Ant is the build tool of choice for many Enterprise Java projects. This is an XML file, usually called build.xml, which describes a project's dependencies. At the beginning of any project, this build file will be somewhere around 70-80 lines, which would include targets for compiling source and tests, running these tests, creating the libraries, and so on...

But, as the project grows, this file grows as well and becomes as huge as several thousand lines; which is complicated and hard to maintain.At this point, you might decide to refactor the build file, but before you being to do so, it would really help if you had a bigger picture of this several thousand lines of XML file, right? As the proverb goes "A picture is worth a thousand words," I will show you how this one picture we are just going to create shows several lines of XML files.

1. Download the libraries. I have tested diagrams from both Grand as well Vizant. I didn't see any significant difference in either one of them. So, based on your preference and the license, download the libraries from here:

• Grand
• Vizant
• Graphviz The dot file needs to be post-processed with Graphviz to produce the actual graph.

2. Create an Ant Target. I have two listings shown below; one for Grand and one for Vizant. If you have used custom ant tasks, the listing shown below is self explanatory. Before using either Grand or Vizant, define a task. Next, give the name of the build file, its location, and the output. To view the graph you need to transform the dot file into something else using the dot command. In our case, we are generating a PDF file, but you can generate any other format as well; like JPG, PNG and so on.

Listing 1 for Grand:

<target name="grandAntDiagram">
    <typedef resource="net/ggtools/grand/antlib.xml" classpath="${basedir}/lib/grand-1.8.jar" />
        <grand output="build.dot" buildfile="${basedir}/build.xml" />
		<exec executable="dot">
		  <arg line="-Tpdf -Gsize=11.69,8.27 -Grotate=90 -o build.pdf ${basedir}/build.dot" />
		</exec>
</target>

Listing 2 for Vizant:

<taskdef name="vizant" classname="net.sourceforge.vizant.Vizant" classpath="${basedir}/lib//vizant-0.1.2.jar" />
<target name="vizantAntDiagram">
		<vizant antfile="${basedir}/build.xml" outfile="vizant-build.dot">
			<attrstmt type="graph">
				<attr name="ranksep" value="1.2" />
				<attr name="nodesep" value="0.5" />
			</attrstmt>
		</vizant>
		<exec executable="dot">
			<arg line="-Tjpg vizant-build.dot -o build.jpg" />
		</exec>
</target>

3. Run the Target.

You can run the targets from the command line, from the IDE of your choice or from your CI server by just calling the above targets.

mobile-166-217-041-119:webservices-samples meerasubbarao$ ls
build.dot dist run.bat
build.pdf instrumented src
build.properties lib test
build.xml passfile vizant-build.dot
classes qalab.xml
cobertura.ser reports
mobile-166-217-041-119:webservices-samples meerasubbarao$ ant grandAntDiagram
Buildfile: build.xml

grandAntDiagram:
[grand] Loading project /Users/meerasubbarao/Development/webservices-samples/build.xml
[grand] Setting up filter chain
[grand] Writing output to /Users/meerasubbarao/Development/webservices-samples/build.dot
[grand] Outputing to /Users/meerasubbarao/Development/webservices-samples/build.dot

BUILD SUCCESSFUL
Total time: 0 seconds
mobile-166-217-041-119:webservices-samples meerasubbarao$

Here are some sample diagrams for the existing build files I had.

1. A simple one, this was the build file I used for my article I wrote for Javalobby.

2. And, this one which was generated by an IDE for another article I was working on. Does your build file look like this? If it does, than it is time to refactor the build files heavily.

P.S: The listings shown above in itself are sufficient for you to get the diagrams working in your build files, the one thing you will need to change is the location of the libraries. Also, don't forget to download and install Graphviz, if not you will get an exception like this:

BUILD FAILED
/Users/meerasubbarao/Development/webservices-samples/build.xml:107:
Execute failed: java.io.IOException: dot: not found
Total time: 269 milliseconds

I hope this article has convinced you about the importance of documenting your build process. The next most important aspect in my view, is communicating the same to your team and keeping the documentation up to date. This article showed you how to follow these aspects in 3 simple steps.