Σοφία Graph Tools

Overview

The graphs package of Σοφία provides functionality for statically constructing graphs that encode various types of information about a program. As with many static analyses, the information contained in these graphs may be approximations. Σοφία currently provides implementations to construct two types of graphs.

The first type is intra-procedural control flow graphs (CFGs), which are used throughout the system and are necessary to implement various components such as the structural event dispatchers. These graphs can also provide useful information for program understanding. The control flow graphs produced by Σοφία each encode a basic block representation of the control flow for a method in the program, annotated with information about the control flow branches in the method. In aggregate, they yield a representation of the basic block and branch control flow for the entire program.

The second type is interclass relationship graphs (IRGs). An interclass relationship graph is a single graph constructed for an entire program to represent all of the inheritance and interface implementation relationships between classes and interfaces in a program. These graphs are used internally by the control flow graph builder to guide the advanced inter-procedural algorithms for performing type inference on exceptions to provide more precise representations of control flow caused by exceptions.

Running the Control Flow Graph builder

To run the CFG builder to build control flow graphs for a class, use the following command:

java sofya.graphs.cfg.jCFG [-tag tag] <classname|jarfile|listfile> [classname|jarfile ...]

The tag parameter may be used to associate an identifying tag with the control flow and map files in the Σοφία database. This is necessary if you intend to use the test selection tool DejaVu. If you specify a tag to the CFG builder, you must supply the same tag to any other tool which requires access to the control flow and map files (filters, viewers, etc...).

If you include the '.class' extension when specifying a single class, it is interpreted as an absolute path name. If the extension is excluded, the class must be specified using its fully qualified name, and Σοφία will attempt to load it from the classpath. Regardless of how a class is specified, the generated database files will always reference the class by its fully qualified name. The tool will output control flow and map files for the class to the Σοφία database directory that can then be used by other Σοφία tools and viewed using the viewers described below.

The CFG builder also accepts jar files and program list files to specify the classes for which to build control flow graphs. Program list files are automatically found in the database, using the specified tag, if any. Any necessary path information should be provided when passing a jar file as an argument. When a jar file is passed as an argument on the command line, control flow graphs are built for every class in that jar. The preferred way to include classes in a jar file is to include the jar file in a program list file and supply the program list file as an argument instead, as a program list file permits you to exclude classes in the jar from processing. Any number of specific classes, jar files, and program list files can be passed to the CFG builder, though supplying a single program list file is the expected typical use.

Control flow graphs created by Σοφία can be viewed using the control flow graph viewer.

Note: The environment variable Classpath should be specified with only the current path of the program which Control Flow Graphs will be create. If the program has more than one version, you should be very careful in selecting the desired version, the classpath must contain only the path for the current version. Different versions of programs on your classpath can create unexpected results on the Control Flow Graphs.

Running the Interclass Relation Graph builder

To run the IRG builder to construct an interclass relationship graph for a program, use the following command:

java sofya.graphs.irg.jIRG [-tag tag] <listfile>

The tag parameter may be used to associate an identifying tag with the resulting graph in the Σοφία database; this is optional. Note that the control flow graph builder handles the creation of these graphs internally, as necessary.

The listfile is a program list file containing the names of the classes and interfaces for which the interclass relationship graph is to be constructed. It is found in the database directory, using the specified tag, if any.