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.
|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|| || |
|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
) 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.|
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.
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">
<target name="xml2dot.doc" if="build.doc"
"converts xml to dot format for DOC targets">
<filter name="fromnode" node="build"/>
<target name="xml2dot.nondoc" if="build.nondoc"
"converts xml to dot format for non-DOC targets">
<filter name="fromnode" node="a"/>
<target name="xml2dot.m5" if="build.m5"
"converts xml to dot format for targets to m5">
<filter name="tonode" node="m5"/>
|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.|
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).