Source Code Visualization with Doxygen

When you need to figure out source without documentation!

Background 

In this situation we were tasked with parallelizing the Army Corp's HEC-RAS code using MPI. As per usual of fortran source, there seemed to be no documentation to work with, nor explanatory comments in the source itself. Additionally, the code was proprietary and so was not allowed to be copied into our own machines and opened in Visual Studio. Evidently, we needed somewhere to start, so it was suggested to start by generating a subroutine call graph. The following guide will use HEC-RAS and Fortran as an example. 

This guide is intended to get the user up and running as fast as possible so it glosses over some details, but more in depth explanations can be found in the references. 

Visual Studio

If you can access the source with visual studio, many languages are supported through an extension: 

Code Graph - Visual Studio Marketplace

Doxygen

Doxygen is usually used to generate user-defined documentation to accompany source, but we can exploit it to summarize the features of a program. Most Oden computers already have it preinstalled, but TACC does not have it available as a module. Detailed installation instructions are here.

Installing on TACC

...

Running Doxygen

Doxygen generates documentation according to a user-defined file called a Doxyfile. A template doxyfile may generated using:

doxygen -g <name_of_doxyfile> 

The following options in the doxyfile must be set to YES:

• EXTRACT_ALL
• HAVE_DOT
• OPTIMIZE_FOR_FORTRAN
• CALL_GRAPH
• CALLER_GRAPH 
• RECURSIVE
  
  • This last option will search the whole tree for source files, which in this case was necessary because the source was split into a Linear Algebra and Solver library.

You may also just use this doxyfile which already has these preset. Then in terminal run: 

doxygen <name_of_doxyfile> 

This will generate a directory called "Documentation" wherever you call the command. Since the RECURSIVE option is on, it's recommended to call from in or directly above your source. 

Doxygen will generate a bunch of files inside ./Documentation/html. Downloading this directory and opening index.html will open a nicely formatted browser page with a list of modules, functions, and call/caller graphs.

As an example you may view the call/caller graph for HEC-RAS Light: RAS_Light.tar.gz

And for HEC-RAS-CSharp: rassharp-docs.zip