README.txt

Description
-----------

Grand is a tool to create visual representation of Ant target dependencies.
It works by taking a Ant build file and creating a DOT language file. This
file needs to be post-processed with Graphviz to produce the actual graph.


Usage
-----

Grand's front end is an Ant task that must be defined with the following line:

   <typedef resource="net/ggtools/grand/antlib.xml"/>

You may have to add attribute classpath="path_to_grand.jar" if the grand jar
isn't already in the classpath.

The grand task takes the following attributes:

  output            name of the output file (mandatory).

  buildfile         name of the build file to graph. If omitted, the current
                    build file will be used.

  outputconfigfile  a property file to configure the output.

  showgraphname     if true, the generated graph will have the Ant project's
                    name displayed a the graph label.

  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.

Beside these attributes, the task can take as nested elements: property,
propertyset and filter. The first two are the standard Ant elements and are
used to pass properties to the graphed project.

The filter element is used to apply filter on the full graph. The filter
element accepts the following attributes:

  name      filter name. Can be one of isolatednode, missingnode,
            fromnode, tonode, connected or prefixed; mandatory.

  node      node name. Depending of the selected filter, this attribute
            can have different meanings and may or may not be mandatory.

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 nonexistent one.
    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.

Prefixed
    Removes prefixed nodes created by <import/> in Ant 1.8+ that may
    clutter the graph. The node attribute is not used by this filter.


Examples
--------

The simplest form:

	<grand output="build.dot"/>

Create a build.dot graph file using the current build file. Add a buildfile
attribute to process another file:

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

A two filter example:

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


Known issues
------------

Subant dependencies on tasks not yet processed before invoking the grand task.
For instance in the following pseudo-build.xml:

    <target name="subant-task-1">
        <subant .../>
    </target>

    <target name="subant-task-2">
        <subant .../>
    </target>

	<target name="dograph">
		<grand .../>
	</target>

Running "ant dograph" will get all the subant dependencies, while running
"ant subant-task-1 dograph" will only get dependencies from "subant-task-2"
and running "ant subant-task-1 subant-task-2 dograph" won't get any subant
dependencies at all.


More information
----------------

The Grand web site (https://ant-grand.github.io/Grand/grand.html) contains the full
documentation for Grand with some illustrated examples and the latest version.

You can contact me at grand@ggtools.net.


Licensing
---------
 
This software is licensed under the terms you may find in the file
named "LICENSE" in this directory.