In this tutorial, we write ccvisu.sh for java -jar CCVisu-3.0.jar. If no command-line option is given, CCVisu opens a GUI to enter necessary parameters, e.g., an input file to operate on. A double-click on the jar file in a file browser should do the same.
Relational Standard Format (RSF) is a common exchange format for relations. RSF is used by many relation-based tools, for example, the relational programming tool CrocoPat and the re-engineering tool Rigi (Rigi Standard Format). RSF is based on plain text with whitespace (most common: tabs) as delimiter, which makes it easy to process data on the command line with standard Unix tools like grep, cut, and sed.
When CCVisu is used to produce layouts (visualizations), it expects input graphs in one of the following file formats: Relational Standard Format (RSF), Doxygen XML format (DOX), Subversion log format in XML (SVN), and CVS log format (CVS). Since CCVisu uses RSF as file format for data exchange, it can export (to RSF) relations that it extracted from one of the above mentioned input formats.
Open Document Spreadsheet (ODS) to RSF Converter.
For example, given a file
which is an ODS file that contains one table sheet named ’CO-CHANGE’
with several columns representing a relation.
Then the command
ccvisu.sh -informat ODS -i crocopat-2.1.ods -outformat RSF -o crocopat-2.1.rsf
produces a file crocopat-2.1.4.rsf, which contains the co-change graph that CCVisu extracted from table sheet ’CO-CHANGE’.
Doxygen (DOX) to RSF Converter.
For example, given a directory
of XML files that was produced using the command doxygen Doxyfile,
is an example configuration file for Doxygen.
(Doxygen usually generates a directory xml which contains a file index.xml.)
Then the command
ccvisu.sh -inFormat DOX -i crocopat-2.1.4-dox/index.xml -outFormat RSF -o crocopat-2.1.4.rsf
produces a file crocopat-2.1.4.rsf, which contains the relations that CCVisu extracted from the Doxygen output.
CVS to RSF Converter.
For example, given a file
which is a CVS log file of
CrocoPat and was produced using the command cvs log -Nb.
Then the command
ccvisu.sh -informat CVS -i crocopat-2.1.log -outformat RSF -o crocopat-2.1.rsf
produces a file crocopat-2.1.4.rsf, which contains the co-change graph that CCVisu extracted from the CVS log file. As example for how an RSF file looks like we show an extract from the generated co-change graph of CrocoPat:
CCG 125 src/bddSymTab.h CCG 126 src/Makefile CCG 126 src/relLex.l CCG 127 src/crocopat.cpp CCG 127 src/relExpression.h CCG 127 src/relLex.l CCG 127 src/relYacc.y
Subversion (SVN) to RSF Converter. TODO
Other Fact Extractors. There are many tools available for graph extraction from software systems. Examples are: cawkcg, GCT, Imagix, Rigiparse, Field, cflow, CIA, LSMEcg, Mawkcg, Portable Bookshelf (grok), Doxygen, DepFinder, java2rsf.
Comparison of Fact Extractors. A good (but somewhat outdated) comparison of fact extractors was done by Murphy et al. [MNGL98].
Generate a Layout.
Once we have the input graph in RSF or in one of the above mentioned formats,
the next step is to run
CCVisu on the input graph in order to produce a (clustering) layout for the software graph.
For example, consider the dependency graph of a (small) compiler system (extracted using
Bauhaus) in file
If we run
CCVisu using the command line
ccvisu.sh -informat RSF -i compiler.rsf -outformat DISP -iter 100,
a screen display will open and show the resulting layout, running 100 iterations of the minimizer. Since RSF is the default input format, and DISP (screen DISPlay) is the default output option, and by default it runs 100 iterations, the following command does the same: ccvisu.sh -i compiler.rsf
Save a Layout. CCVisu supports several different output formats: LAY (plain text format), SVG (2D Scalable Vector Graphics), VRML (3D format). Any layout that CCVisu shows on the screen can be saved to a file in one of these formats, by opening the corresponding SAVE dialog and giving a filename to store the layout in the file. The filename extension .lay, .svg, or .wrl determines the file format.
Force-directed graph layout consists of two parts: an energy model that assigns an energy value to each layout for evaluation —the smaller the number, the better the layout—, and a minimizing algorithm that computes a layout with minimal energy.
A tool for force-directed graph layout takes as input a graph (undirected, connected, irreflexive). Another parameter of the tool is the energy model, which encodes the user’s requirements for ‘good’ layout, e.g., uniform edge-length or interpretable distances. The output of the tool is a layout that has minimal energy according to the energy model.
CCVisu is such a tool for force-directed layout. It uses the well-known algorithm of Barnes and Hut as minimization algorithm, and it provides several standard energy models, and lets the user define (optional, per command line) certain parameters of the energy model, in order to adapt it to the user’s application area.
Chain. Consider first a graph that forms a chain, i.e., a connected graph
where the first and the last vertex has one edge and all other
vertices have two edges.
Figure 1 shows the graph (on the left) and
the resulting layout (on the right).
To produce this result, the tool
CCVisu was invoked with the following
command line (start java interpreter with class CCVisu of package ccvisu,
read the input graph in RSF format from file simple-chain.rsf,
and use the attraction exponent 3 in the energy model,
cf. Section 6.2, Generic Model):
ccvisu.sh -i simple-chain.rsf -attrExp 3
An energy model usually consists of two terms, one is interpreted as the energy resulting from an attraction force, and the other is interpreted as the energy resulting from a repulsion force. In the example, the attraction force ensures that neighboring vertices in the chain have closed positions in the layout (e.g., vertices 1 and 2). The repulsion force between each two vertices ensure that vertices that are connected by a long path have distant positions (e.g., vertices 1 and 20).
R 1 2 R 2 3 R 3 4 R 4 5 R 5 6 R 6 7 R 7 8 R 8 9 R 9 10 R 10 11 R 11 12 R 12 13 R 13 14 R 14 15 R 15 16 R 16 17 R 17 18 R 18 19 R 19 20
3times two. todo
CrocoPat’s Co-Change Graph. Now we consider the co-change visualization of the tool CrocoPat1. The input is the CVS log file of the version history, obtained using the command cvs log 2. The co-change visualization can be either computed and displayed in one direct step:
ccvisu.sh -inFormat CVS -i crocopat-2.1.log -hideSource
or obtained by several steps (to store intermediate results for later reuse):
ccvisu.sh -inFormat CVS -i crocopat-2.1.log -outFormat RSF -o crocopat-2.1.rsf
computes the co-change graph and stores it into a text file in RSF format.
ccvisu.sh -inFormat RSF -i crocopat-2.1.rsf -outFormat LAY -o crocopat-2.1.lay -hideSource
computes the layout and writes it to a text file in LAY format. The option -hideSource hides the change transaction vertices in the visualization.
ccvisu.sh -inFormat LAY -i crocopat-2.1.lay -outFormat SVG -o crocopat-2.1.svg
converts the layout in LAY format to a vector graphics in SVG format.© Dirk Beyer