Note: Arqua is no longer maintained, take a look at https://github.com/ernstsson/Arquanator instead
Arqua is a tool used to visualize software structure and complexity.
Arqua parses RTL, an intermediate format used by gcc, and generates a graph in the dot language to be parsed by Graphviz. The graph visualizes complex functions, files and directories as well as tangles between these.
Install Arqua using make:
This will copy the script and the man page to the directory structure specified by the prefix variable (default is /usr/local).
Use the following command to get gcc to write an RTL file when compiling:
gcc -c -fdump-rtl-expand file.c
This generates an RTL file, usually with the name file.c.104r.expand (the name may vary from system to system). Now use Arqua and generate a dot file:
arqua -functions file.c.104r.expand > file.dot
The file can now be viewed directly with a dot file viewer or you can use the Graphviz tools to generate an image, for instance a png image:
dot file.dot -Tpng -ofile.png
Run Arqua on a directory structure of files by inputing all files with their relative path to Arqua:
arqua -files -packages dir1/file1.c.104.r.expand dir2/file2.c.104.r.expand > dirs.dot
This will generate a graph visualizing both files and directories.
There are a few options that controls how Arqua is creating a report:
- -report (default:graph) Arqua can create text list of smells instead of a graph using -report text. When used all other options are ignored.
- -root path Sets what root directory to start from when generating a graph. The analysis and calculation is still done from the working directory.
- -packages (default:off) Tells arqua to draw packages (directories).
- -files (default:off) Tells arqua to draw files.
- -functions (default:off) Tells arqua to draw functions.
- -levels number of levels Sets the number of abstraction levels to traverse.
- -ft function complexity threshold Sets the function complexity threshold (max allowed cyclomatic complexity of the RTL representation of the function))
- -nt node complexity threshold Set the node (directory and file) complexity threshold (max number of allowed edges in a node)
In each example it is assumed that $FILES contains a list of RTL files with their path relative to the root of the system.
Draw the top 3 directories and all files directly within them:
arqua -packages -files -levels 3 $FILES > system.dot dot system.dot -Tpng -osystem.png
Generate a list of smells of a system:
arqua -report text $FILES > system.txt
Draw the files and their internal call graphs for all files within the folder adir/bdir:
arqua -files -functions -levels 3 -root adir/bdir $FILES > system.dot dot system.dot -Tpng -osystem.png
Note that -root only filter out data and that -levels is still needed to traverse down into the directories.
Any code contributions or ideas on how to even better represent the structure of C code are welcome.
Copyright (c) 2012, Magnus Ernstsson All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.