Code Graphs to Vizualize Your C Code

R. J. Brown -- Elijah Laboratories Inc.

The code_graphs package is a set of bash and perl scripts that generates interactive graphical representations of C source and object code. These graphs are in the form of a set of pdf files. They are intended to be viewed interactively in a web browser equiped with a plug-in for a pdf viewer.
I find that Adobe's acroread is the best tool for this because it supports panning and scrolling using the mouse in "palm" mode, and it supports zomming in and out with the mouse wheel. The combination of these operations provides you with the ability to explore these intracate graphs in as much detail as you desire.
For any of these graphs, there will be a "table of contents" frame to the left of the graph containing the names of the nodes in the graph. You may click on any of these entries to view the maximal subgraph that contains only that node, together with its direct and indirect predecessors and successors.
These graphs fall into the following groups:

Module Graph
This shows a node for each object file, or object module, in the program. Edges show which object files reference which other object files, allowing you to easily determine why a particular file was included in the link.

Include Graph
This shows a node for each source file in the program. Edges show which file includes which file, and which function is called by which function. This helps you determine why a particular #include file is included into a compilation. It also helps you during development by alerting you when the graph becomes a terrible tangled mess to the realization that you need to clean up your #include heirarchy.

Call Graph
This shows a node for each C function in the program. Edges show which function calls which function, and which function is called by which function. This allows you to determine which functions will be called as a result of calling another function. Each function node is labeled with the function name, the module name (C source file name) where that function is defined, and the size of the stack frame which that function allocates when it is called.

This is useful for testing and maintenence. It is also useful during development by letting you visualize the calling structure of your program while you are developing it. This helps you better factor your code for easier maintenence and understanding.

If the program contains recursion, the nodes representing the functions participating in the recursion will be highlighted in pink, and the edges representing the calls between such functions will be highlighted in red.

If the program is not recursive, then each function node will be further annotated with the worst case maximum cumulative stack size possible that could be used when that function is called via the worst-case sequence of function calls. The sequence of function callls that realizes the greatest size of the stack will be made visually apparent by having the edges representing those function calls highlighted in red.

If the program is recursive, then it is not possible to determine the worst case stack size obtained, since there is no way to determine the possible depth of recursion that could occur by using only a static analysis of the code.

Linkage Graph
This shows a node for each object module in the program, and for each global symbol in the program. Edges show which symbols are exported and imported by any given object module. Colors and shapes distinguish object modules, defined function names are in red. Undefined function names, such as names defined in a library that is not actually part of the build, are in white. Variables appear in green if they are read-only, and in yellow if they are both read and written to. Object modules are in blue. Black edges are imports of a symbol into an object module, and red edges are exports of a symbol from an object module.

Source Listings
This is not a graph at all, but a pretty printed set of source files for the program.

The following demonstrations of code_graphs are provided so you can see what it will do:
The Gnu cflow utility
This contains a bison parser, and is highly recursive, exhibiting very complex recursion.

The iq_test utility -- recursive
This is a demonstration of an A* heuristic state space graph search algorithm from the domain of artificial intelligence. This program is not really recursive, but it uses a single recursive function to display the results.

The iq_test utility -- non-recursive
This is the same program as the one above, but with the call to the recursive output function commented out, so that the program becomes totally non-recursive. This causes the recursion highlighting to be bypassed, and instead, a stack usage analysis is displayed, with the worst case stack usage sequence of function calls highlighted instead of the recursive function calls.

Gemsvnc -- A Framebuffer Relay Server
Unlike most Unix hosted VNC servers, which are also X-servers, and serve an X environment that they maintain internally, gemsvnc, like its predecessors x0rfbserver and x11vnc, which is distributed with libvncserver, is only a VNC server, but not an X-server. It attaches to an already running X-server and permits remote control of that X-server from the vncviewer. This is desirable when one is using vnc for a customer service or training tool, or where special graphics hardware (such as openGL) is being used so that a normal vncserver would not work.

This is a "real life" size program that I wrote in 2002 for a client. Because it is derived from GPL-ed code, it too is under the GPL. I wish I had had back then, as it shows that there is some potential recursion that is not intended. Oh well, the Gensvnc server does work, and the client was happy.

You may fetch the source code for the code_graphs package and try it out on your own programs.

NOTE: The determination of the stack frame size for each function is highly compiler and target CPU dependent. The script provided, stack_frame.sh, is only designed to work with the Gnu gcc compiler compiling C, not C++, source code, and an amd_64 target CPU. Other compilers, CPUs, and architectures will require changes to this script. It is the author's hope that over time, such other scripts will be developed.