Login | Register   
LinkedIn
Google+
Twitter
RSS Feed
Download our iPhone app
TODAY'S HEADLINES  |   ARTICLE ARCHIVE  |   FORUMS  |   TIP BANK
Browse DevX
Sign up for e-mail newsletters from DevX


advertisement
 

Visualizing Data: Self-Documenting Ant files : Page 2

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.


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

Ant Pretty Build

TechniqueRatingDescription
Ease of Installation5Just add a reference to the Ant Pretty build XSL file in your Ant file.
Ease of Use4
  • Mostly intuitive, but useful to scan the "help" file first. (You cannot open the help file from the application, though; must go to the web site.)
  • Executing targets worked out of the box on one system, but had some security configuration issue on another.
Shows Targets4Lists targets concisely with descriptions and dependencies, but does not show source. Does not differentiate public from private targets.
Shows Connections1 
Strengths 
  • GUI embedded in IE lets you specify which targets to run, modify existing properties, or add new ones.
  • Very useful as an execution shell for Ant.
Weaknesses Shows no relationships, ordering, or source.
Sample file build-stylesheet.xml
Download The file antprettybuild-core-2.2.0.xsl

 
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:

<?xml version="1.0"?> <?xml-stylesheet type="text/xsl" href= "include/antprettybuild-core-2.2.0.xsl"?>

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:\devx\ant\antdemo\build [concat] This is introductory text [concat] for our simple ant build. init: [echo] init: Creating directory M:\devx\ant\antdemo\build [concat] This is introductory text [concat] for our simple ant build. compile: [echo] compile: Compiling M:\devx\ant\antdemo\src directory to M:\devx\ant\antdemo\build BUILD FAILED M:\devx\ant\antdemo\build-stylesheet.xml:33: srcdir "M:\devx\ant\antdemo\src" 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.



Comment and Contribute

 

 

 

 

 


(Maximum characters: 1200). You have 1200 characters left.

 

 

Sitemap