cflow2vcg

Whenever one has to work with applications which use more than 10-15 functions, it becomes difficult to understand the calling relationship between function. This is more even more so for free software, where the code is often the work of another person, and sometimes more than one. At times the code is well documented (comments, design documents, etc ). But often that is not so and the code is hard to understand for a new developer. To work with this sort of software, one of the indispensable tools to help understand it is the call tree.

A call tree is - as the name suggests, a tree-like representation of the calls between functions. There are two types of call trees:

The static call tree : it represents all the possible calls as defined by the source code (including those which are never accessed because the conditions which would lead to their invocation are never fulfilled)
The dynamic call tree : it represents all of the actual calls invoked when a program is executed.

UNIX© platforms have utilities to produce such call trees ( e.g. cflow and gprof). However, their output (in text format) is, although perfectly usable, somewhat difficult to handle. Particularly, because by their very nature, this information lends itself better to a graphical presentation rather than text.

1.2. cflow2vcg

The graphical representation of a tree is not a simple problem. Fortunately there is a utility which does the job very nicely: xvcg developed by I. Lemke, G. Sander<sander@cs.uni-sb.de> and the Compare Consortium and is maintained by Shantanu Tarafdar<shantanu@ece.neu.edu>.

In keeping with the UNIX philosophy, cflow2vcg provides, as simply as possible, the link between cflow and xvcg. We only concern ourselves with static call trees because dynamic trees can be produced with Call Graph Drawing Interface developed by Vadim Engelson <vaden@ida.liu.se>.

Note : Even though cflow2vcg is only in its first release, it is still is perfectly usable.I use it in my work on a regular basis as is.

1.3. License

cflow2vcg is developed and distributed under the GNU General Public License - GPL. This, among other things, allows you to adapt cflow2vcg to your needs, if necessary. In that case, I invite you to contact me at <guyou@sourceforge.net> since your modifications might be of interest to other users as well.

Chapter 2. Installation

2.1. Availability

cflow2vcg actually runs on a Sun Solaris™ platform. Considering its simplicity of the interface it employs, it should present no problems in porting it to other platforms. The major difficulty will be the output format of cflow which is not necessarily the same on all platforms. This issue has not been addressed.

Utilities like cflow exist on the GNU/Linux platforms, but are not installed by the distributions. A quick search ought to help you find it rather quickly. For myself, the cflow which I have installed does not produce the same output as the Sun Solaris™ cflow. Ways to analyze these output formats are currently being developed.

One implementation of cflow by Andrew Moore is available at:
ftp://ftp.ntua.gr/pub/linux/debian/pool/main/c/cflow/cflow_2.0.orig.tar.gz.

The latest version of cflow2vcg can handle this format.

2.2. Downloading

cflow2vcg is hosted by SourceForge. This site provides distribution and support.. Both source code and binaries are available there.

2.3. Compiling

Just like other Open Source projects, cflow2vcg uses the compile facilities offered by configure. To compile the application, simply run the usual commands :

          % gunzip -c cflow2vcg-x-x.tar.gz | tar xf -
          % cd cflow2vcg-x-x
          % ./configure
          % make

As always, you can control the compile with configure. To view the available parameters, simply execute: ./configure --help.

2.4. Installation

Install cflow2vcg in /usr/local with :

          % make install

Thanks to configure you can control the installation quite finely. For details, just execute :

./configure --help.

Chapter 3. Use

3.1. Usage

cflow2vcg [-e | -i] [-h] [-v]

cflow2vcg reads a cflow output file from its standard input and produces an equivalent vcg formatted output file to its standard output. The resulting file can be further manipulated with other applications which handle the VCG format, in particular by xvcg.

3.2. Description

3.2.1. Limiting graphs to only internal or external calls

The VCG output file produced by cflow2vcg allows you to limit the graph to only show calls to internal functions (defined in the files being analyzed) or only calls to external functions (system calls, for example). This capability is extremely useful to understanding the various modules which make up your application.

3.2.1.1. Display

Limiting the tree to display only one of these types ((internal;/external???) can be done in xvcg using the "Expose/Hide Edges... "dialog box of xvcg.

3.2.1.2. Exporting graphics

xvcg does not support limiting the output in any (???) such fashion - at least, if there is such an option, I've never found it. Because of that, cflow2vcg provides the options [-i] and [-e] to restrict the graphs it produces.

3.3. Examples

The examples are based on the cflow2vcg code. The intermediary files used to produce these examples are available in the doc directory of the distribution :

cflow2vcg.cflow output from cflow,
cflow2vcg.vcg output produced by cflow2vcg from the previous file.

3.3.1. Display

To display a graph :

            % cflow cflow2vcg.c | cflow2vcg | xvcg -

The result :

Selecting only internal nodes (either via xvcg or via cflow2vcg) :

Selecting only external nodes (either via xvcg or via cflow2vcg) :

3.3.2. Printing

To print a graph :

            % cflow cflow2vcg.c | cflow2vcg | xvcg - -psoutput file.ps
	    % lp file.ps

xvcg provides a host of parameters to control the rendition of a print. To find out more, consult the on-line documentation.

Chapter 4. Technique

The principle used by cflow2vcg (at present) is very simple. It converts the cflow output line by line to VCG instructions.

This means we need to recognize whether a line corresponds to :

a declaration or definition of a symbol, in which means we must produce a node,
a simple reference, in which case we do nothing.

In either case, we add an arc to the calling function.

Chapter 5. Final comments

5.1. Suggestions

Don't hesitate to send me your questions, comments, bug reports and such via e-mail at:

<guyou@sourceforge.net>.

5.2. To do

Major changes planned :

enhancing the VCG output file to contain the maximum information produced by cflow (Cf. Section 5.2.1),
packages (RPM),
internationalization of both the VCG output and the documentation.

5.2.1. Enhancements

At present, cflow2vcg does not use the file name of the (input??) file. This information could be stored in one of the node's 'info' fields. It would also be possible to use this information to limit the graph. This could lead to producing one graph per file. This would complicate the program since it would require that the program record this information in a structure prior to writing it to the output file

Chapter 6. Other Versions of this document