samer@0: This package provides library(callgraph), a tool for compiling a graph of calls between predicates in a module.
samer@0: 
samer@0: ---++++ Prerequisites
samer@0: 
samer@0: The graph layout programs from the GraphViz library (http://graphviz.org/) are
samer@1: used to render the end result. Whilst you can produce a dot file without them,
samer@0: you will need them for the final rendering. 
samer@0: On Mac OS X with MacPorts installed, do this at the bash prompt.
samer@0: ==
samer@0: $ sudo port install graphviz
samer@0: ==
samer@0: On Debian based systems, do this:
samer@0: ==
samer@0: $ sudo apt-get install graphviz
samer@0: ==
samer@0: And so on.
samer@0: You will need a PDF viewer to see the results.
samer@0: 
samer@0: 
samer@0: 
samer@0: ---++++ Simple usage
samer@0: 
samer@0: To produce a call graph as a PDF, make sure that both this module and the
samer@0: module you wish to analyse are loaded, then do this:
samer@0: ==
samer@0: ?- module_dotpdf(<module_name>,[]).
samer@0: ==
samer@0: This will produce a PDF file <module_name>.pdf in the current directory.
samer@0: Often, the default layout program, dot, will produce a very wide graph.
samer@0: This can sometimes be alleviated by using the unflatten program from the
samer@0: Graphviz tools. In module_dotpdf/2, the default layout method does actually
samer@0: use unflatten without any parameters, but if this is not enough, you can
samer@0: provide values for the -f, -l and -c switches of unflatten (see the man
samer@0: page for unflatten for more details). For example, to produce a graph of 
samer@0: callgraph itself, you can try the following:
samer@0: ==
samer@0: $ swipl
samer@0: ?- use_module(library(callgraph)).
samer@0: ?- module_dotpdf(callgraph,[method(unflatten([fl(4),c(4)]))]).
samer@0: ==
samer@0: 
samer@0: ---++++ Output formats
samer@0: 
samer@0: If you want the dot language source file, use module_dot/2 instead. The
samer@0: method option is then inapplicable.
samer@0: 
samer@0: The code can also produce rendered graphs in any format supported by
samer@0: Graphviz, but this functionality is not currently exposed.
samer@0: 
samer@0: ---++++ Limitations
samer@0: 
samer@0: The graph compilation relies on prolog_walk_code/1 to do the actual code
samer@0: analysis. This does a good job in most cases, using meta-predicate declarations
samer@0: or inferred meta-predicates to detect many high-order calling patterns.
samer@0: Ironically enough, callgraph fails to analyse itself fully because
samer@0: prolog_walk_code/1 does not detect that it itself calls a given predicate
samer@0: for each call detected. Thus, in the example, there is no edge from 
samer@0: assert_module_graph/1 to assert_edge/4.
samer@0: 
samer@0: ---++++ Planned enhancements
samer@0: 
samer@0: The main thing to add next is to render graphs for multiple modules using dot's
samer@0: subgraph facility. Otherwise, the system for dealing with style attributes is
samer@0: a bit messy and could be cleaned up.