RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Visualizing Data: Self-Documenting Ant files : Page 5

Interactive graphical views of your Ant build files give you more information faster, reduce errors, and provide intuitive methods to help you comprehend, modify, and test build targets.

Graphical Visualization
The techniques presented so far present a variety of essentially textual representations of your build file that vary tremendously in how and how well they communicate information. But it's difficult to surpass the communicative ability of a well-organized graphical rendering of data. This graphical visualization technique involves converting your Ant source code into scalable vector graphics (SVG). From a standard SVG format you may then pass this to applications or other converters to render the final output however you see fit.


Ease of Installation3Besides ant2svg.jar, also need batik-rasterizer.jar for the svg-to-png conversion (not mentioned at all on the web site; the only clue is an unadorned link to the batik web site).
Ease of Use5Two steps needed to get to more standardized graphic formats (e.g. png); alternately, need a viewer for SVG file types.
Shows Targets4Shows just target names.
Shows Connections5Graphical visualization of dependencies.
Strengths Shows entire hierarchy in one diagram.
Weaknesses Too crowded for large Ant files.
Sample file build-svg.xml, build-complex-svg.xml
Download ant2svg, batik rasterizer
CLASSPATH setting ./customJar/ant-ant2svg.jar;./customJar/xalan.jar

The sample build file shown below uses the ant2svg task to generate SVG output (see the xml2svg target in the following code). But even though SVG is a standard format, most browsers do not yet have the capability to render it without a plug-in of some type. Adobe, for example, provides an SVG viewer plug-in for IE. So rather than require a plug-in, the sample project converts the SVG to PNG format that any browser can display. It performs the conversion using another open source package, Batik's SVG rasterizer (see the svg2png target in the code below):

   <project name="MyProject" default="antdoc.vector" basedir=".">
       <description>simple example build file</description>
       <property name="docPath" location="doc"/>
       <property name="customJarPath" 
       <basename property="antfile.base" 
         file="${ant.file}" suffix=".xml"/>
       <dirname  property="antfile.dir"  
       <property name="antfile.path" 
       <target name="build" depends="antdoc.html,antdoc.vector"/>
       <target name="antdoc.vector"
       <target name="xml2svg"
           description="converts build.xml to  build.svg">
           <taskdef name="ant2svg" classname=
           <ant2svg srcfile="${ant.file}" 
       <target name="svg2png"
           description="converts build.svg to build.png"
           <java fork="true" dir="${docPath}"
               <arg value="${antfile.base}.svg"/>
               <arg line="-bg"/>
               <arg line="-m image/png"/>
           <delete file="${docPath}/${antfile.base}.svg"/>
       <!-- <internal target> -->
       <target name="svg2png.checkIfRequired">
           <uptodate property="svg2png.notRequired"
       . . .
The Batik site provides a variety of conversion tools, depending on what type of output you wish to generate; you'll find rasterizer details here.

Figure 16. Sample Build Graph: This graph of the sample build file generated by ant2svg shows all targets and their connections.
This build file is, of course, uncomplicated enough so that one could scan the text and discern the targets and their dependencies, but the clarity and simplicity of the relationship graph generated by ant2svg makes scanning the text unnecessary (see Figure 16). You can immediately discern that a build consists of antdoc.vector (that's the main target that generates the SVG graphic) and antdoc.html (the target from the last section that generates AntDoc). The antdoc.vector target itself depends on xml2svg and svg2png, the two steps involved in converting the Ant file to PNG file, as previously discussed. The help target is shown with no connections because it is independent; it does not get executed during a full build, only when explicitly called or when it's set as the default target (as discussed in the earlier section titled "Ant's Intrinsic Help Facility").

With graphic-generating tools, something simple (like the sample build file) typically works well, but what happens when the build file gets moderately complex? Here's a sample build file that includes a variety of targets and random dependencies between them, as shown:

   <project name="Complex Example" default="antdoc.vector">
       <target name="a" depends="b,c,d"/>
       <target name="b" depends="e,f"/>
       <target name="c" depends="g,h,i,j,k"/>
       <target name="d" depends="l"/>
       <target name="e" depends="g,i,m1,m2,m3,m4,m5"/>
       <target name="f" depends="m1,m2,m3,m4,m5"/>
       <target name="g"/>
       <target name="h" depends="i,j"/>
       <target name="i"/>
       <target name="j"/>
       <target name="k"/>
Figure 17. Moderately-Complex Build Graph: This graph of a moderately complex build file generated with ant2svg is busy but still useful.
<target name="l"/> <target name="m1" depends="m2"/> <target name="m2" depends="m3"/> <target name="m3" depends="m4"/> <target name="m4" depends="m5"/> <target name="m5"/> . . . </project>
Using ant2svg to generate a graph for this build file produces the result in Figure 17. While still readable, this graphical rendering is somewhat more challenging to interpret. If you take a look at an even more complex build—a rendering of the build file for my open source web site—you'll see that the graph no longer provides useful information. Hence, this technique is limited to build files of moderate complexity.

Finally, while the Batik web site looks quite impressive and I am sure the Batik toolset does quite a lot, even as an experienced developer I had some difficulty figuring out what needed to be installed where to run the code. In fact, I ended up running the command-line utility from within my Ant file even though Batik provides an Ant task, because I could not get their Ant task to run.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date