Grand:

What/Why?

Grand is a tool to create visual representation of ant target dependencies. It differs from tools like Vizant or AntGraph by a totally different approach, relying on the Ant API rather than parsing directly the XML files. This enables Grand to provide some nifty features such as the support of the ant 1.6.x tasks like import or subant.

From a user point of view, Grand can be used either as a standalone application with a nice GUI or as an Ant task generated a dot" file. In this latter case a post processing using Graphviz is required to get the actual graph.

On the right is a screenshot of the GUI displaying a very simple ant file. The left pane displays a sorted list of the targets, the lower pane the source code of the last selected node and the main one the dependency graph. In this graph, the default target is pictured in a yellow octagon, the targets with a description (main targets) in a cyan box while ovals are targets without description. The gray target is an external target located in another file but referenced by a task (subant in this specific case).

On the link side, the black ones are static dependencies (from the depends attribute) while the gray one are the dependencies created by tasks.

Images produced using the ant task can be found in the examples section.

Features

• finds both static (using the depends attribute) and dynamic (created by tasks like ant or antcall) dependencies,
• supports ant 1.6 import statement,
• supports most dependencies generating tasks: ant, antcall, subant and foreach, runtarget from antcontrib,
• available as both as an easy to install (one single jar, no extra dependency) ant task or a stand alone application with a nice SWT GUI,
• the GUI can open several files simultaneously and includes some inter files navigation features.

News

Current situation (21 Jan 2012)

It has been quite a long time since I worked on Grand. The last commits date from July 2006 (almost 6 years). I have to admit it, Grand is no longer on the of my todo list especially since I no longer use Ant in my day job.

In order not to let the project die, I decided to move it to github: Grand and GrandUI.

Mac OS X version available with JNLP (30 May. 2005)

A pre-release of version 0.8 (or 0.7.3) has been uploaded, beside an upgrade to the lastest versions of Ant, SWT, etc. this release supports Mac OS X. Since I don't have access to any machine running Mac OS X, this wasn't tested at all so don't hesitate to contact me is something goes wrong.

GUI version 0.7.2 (19 May. 2005)

• Upgrade to ant 1.6.3,
• Fixed build process.

GUI version 0.7.1 (3 May. 2005)

• Fixed a bug on Windows platforms with JDK 1.4 which prevent the display of any graph.

GUI version 0.7 (14 Apr. 2005)

• Upgraded to Grand core 1.8,
• Added a new export as image feature,
• Minor improvements and bug fixes.

Version 1.8 (11 Apr. 2005)

• Support for the new target element in ant and antcall,
• Improved behaviour when targets with the same names exists in several files.

GUI version 0.6 (17 Mar. 2005)

• Upgraded to Grand core 1.7 & and Eclipse 3.1M5a,
• Added support for mouse wheel,
• Improved Synchronization between the outline and the other panels,
• Fixed an exception when parsing a file with a <taskdef> outside of a target,
• Added a log window,
• It is now possible to specify a set of properties when opening a graph
• Minor bugfixes.

Version 1.7 (15 Mar. 2005)

• Fixed an exception when parsing a file with a outside of a target,
• Added a new filter type: removenode.

Version 1.6 (23 Dec. 2004)

• Rewrite of the dot generator,
• Subant generic links now have a specific display style.

GUI version 0.5 (16 Oct. 2004)

• Upgraded to Grand core 1.5 & and Eclipse 3.0.1,
• Added special tooltip for subant genericantfile mode,
• Added an outline panel,
• Both outline & source panels are now maskable,
• When double clicking on an external node, the corresponding build file now opens centered on that node,
• Minor bugfixes.

Version 1.5 (5 Oct. 2004)

• Support for the subant task,
• Relative paths in the dir attribute of the ant task are now handled correctly,
• The Ant task no longer crashes when no target is supplied,
• Minor bugfixes.

GUI version 0.4 (21 Jul. 2004)

• Fix a NPE when toggling bus routing,
• Added source display of the selected target,
• Added a preference dialog and allow customization of the graph rendering,
• Upgraded to Ant 1.6.2.

GUI version 0.3.1 (29 Jun. 2004)

• Replace buggy 0.3 release.

GUI version 0.3 (27 Jun. 2004)

• Double clicking on a external target now opens this target's build file,
• Page-Up & Page-Down zoom in & out on the graph,
• Added a minimal page setup dialog,
• Upgrade to Eclipse to 3.0 & GEF to 20040619,
• Code cleanup & better error processing.

GUI version 0.2 (16 Jun. 2004)

• The UI can now open several graphs in several tabs,
• Rewritten tootips for both Node & Links,
• The antcall/ant parameters are now displayed on the link's tooltip,
• Upgrade to Eclipse RCP 3.0RC2, Draw2d 20040610 and Grand (core) 1.4,
• The graph can use the bus routing capability of JzGraph.

Version 1.4 (15 Jun. 2004)

• Small bugfix release needed by forthcoming Ui release.

Version 1.3 (11 Jun. 2004)

• Major rework in the way the ant file tasks are processed,
• The nested ant, antcall & similar tasks are now correctly displayed,
• Support for the runtarget task.

Version 1.2 (04 Jun. 2004)

• Internal changes allowing to gather more information on targets,
• First release of a GUI based on Grand.

Version 1.1 (25 May 2004)

• Grand is now compiled against ant 1.6.1, although it probably still work with 1.6,
• Add the FilterChain class to handle a set of filters as one filter,
• Implements a preliminary support for ant task,
• Some code cleanup.

Version 1.0 (28 Feb. 2004)

Nothing much (again), more code cleanup (removed jikes warning when compiling the test cases), tests on ant 1.6.1 and java 1.5.0 beta.

