What/Why?
Grand is a tool to create visual representation of Ant target dependencies. It differs from tools like Vizant or AntGraph or ant2dot by a totally different approach, relying on the Ant API rather than parsing the XML files directly. This enables Grand to provide some nifty features such as the support of the Ant 1.6+ 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 generating a DOT language 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 limegreen boxes 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 ones 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 Ant-Contrib,
- 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 file navigation features.
News
Please see the Grand and GrandUI release history. Latest versions (as well as quick download links) are displayed on the front page if JavaScript is enabled in your browser.
Download
Core/Ant task
The latest version of Grand is available as a jar file. Old versions are available in the download directory.
You'll also need to grab Ant. The recommended version is 1.8.0 or later.
GUI
The GUI is available as a complete binary distribution in a zip file. This archive should work for macOS (x86_64), Linux and Windows (both x86 and x86_64) systems. Old versions are available in the download directory.
Compilation
If you want to recompile 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 mvn package. 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, the build will download the dependencies using Ivy. You can prevent this by running Ant with -Dnoget=yes. In this case you'll have to put all jars listed in the dependency report in the classpath or in the target/lib directory.
Using the Ant task
To use the Ant task you should first define the grand task:
<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 properties (for instance, anything defined with the property task) 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 | Property file to configure the output. Mutually exclusive with outputconfigprefix. | No |
| outputconfigprefix | Prefix of project properties used to configure the output. Mutually exclusive with outputconfigfile. | No |
| showgraphname | If true, the generated graph will have the Ant project's name displayed as 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 accepts nested property and propertyset elements. Those properties will be set in the processed 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 have nested filter elements. The filters will be applied to the graph in specified order resulting in something similar to an and between filters. The filter can take the following parameters:
| Attribute | Definition | Mandatory |
|---|---|---|
| name | Name of the filter. Can be one of isolatednode, missingnode, prefixed, fromnode, tonode, connected or removenode. | Yes |
| node | Name of a node. Depending of the selected filter, this attribute can have different meanings and may or may not 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 makes a reference to a non existing one. The node attribute is not used by this filter.
- Prefixed
- Removes nodes with prefixed names created by Ant 1.8+ for targets in build files included by <import /> statement. The node attribute is not used by this filter.
- From node
- Keeps only a selected node and the nodes it depends upon. The node parameter is the name of the node to start from.
- To node
- Keeps only a selected node and the nodes depending upon it. The node parameter is the name of the node to start from.
- Connected
- Keeps only a selected node and the nodes connected to it. The node parameter is the name of the node to start from.
- Remove node
- Removes a named node (and the attached links) from the graph.
Output configuration
Currently, there are two ways to configure the output. One 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="limegreen",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="gray",fontcolor="gray"
Alternatively, properties configuring the output can be set up directly in the build file. The grand task is made aware of them by outputconfigprefix attribute of the task. It works similarly to Ant's <propertyref prefix="..."/>, except that prefix value is replaced by dot, as well. The following Ant snippet hopefully explains the concept:
<property name="grand.graph.attributes" value="rankdir='TB'"> <grand output="build.dot" outputconfigprefix="grand"/>
The Graphviz attribute values can be enclosed in apostrophes (', as in the above) or corresponding XML entities (" or ').
Examples
<grand output="build.dot" buildfile="ant-build.xml"/>
The above Ant snippet will create a DOT file named build.dot from ant-build.xml. To view the graph you need to transform the DOT file into something else using the dot command. The following Ant snippet converts 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 targets that could be executed from the default main target:
<grand output="build.dot" buildfile="ant-build.xml">
<filter name="fromnode" node="main"/>
</grand>
Below is a more complex example 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 online. The source archive includes a few JUnit tests including some Ant examples.
License
Grand is distributed under the terms of the Simplified BSD License.
Contact
Don't hesitate to contact me for anything relative to Grand (bug, suggestion, etc.).