I have always been fascinated by informational graphics. Mathematicians aside, most people find properly rendered information graphics easier to assimilate and quicker to understand than raw data, in whatever form that raw data may come in. This article applies concepts of data visualization to source code—not to what typically first comes to mind as source code (e.g. Java, C#, etc.) but rather the source code of an Ant build file.Build files are notorious for being difficult to create, maintain, and understand, but you’ll see a variety of techniques for visualizing or rendering an Ant file—some textual and some graphical—that will simplify the creation, maintenance, and comprehension of your build files.
The Art of Obfuscation
Most designers and developers endeavor to produce clearly written and maintainable code. But sometimes you want to deliberately produce incomprehensible code. Two reasons come to mind:

• To help protect intellectual property rights where it is unavoidable that your code will be accessible.
• To amuse and befuddle colleagues and associates, or take part in any of a number of annual contests just for fun.

The canonical example showing how graphics improve raw data comprehension is to show a table of numbers and then show a chart of those numbers, letting readers see how the chart shows trends at a glance that are much tougher to tease out from the raw numbers. But as software designers, perhaps you’d appreciate a more topical example; take a look at this C code:

   _(__,___,____){___/__<=1?_(__,___+1,____):! (___%__)?_(__,___+1,0):___%__==___/ __&&!____?(printf("%d ",___/__),_(__,___+1,0)):___%__>1   &&___%__<___/__?_(__,1+___,____+!(___/__%(___%   __))):___<__*__?_(__,___+1,   ____):0;}main(){_(100,0,0);}

I am sure you would agree that the purpose of the preceding code is not terribly self-evident! It was, in fact, deliberately obfuscated from the following code:

   void primes(int cap) {       int i, j, composite;       for(i = 2; i < cap; i++) {           composite = 0;           for(j = 2; j < i; j++)                composite += !(i % j);           if(!composite)               printf("%d	", i);       }   }      int main() {        primes(100);   }

These two code samples show that different views of the same data may transmit very different amounts of information. (Final aside on that: if you want to learn how to write obfuscated code, a good starting point is the article “Writing highly obfuscated code in Perl.”) This example is a bit extreme, of course, but it illustrates the point that well-written code—or more accurately, well-presented code—communicates more effectively than its counterpart.

That point holds true for other types of code as well, such as Ant files. In the tradition of classic programming tool nomenclature, “Ant” is a short acronym for Another Neat Tool.. Ant is an XML-based language for specifying how to compile complex software systems. Its predecessor make has been around since the early days of Unix, but was particularly unfriendly to edit (primarily because it was extremely finicky about the uses of spaces and tabs). Ant, on the other hand, uses standard XML syntax and, as you will soon see, has a variety of self-documentation tools, thanks to the extraordinary efforts of Ant aficionados.

Each section here describes a single visualization technique for Ant, beginning with a nutshell table summary. The summary should prove useful if you want to revisit this material later as a reference without having to read through the text in detail. The Rating column values are on a scale from one (worst) to five (best).

The small (206KB) downloadable code archive accompanying this article includes the collection of Ant build files along with the output for each technique discussed. For your convenience, a second, much larger (8.5MB) code archive includes both the Ant build files and all the external jar files you’ll need.

Ant Pretty Build: An Ant-Aware IE Overlay
Internet Explorer (IE) provides native support for rendering any XML file, with syntax highlighting and a mechanism to expand or collapse arbitrary nodes (see Figure 1). IE’s XML display is a good starting point, but has only rudimentary interactivity, so developers created Ant Pretty Build, an XSL style sheet that lets IE render the Ant XML in a form that lets you view and execute targets.

Figure 1. Default Internet Explorer XML Rendering: The browser applies syntax highlighting to the Ant XML and lets you expand or collapse any node.

Ant Pretty Build leverages the power of XSL to render a deceptively simple list of properties and targets. To take advantage of it, you need add only two lines of code to the very beginning of your Ant file—and if you’re a stickler for well-formed XML, you may already have the first line, which just specifies the currently universal XML version. The second line provides the incantation for Ant Pretty Build:

The second line instructs an XSL-aware browser to let the specified XSL file render the document. When you open the XML file in IE, the browser reads that line, and then attempts to render the XML document according to the XSL style sheet referenced in the href attribute. Note that you must provide the exact path to the XSL file as the value of the href attribute. If the path is incorrect, IE indicates an error (see Figure 2).

Figure 2. Invalid XSL Path: If you reference an invalid XSL style sheet in your XML, the file no longer renders.

Figure 3. Ant Pretty Build Default View: This browser-based GUI lets you review targets as well as execute them.

Figure 3 shows the Ant file when the XSL file is referenced properly. This solution works only in XSL-aware browsers such as IE that honor xml-stylesheet XML processing instructions. (It does not work in Opera, for example.) Unlike IE’s default rendering of an XML file where all nodes are expanded, Ant Pretty Build takes the opposite approach, displaying the document with all elements collapsed. The default screen, shown in Figure 3, is divided into two regions. The top region provides the key details of your top-level project node, including the name, description, base directory, and default target.

Figure 4. The Working Area: Clicking on each sub-region title reveals its content for editing and/or execution.

The bottom region of Figure 3 shows three collapsed sections for viewing/editing properties, viewing/ordering/executing targets, and for execution parameters, respectively. Figure 4 shows all three sections expanded. The Properties section displays all the properties defined in your Ant file. But they aren’t just displayed—you can actually edit their values! Furthermore, you can add additional custom properties using the plus button at the bottom of the properties list. Changes you make in the GUI won’t damage your original file; you are working with a temporary copy. But the editing feature provides a great mechanism for testing and experimenting with a build file.

The Targets section presents a list of all your project’s targets, both public and private. Surprisingly, neither this tool nor any of the others makes any notable distinction between public targets and private targets, even though the distinction is just as valuable in a build file as it is in regular source code. An Ant file user should neither know nor care about internal targets. My convention, which I will refer to throughout, is that a target should be advertised as part of your build API if and only if you assign a description attribute to that target. Any targets without descriptions are considered internal or private. Therefore, the init target is private in Figure 4 and the other three targets are public.

Ant Pretty Build does more than just list targets, however; it also executes them. The button and checkbox in each target row give you control over the order of execution. Normally, a build file will define its own ordering among dependent targets, but this GUI provides the flexibility to run individual targets, independent targets, or private targets, and to specify the ordering. The button alongside each target executes just that single target. The checkbox gives you a way to number that target, preparing it for a multiple-target execution, which you launch with the Run button in the Run section. The Run section also lets you control the logging of the run.

Figure 5. Ant Execution Window: If you elect to log output to a file, the command window shows essentially no output.

When you execute one or more targets from this GUI, it opens a command window and executes in that context. The “Close when done” checkbox refers to that separate command window, not the GUI itself. If you specify a log file in the Run section all output goes to the log rather than the console, so the command window will be decidedly uninteresting (see Figure 5).

Here’s the log file from executing the sample Ant file in Figure 1 (with a few extra lines added to the sample Ant file so it generates some output):

   init:        [echo] init: Creating directory M:devxantantdemouild      [concat] This is introductory text      [concat] for our simple ant build.      init:        [echo] init: Creating directory M:devxantantdemouild      [concat] This is introductory text      [concat] for our simple ant build.      compile:        [echo] compile: Compiling M:devxantantdemosrc directory to         M:devxantantdemouild      BUILD FAILED   M:devxantantdemouild-stylesheet.xml:33:       srcdir "M:devxantantdemosrc" does not exist!      Total time: 0 seconds

Ant Pretty Build goes a step beyond just presenting a summary of the build file API, giving you a compact, lightweight GUI for executing Ant.

Ant’s Intrinsic Help Facility
Yet another approach that takes virtually no installation is the -projecthelp option of Ant itself.

Figure 6. Ant’s Built-In Help: The “-projecthelp” command-line option reveals the public API of your build file.

Figure 6 shows the output for the build file in Listing 1, which displays the project description, all the public targets, and the default target. This is very basic output, of course, but it does two things very well: It presents a summary of what the build file does, and it shows only the public API.

Not satisfied to leave well enough alone, however, I prefer the convention of many command-line tools, which is that when you don’t provide any arguments, the command simply describes its own usage and nothing else. With Ant, you could certainly argue that you want your build file to default to a specified action (as you’ll see in several examples shortly) but I think it’s useful to learn how to make help the default because this tip is rather obscure to track down if and when you need it.

The sample build file shows how you can make the help target the default. Simply set the default attribute to the help target and define the target as shown. (I have called it “help” but you are free to name it anything as long as you update both the target name and its reference.)

                     simple example build file            

Figure 7. Help Target Output: After you instrument the code with a “help” target, launching Ant with no arguments gives you the same result as using the “-projecthelp” argument.

        . . .   

With this target installed in your build file, you can then invoke the build file with no arguments and get the same output that the -projecthelp argument would return, as shown in Figure 7.

AntDoc API
Ant Pretty Build and Ant’s projecthelp both present the essential API of your build file—the targets and their descriptions. Both provide an essentially static summary with no possibility for discerning any further details. If you have used Javadoc (or Ndoc or other similar tools that generate a documentation set from your source code) you will instantly appreciate the added capability of AntDoc. It creates a hyperlinked set of HTML documentation in the style of Javadoc.

AntDoc renders an excellent presentation of your build file, but it does require some setup. You will need the AntDoc.jar and log4j.jar files available on the AntDoc site, as well as the xalan.jar and serializer.jar files available from Apache’s Xalan site (and AntDoc does not even mention these as requirements). You must put serializer.jar in the same directory as xalan.jar, but the location does not need to be referenced in your CLASSPATH. Speaking of CLASSPATH, you need to set the CLASSPATH externally rather than use the classpath attribute of the element. (It should execute just as well either way, but I could not get it to work without explicitly defining the CLASSPATH.)

After setting up AntDoc, you can generate AntDoc documentation for your build by just defining and executing an task within Ant itself, as shown in the sample code below:

                   simple example build file                                                    Build complete                                                            

           antdoc complete.                                                                                                                                                                                                                                   

Figure 8. An AntDoc Build: The first invocation shows the output from a typical execution; later invocations skip the build if the build file has not changed since the last execution.

The preceding code contains an added dependent clause to make the build conditional; AntDoc will execute only if the build file has changed since the last time you ran it. Figure 8 shows the results of a typical AntDoc execution—twice, so that you can see it skip the build the second time around (the red numbers indicate the two runs).

So what does AntDoc actually deliver? Quite a lot. Figure 9 shows the home page of the generated application set for the sample build file. The page has the standard three-pane layout of Javadoc, with projects in the upper left, targets in the lower left, and the current project or target in the main, right-hand pane. As you click on items in the navigation panes, the main pane changes to show the selected item.

The following brief walkthrough should serve to show you how powerful AntDoc’s visualization of your build files can be.

First, click on a simple target, the help target (see Figure 10). The main pane renders this selected target in three sections: the name, the description, and the source code.

But wait; it gets better! Now select a more complicated target, the build target. As shown in Figure 11, you can see that the top section of the main pane shows not only the name of the target, but also its hierarchy. (The help target in Figure 10 had no connected tasks, so it just displayed the name.) Each of the connected targets is a hyperlink—both in the top hierarchy section and in the bottom source code section—so you can click any link to jump to the documentation for that element.

If, for example, you click either of the antdoc.html links from Figure 11, you will jump to that documentation page (see Figure 12). Note that the hierarchy at the top is now relative to the newly displayed target. So you may “drill down” via hyperlinks to each connected task. Figure 12 adds one more feature to the display. Notice the hyperlink on the echo task near the bottom of the Detail section.

Figure 12. Drill-Down Capability: The relative hierarchy in the top portion of the display lets you drill down to other connected targets.

Figure 13. Linked Tasks: Clicking a linked task displays the standard Ant documentation for that task.

Figure 14. Usage Page: The Usage page summarizes and provides hyperlinks to the tasks used for each target.

AntDoc not only connects your targets together in a hyperlinked web, it also connects your build file to the Ant documentation set for all standard Ant tasks. Clicking on the echo link, therefore, opens the documentation for the echo task itself (see Figure 13).

Next, scroll to the top of any page in the documentation set and you will see some standard links (see Figure 14). Clicking the Usage link displays a summary of standard Ant tasks that you have used, and which targets they are used in. Again, all of these are hyperlinked so you may jump between your targets and Ant’s tasks.

Finally, access the project page by clicking the project name in the upper-left navigation pane (see Figure 15). This page lists the targets in the rightmost column, labeled curiously as “Description.” The description column actually includes both the name and the description of each target. The Depends and Runtime columns present essentially identical information, the former in a tree format, and the latter in a linear sequence.

AntDoc lets you execute Ant targets in a manner similar to Ant Pretty Build; however, that’s not where AntDoc shines. You need to perform some setup before you can press any of those buttons you can see in the Run column in Figure 15. It’s not obvious where to find the documentation for the run-time setup, so here’s the link: http://antdoc.free.fr/AntDoc_documentation_content.php. In a nutshell, you need to launch a separate application—the AntDocGUI—then connect to that application on the project page (see Figure 15), and only then may you execute your selected target. That’s fine in theory but in practice it requires some fiddling with the configuration. Also, the batch file provided to launch AntDocGUI for Windows failed because my Ant installation was in the standard “Program Files” location, and the batch file is missing quotes around the path, so the space in the name caused a problem. In the end, I was not able to get the AntDocGUI program to run. However, given the excellent quality of the rest of AntDoc, I am certain that AntDocGUI would run quite well if its documentation was able to get this humble developer through the appropriate hoops.

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.

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):

          simple example build file                                                                                                                                                                                                                                             . . .      

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:

Figure 17. Moderately-Complex Build Graph: This graph of a moderately complex build file generated with ant2svg is busy but still useful.

. . .

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.

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.

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.

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.

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   

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:

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).

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).

Ant Visualization Wrap-Up
You’ve seen a variety of techniques for visualizing an Ant build file, each of which provides a unique perspective of your Ant source code. One reason for writing this article was to explain and examine these very practical techniques, but another was to instill the notion that the way you visualize something has a dramatic effect on what you can do with it, how you use it, and indeed, how you even think about it.

The table below lists all the techniques discussed in this article, giving you a side-by-side comparison. No one technique is best so you may end up using a variety.