1 The Cross Reference Tool
The Graphical Cross Reference Tool performs a static analysis of an Erlang program, resulting in information about:
- inter-module dependencies
- undefined modules
- intra-module dependencies, i.e. between functions a module
- unused local functions
- unused exported functions
- inter-module recursion
1.1 Purpose
The purpose of the Graphical Cross Reference Tool is to be of assistance during development and maintenance of Erlang software. It will help the developer to find undefined functions and to identify dependencies between modules and functions.
1.2 Limitations
The analysis functionality cannot handle calls to
apply
andspawn
where the applied or spawned function is a variable.The analysis cannot handle higher order functions in general. So calls to funs and functions using for instance
lists:map
will not be handled properly.The end result due to the limitations described will be that functions that are used in any of the ways described, but not defined, will not be listed as undefined, and any cross references due to such usage will not be visualized.
1.3 Invocation
The Graphical Cross Reference Tool is started by typing the following in an Erlang shell:
xref:start().1.4 The Main Window
1.4.1 Overview
The main parts of the Main Window are the Files list, the Modules list and the Functions list.
The Main Window showing a set of loaded modules.1.4.2 Files
1.4.2.1 Moving in the directory structure
- A double click on a directory name in the Files list-box will open that directory.
- Place the mouse pointer in the entry field and type in the directory name, terminated with a (back)slash and press the
Enter
key.
1.4.2.2 Loading files
To load one or more files, select a set of files and/or directories in the File list-box and then click on the right-arrow button placed to the right of the Files list.
If a directory is selected and loaded, all files with a
.erl
extension in the selected directory will be loaded, and subsequently appear in the Modules list. Since the files are analyzed as they are loaded this operation may take some time.1.4.3 Modules
The contents of the modules section is determined by the radio-buttons
Defined
andUndefined
.Depending on which of the radio-buttons is pushed, the contents of the module list will be as follows:
- If the
Defined
button is selected, all loaded modules plus any built in functions that are referenced by the loaded modules will be shown in the module list-box.
- If the
Undefined
button is selected, all modules that are referred to from other modules, but that are not currently loaded will be shown.
To view a graph of inter-module dependencies, click the
Show module graph
button. This will open a graph window showing the inter-module dependencies between the selected modules.To remove a module from the set of analyzed modules, click the
Delete module
button. This will unload the selected modules.To remove all modules from the analyzed set, click the
Delete all
button. This will unload all loaded modulesTo view modules that are mutually dependent, click the
List recursive modules
button. The occurence of mutually dependent modules may indicate poor module design.1.4.4 Functions
When a function is analyzed, one can specify how many levels of function calls that should be traced from that function.
To view a function graph, select one or more functions in the function list-box, then click the
Show function graph
button.To view all local functions that are not called, click the
List unused locals
button.To view all exported functions that are not called, click the
List unused exports
button.1.4.5 Quitting
To quit the application click on the
quit
button.1.5 The Graph Window
1.5.1 Overview
The graph window is invoked by clicking either of the two buttons
Show module graph
andShow function graph
. It's purpose is to show a cross reference graph of selected modules/functions and their dependencies.The nodes in the graph can be moved around manually. By using the functionality to relax a graph, all nodes that do not have a fixed position will be moved around automatically.
The Graph Window showing all references between a set of sample modules.The functionality in the window is the same, independent of whether it was opened for modules or for functions, with the natural difference being that they show different objects.
The modules/functions are represented as nodes in a graph, and calls between them are represented as arrows. By default no edges are shown.
The modules/functions that were selected in the main window will be fixed nodes, i.e. nodes that will not be moved around by the relax function (see below). Fixed nodes are drawn in yellow.
Red nodes are non fixed nodes. And a green nodes represent a selected module/function..
1.5.2 Graph operations
1.5.2.1 Node manipulation
To select a node, click on it with the mouse pointer.
To deselect a node, click somewhere in the graph area, or on another node to select that node instead.
To fix the position of a node, select it and click the check-box button
Fixed
1.5.2.2 Showing cross references
To show cross references between modules/functions, press one of the
Show
buttons.The buttons
Show calls to
andShow calls from
operate on the selected node, whereas theShow all calls
button will show all calls to and from all modules/functions in the set.There is also a corresponding set of
Hide
-buttons, which hides the cross references in the same manner as described above.1.5.2.3 Graph layout
To automatically rearrange the nodes in the graph, click the
Relax graph
check-box button. To end the relaxation click once more one the same button.This operation tries to minimize the edge crossings and with that making the graph more clear. It is a time consuming operation so the best thing to do is to having it run for a while, break and continue by hand.
1.5.3 Closing the Graph Window
To close a Graph Window, click the
Close
button.1.5.4 See Also
There is also a brief reference page for the Graphical Cross Reference Tool in the module
xref
.