NAME

egypt - create call graph from gcc RTL dump

SYNOPISIS

 egypt [--omit function,function,...] [--include-external] <rtl-file>... | dotty -
 egypt [--omit function,function,...] [--include-external] <rtl-file>... | dot <dot-options>

DESCRIPTION

Egypt is a simple tool for creating call graphs of C programs.

OPTIONS

omit
Omit the given functions from the call graph. Multiple function names may be given separated by commas.

include-external
Include calls to external functions in the call graph. A function is considered external if it is not defined in any of the input files. For example, functions in the standard C library are external. By default, such calls are not shown. Even with this option, only direct calls will be shown; there is no way to show indirect calls to external functions.

HOW IT WORKS

The two major tasks in creating a call graph are analyzing the syntax of the source code to find the function calls and laying out the graph, but Egypt actually does neither. Instead, it delegates the source code analysis to GCC and the graph layout to Graphviz, both of which are better at their respective jobs than egypt could ever hope to be itself. Egypt itself is just a small Perl script that acts as glue between these existing tools.

Egypt takes advantage of GCC's capability to dump an intermediate representation of the program being compiled into a file (a RTL file); this file is much easier to extract information from than a C source file. Egypt extracts information about function calls from the RTL file and massages it into the format used by Graphviz.

GENERATING THE RTL FILE

Compile the program or source file you want to create a call graph for with gcc, adding the option ``-dr'' to CFLAGS. This option causes gcc to dump its intermediate code representation of each file it compiles into a a file.

For example, the following works for many programs:

   make clean
   make CFLAGS=-dr

Depending on the GCC version, the RTL file for a source file foo.c may be called something like foo.c.rtl, foo.c.00.rtl, or foo.c.00.expand.

VIEWING THE CALL GRAPH

To view the call graph in an X11 window, run egypt with one or more .rtl files as command line arguments and pipe its output to the dotty program from the Graphviz package. For example, if you compiled foo.c with gcc -dr to generate foo.c.00.rtl, use

    egypt foo.c.00.rtl | dotty -

PRINTING THE CALL GRAPH

To generate a PostScript version of the call graph for printing, use the dot program from the Graphviz package. For example, to generate a callgraph in the file callgraph.ps fitting everything on a US letter size page in landscape mode, try

   egypt foo.c.00.rtl | dot -Grotate=90 -Gsize=11,8.5 -Tps -o callgraph.ps

Sometimes, the graph will fit better if function calls go from left to right instead of top to bottom. The dot option -Grankdir=LR will do that:

   egypt foo.c.00.rtl | dot -Gsize=8.5,11 -Grankdir=LR -Tps -o callgraph.ps

For nontrivial programs, the graph may end up too small to comfortably read. If that happens, try N-up printing:

   egypt foo.c.00.rtl | dot -Gpage=8.5,11 -Tps -o callgraph.ps

You can also try playing with other dot options such as -Gratio, or for a different style of graph, try using neato instead of dot. See the Graphwiz documentation for more information about the various options available for customizing the style of the graph.

READING THE CALL GRAPH

Function calls are displayed as solid arrows. A dotted arrow means that the function the arrow points from takes the address of the function the arrow points to; this typically indicates that the latter function is being used as a callback.

WHY IS IT CALLED EGYPT?

Egypt was going to be called rtlcg, short for RTL Call Graph, but it turned out to be one of those rare cases where ROT13'ing the name made it easier to remember and pronounce.

SEE ALSO

gcc, dotty, dot, neato

COPYRIGHT

Copyright 1994-2006 Andreas Gustafsson

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Andreas Gustafsson