nkame / grand Goto Github PK

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" file. This file
need 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 had 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's name. Can be one of isolatednode, fromnode, tonode,
  			missingnode or connect, mandatory.
  			
  node	 	a node's name. Depending of the selected filter, this attribute
  			can have different meanings and can or cannot 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 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.


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 filters 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 (http://www.ggtools.net/grand) contains the full
documentation for Grand with some illustrated examples and the last version.

You can contact me at [email protected].


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