Version 0.9 (18 Feb. 2004)

Nothing much except some code cleanup to be more checkstyle compliant. The obsolete net.ggtools.grand.App class is no longer there.

Version 0.4 (12 Feb. 2004)

• Grand supports the foreach task,
• When a target depends on a non existing one, Grand used to discard the link, starting from this release, when a target depends on a non existing target, a dummy node will be created; this node will be marked as a missing node, those nodes can be filtered out using the new missingnode filter,
• Grand has now a mechanism to set and use properties when processing dependencies,
• The propertyfile attribute from the grand task had been superseded by outputconfigfile in order to avoid confusion.

Version 0.3.1 (6 Feb. 2004)

Corrects NullPointerException issue on some build files.

Version 0.3 (5 Feb. 2004)

This version implements filters and can display antcall task as weak links.

Version 0.2 (29 Jan. 2004)

No new features but some code rewrite to ease the implementation of filters in a (hopefully) near future.

Download

The current and former releases can be fetched from the download directory.

Core/Ant task

The latest version of Grand is available as grand.tar.gz or grand.zip. Both archives contain jar and the API documentation. Alternatively the grand.jar is available separatly. Source distributions and old versions should be fetched from the download directory.

You'll also need to grab Ant. The recommanded version is 1.6.2 while Grand should work with version 1.6.0 or later.

GUI

The GUI is available in a fully package binary distribution as grand-ui.tar.gz or grand-ui.zip. Those archives should work for both Linux x86 and Windows systems. The source distributions should be grabbed rom the download directory. A snapshot version is also available through java web start.

Compilation, installation

If you want to recomplile Grand, you'll first need to install Maven. After that the compilation process should be straightforward: untar or unzip, cd to the Grand directory, and type maven jar. Maven will download the required libraries, compile the classes, run the (few) unit tests and create a jar.

As an alternative to Maven, the source archive also provides a build.xml file to be used with ant. This file had been generated by maven so it tries to mimic its behaviour. By default, this file will make ant download the dependencies. You can prevent this by running ant with -Dnoget=yes. In this case you'll have to put the following jars in the classpath or in the target/lib directory:

• ant.jar and ant-launcher.jar from ant 1.6.3 (ant 1.6.0, 1.6.1 and 1.6.2 should also work),
• from JUnit 3.8.1.

Using the ant task

To use the ant task you should first define the grand task:

<taskdef resource="task.properties" classpath="grand-0.4.jar"/>

Starting with version 0.2, the preferred method is to use antlib as it provide a way to define both tasks and types at the same time:

<typedef resource="net/ggtools/grand/antlib.xml" classpath="grand-0.4.jar"/>

Note on property defined dependencies

Starting with release 0.4, Grand can work with dependencies defined from properties like <target name="target" depends="${my.target}">. Keep in mind that the graphed file is only parsed, not executed. So no runtime defined (anything defined with the property task for instance) property will be available to Grand. The only exception is when Grand is graphing the current build file because it uses the project already loaded by Ant rather than parsing it from scratch.

The task takes the following parameters:

The grand task accept as child the standard property and propertyset elements. Those properties will be set on the process project. Keep in mind that if buildfile is not set, those properties will be actually set in the current project.

The grand task can also include one more filter element. The filters will be applied in order to the graph resulting to something similar to a and between filters. The filter can take the following parameters:

# Attributes for the graph
dot.graph.attributes=rankdir="LR"

# Default Attributes for node.
dot.node.attributes=fontsize="12"

# Dependency links
dot.link.attributes=fontsize="10"

# Weak dependency links
dot.weaklink.attributes=fontsize="10",style="dotted"

# Subant links
dot.subantlink.attributes=fontsize="10",style="dashed"

# Main nodes
dot.mainnode.attributes=shape=box,fillcolor="cyan",style="filled,bold",fontname="Times-Bold"

# Default nodes
dot.startnode.attributes=shape=octagon,fillcolor="yellow",style="filled,bold",fontname="Helvetica-Bold"

# Missing nodes
dot.missingnode.attributes=color="gray70",fontcolor="gray70"

Examples

<grand output="build.dot" buildfile="ant-build.xml"/>

The above ant snippet, will create a dot file in named build.dot from ant-build.xml. To view the graph you need to transform the dot file into something else usign the dot command. The following ant snippet convert the previously generated file into a PostScript file resized to fit on A4 paper in landscape mode:

<exec executable="dot" >
    <arg line="-Tps -Gsize=11.69,8.27 -Grotate=90 -o build.ps build.dot"/>
</exec>

From the full graph, we use a fromnode filter to keep only what target will be executed from the default main target:

<grand output="build.dot" buildfile="ant-build.xml">
    <filter name="fromnode" node="main"/>
</grand>

Below a more complex examples using two filters to only keep a small part of the graph:

<grand output="build.dot" buildfile="ant-build.xml">
    <filter name="fromnode" node="dist"/>
    <filter name="tonode" node="prepare"/>
</grand>

To do

• The current grapher configuration sucks: too close to dot, switch to generic parameters.
• Improve the processing of ant, antcall, etc.
• Many improvements to the GUI: open multiple files, better visualization, customization, etc.
• Add source visualization in the GUI.
• Create a visual execution mode in the GUI.

Javadoc

The Javadoc API documentation is available in the distributions and online. The source archives includes a few JUnit tests including some ant examples.

License

Grand is distributed under the term of the BSD License.

Contact

Don't hesitate to contact me for anything relative to grand (bug, suggestion, etc.).

Announcement Mailing List

I currently do not have an annoucement mailing list so if you like to be warned of new available versions I suggest you to use the Freshmeat subscribe to new releases service.