Visualizing Data: Self-Documenting Ant files : Page 6

Graphical Ant—Take Two
Here's another try at creating a graphical visualization for the Ant build using a task called "grand." This version creates a flowchart-type graph, which can be easier to interpret.

Grand Visualization
Technique	Rating	Description
Ease of Installation	4	Needs grand.jar, dot, and GhostScript for PDF output. Also needs Perl for optional customization of PDF.
Ease of Use	5	One step for interactive use with GUI. Two or three steps needed to get to more standardized output formats such as PDF or PNG. Four steps needed for PDF personalization.
Shows Targets	4	Statically shows just target names. Displays public and private, but differentiates them by color and shape. In GUI, shows target names, descriptions, conditions.
Shows Connections	5	Graphical visualization of dependencies with ordering.
Strengths		Output is filterable to specific subsets. Shows entire hierarchy in one diagram. Distinguishes public from private targets. Provides a dynamic GUI.
Weaknesses		No execution framework nor links to Ant documentation.
Sample file		build-grand.xml, build-complex-grand.xml
Download		http://www.ggtools.net/grand/ (grand) http://www.graphviz.org/ (dot) http://pages.cs.wisc.edu/~ghost/ (ghostscript) http://www.activestate.com/Products/activeperl/ (perl)
CLASSPATH setting		Specified in Ant file
PATH setting		To execute dot: C:\Program Files\Graphviz\Graphviz\bin To execute ps2pdf: C:\Program Files\GhostScript\gs8.57\lib and C:\Program Files\GhostScript\gs8.57\bin

Figure 18. Flowchart-Style Build Graph: A grand-generated graph of the sample build file shows targets, connections, ordering, public vs. private, and the default target.

Take a look at a rendering of the sample build file using the Ant grand task (see Figure 18).

This graph uses some specific shape and color conventions—the yellow octagon, cyan rectangles, and so on. The meanings of these symbols are not included in the generated graph, and, while described on the home page of the web site, it is not immediately obvious or quick to find them. So here is a legend for the graph:

• default target: yellow octagon
• public targets: blue box
• private targets: white ovals
• external targets: gray oval

Just from this minimal information, you can glean that this graph provides a useful distinction between public and private targets, as well as pointing out the default target. Notice also the numbers on the links whenever there is more than one dependency for a target. Those numbers define the ordering of dependencies from your build file, letting you see which will run first, second, and so forth. It is clear, then, that this visualization of the build file provides a wealth of information of the entire file in one graph.

Figure 19. Graph Comparison: Here's a side-by-side comparison of the graph generated by grand and that by ant2svg for the same build file.

Compare the rendering of the two graph builders (ant2svg and grand) side by side in Figure 19. Which one is better? That depends on what you are looking for. The grand-generated graph contains more useful bits of information as just itemized, but the ant2svg-generated graph is cleaner and more streamlined in a sense.

You will see shortly how the two methods compare for moderate and for complex build files, but first here are some details about using grand. As can be readily observed from the graph, the sample build file uses a four-step process to generate the antdoc.graph target:

• xml2dot—The grand tool converts the Ant XML to the general graphics "dot" format.
• dot2ps—The dot tool converts from the dot format to other standard graphical formats. The sample build file in Listing 2 converts dot to PostScript because PostScript is easy to convert to PDF format—a standalone, finished document. In contrast, you typically include PNG or TIF files in some other file, such as a Word document. Dot can generate PNG instead; in fact, Listing 2 generates both, providing the PNG file in Figure 18.
• psmodify—This step is optional but you can use it to update PostScript files, providing another reason to convert from dot to PostScript. The sample build file includes a custom PostScript update tool that injects a title block into the PostScript file.
• ps2pdf—The ps2pdf converter is part of the GhostScript tool set; it converts a PostScript file to PDF format. The command-line options for GhostScript's ps2pdf are not obvious, but are the same as Acrobat Distiller. In addition, you may use the options for the GhostScript (gs) command-line program. One of the more useful options, -sPAPERSIZE, comes from GhostScript.

Figure 20. Modifying the PostScript File: Adding a title block using the psmodify step modifies creates a more professional look.

The psmodify step is optional, but is useful for customizing generated graphs. This step uses a custom Perl program (pscaption.pl), included with the sample code for this article; you will need to load ActiveState's free Perl interpreter (or equivalent) on your system to run it. The utility takes the standard graph (as in Figure 18) and adds a title block to it (as in Figure 20). The lines comprising the title block are specified in the Ant file so you may include any text you wish. I have left several unassigned variables for version, revision date, copyright, etc. that would normally be defined within the Ant file, just to give a few ideas.

The final product from this pipeline of steps yields quite a good visualization, providing considerable build detail on one page, along with a convenient way for you to add explanatory text (a caption or notes or whatever suits your needs). But keep in mind that the input is a very simple build file. How does it scale? Figure 21 shows the output from the same medium-complexity build used for the ant2svg technique (see Figure 17). The outputs from both generators are still useful at this level of complexity, though one could argue that the layout of the grand-generated graph is somewhat clearer and more spacious.

