Call graphs (call multigraphs)

This module examines XQuery modules and creates an SVG representation of their respective call graphs. These call graphs are useful as an overview of how the SADE app and project specific extensions work and can be used as illustration of the app's architecture, for improving a module's structure while developing, ...

To meet the different needs of users, three ways of using this module are possible:

You can create the call graph of

  • a single module
  • all modules that belong to a collection
  • the whole SADE app

Requirements

Please make sure you have GraphViz installed wherever the database runs (on your computer, on a VM, ...).

Configuration

For the module to work properly you have to consider on which kind of operating system (Windows, Unix, MacOS, ...) the database runs. Simply change the following line in config.xml to the command line invocation of dot that is used by your OS:

<param key="dot-cmd">dot</param>

The option defaults to Unix' dot command.

How to create call graphs

Before using the call graph module please make sure you have the module imported with

import module namespace callgraph="https://sade.textgrid.de/ns/callgraph" at "$(path/to/module)/callgraph.xqm";

To generate a call graph all you have to do is calling the function

callgraph:main("/some/input/as/string", "filename/as/string")

where the first input parameter can be the following:

  • the base URI of a single module, e.g. /db/apps/sade/modules/some-module.xqm
  • the URI of a collection as path, e.g. /db/apps/sade/modules/my-project-collection
  • full (generates a call graph for the whole SADE app)

The second parameter is the desired filename without file extension.

The call graph SVG is stored to /db/apps/sade/modules/callgraph/svg while the GraphML representation can be found at /db/apps/sade/modules/callgraph/graphml.

How it works (in detail)

Depending on which input option you select (cf. "How to create call graphs" above) one or more modules are examined by eXist-db's inspect:inspect-module function which returns some information about the module(s) and its functions.

This information is then converted into a GraphML representation of the module as a directed graph in which all calling and called functions are represented as a graphml:node element. In case several modules are inspected duplicates are avoided. The calling/called connection between two functions is denoted by a graphml:edge element where the calling function becomes the edge's @source and the called one the edge's @target.

This GraphML document is then saved to /db/apps/sade/callgraph/graphml and serves as input for generating a DOT representation of the graph which in turn is used by dot to create an SVG file that is saved to /db/apps/sade/callgraph/svg.

Sample output

The following image has been generated by the callgraph-module and illustrates how its modules and functions interact:

Call graph