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.

Grand Ui screenshot thumbnail, click for full size

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. Both archives contain jar and the API documentation. Alternatively the grand.jar is available separately. 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. 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:

Attribute Definition Mandatory
output name of the output file. Yes
buildfile name of the build file to graph. If omitted, the current build file will be used. No
propertyfile Deprecated, use outputconfigfile instead. No
outputconfigfile a property file to configure the output. No
showgraphname If true, the generated graph will have the ant project's name displayed a the graph label. No
inheritall If true, the properties of the current build file will be passed to the graphed build file. The default is not to pass the properties to the graphed project. No

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:

Attribute Definition Mandatory
name filter's name. Can be one of isolatednode, fromnode, tonode, missingnode, connected or removenode. Yes
node a node's name. Depending of the selected filter, this attribute can have different meanings and can or cannot be mandatory. No

Filters

Isolated node
Removes isolated nodes (i.e.: nodes with no links) from the graph. The node attribute is not used by this filter.
Missing node
Removes nodes created when a link make reference to a non existing one. The node attribute is not used by this filter.
From node
Keeps only a selected node a the nodes it depends upon. The node parameter is the name of the node to start from.
To node
Keeps only a selected node a the nodes depending upon it. The node parameter is the name of the node to start from.
Connect
Keeps only a selected node all the nodes connected to it. The node parameter is the name of the node to start from.
Node remover
Removes a named node (and the attached links) from the graph.

Output configuration

Currently the only way to configure the output is to use a property file to override the default configuration of the dot file writer. When overriding an attribute, the property value should be a valid graphviz attribute set. The default configuration is:

# 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>
Ant full dependency graph

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>
Ant dependencies from main

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>
Filtered Ant dependencies

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.