Figure 21. Moderately Complex Build Graph: A grand-generated graph of a moderately complex build file is busy but still useful.

Just as with ant2svg, the final check is to see what happens if you generate a graph for a real-world build file. Again, this complex build file rendering shows that you can get a lot of information on a page, particularly when printed at full size.

The grand tool is able to scale well. But that is not its only virtue—it can still do more! For a complex build file (such as represented in the ant_all.pdf file), wouldn't it be nice to be able to filter the graph to just those elements that you are interested in? For example, suppose you want to view a specific path through the graph from target a to target b. Or perhaps you have an initialize target connected to most of your other targets and you just don't want to show all the connections emanating from it. Grand provides just such a powerful, flexible, and yet easy to use capability. These are options available through command-line switches that you can specify to the complex build file sample (build-complex-grand.xml). For example, the full, unfiltered graph presented in Figure 21 was generated with this command line:

   ant --f build-complex-grand.xml --Dbuild.all=1
   

Figure 22. Filtered View: This filtered view of the build from the grand tool creates a graph containing only specific details of interest.

To apply some filtering, if you rerun the build with the —Dbuild.doc=1 switch instead you'll see the graph in Figure 22, which includes only the targets related to building the graphical documentation. The filter suppresses all the test targets that were included to show complexity.

The build steps involving grand in Figure 22 have been reorganized from the original (see Figure 20) to facilitate adding the filtering. Note that antdoc.graph depends on the ps2pdf step, which in turn depends on the psmodify step, which in turn depends on the dot2ps step, which in turn depends on four flavors of xml2dot. Here are the key portions of the code for each flavor of xml2dot:

       <target name="xml2dot.all" if="build.all"
           description="converts xml to dot format for ALL targets">
           <grand output="${docPath}/${name}.dot"/>
       </target>
   
       <target name="xml2dot.doc" if="build.doc"
           description=
           "converts xml to dot format for DOC targets">
           <grand output="${docPath}/${name}.dot">
               <filter name="fromnode" node="build"/>
           </grand>
       </target>
   
       <target name="xml2dot.nondoc" if="build.nondoc"
           description=
           "converts xml to dot format for non-DOC targets">
           <grand output="${docPath}/${name}.dot">
               <filter name="fromnode" node="a"/>
           </grand>
       </target>
   
       <target name="xml2dot.m5" if="build.m5"
           description=
           "converts xml to dot format for targets to m5">
           <grand output="${docPath}/${name}.dot">
               <filter name="tonode" node="m5"/>
           </grand>
       </target>

Figure 23. Filtered View: This filtered view shows only targets that connect to the m5 target.

Only one of these four targets should be executed at a time. You could specify more than one switch on the command line, but because each target writes to the same output file, only the last one in the dependency list of dot2ps will persist. For example, building the graph with the build.doc filter executes the xml2dot.doc target. That target includes an additional one-line specification to grand, specifying it should include only targets emanating, however indirectly, from the build target. Similarly, the xml2dot.m5 target specifies that grand should include only targets that connect to the m5 target (see Figure 23). See the complete list of grand filters for more information.

Real-world examples of filtering can be seen by comparing the ant_all.pdf file mentioned earlier to the filtered ant_website.pdf (showing just web site-related targets) and ant_dist.pdf (showing just distribution-related targets) from the same directory.

Figure 24. The Grand UI: Grand comes with its own user interface, allowing you to explore a visual representation of your build file dynamically.

So grand seems to be quite useful for generating a static graph. Wouldn't it be nice if it could also show you the source code at the same time? Enter the Grand-UI. The grand developers have done an outstanding job of moving from the static world to the dynamic world. In Figure 24, the left-hand navigation pane displays targets in the same color as the graph. The lower pane displays the source code for the selected node (the build target in Figure 24.) Hovering over a target brings up a detailed tool tip that identifies the element type (N for node), the dependencies, and the description (the antdoc.html target in Figure 24). Hovering over links provides details of the connections between targets as well.

Grand-UI provides the same filtering capabilities as you saw earlier, but in a dynamic way; you simply select a target, and then select one of the filtering options from the Graph menu. For example, choosing Filter From Selected Node with the build target selected produces the same result as the build.doc=1 switch discussed earlier—but in Grand-UI, it immediately redraws the graph (see Figure 25).

Figure 25. Grand-UI Dynamic Filtering: choosing "Filter From Selected Node" with the build target selected immediately applies the filter and updates the graph.

Grand-UI works directly from your Ant XML files. It does not require any of the four steps used within the Ant file to convert XML to PDF from the command line, but of course, it doesn't output a static file that you can embed in a documentation file or post on a web site, either. The Grand-UI does, however, allow you to export the display to a static output file in several standard graphical formats (BMP, JPEG, PNG, or GIF).

Previous Page

Next Page