checking(n) 1.0 "flibs"

NAME

checking - Instrument source code for tracing execution

    TABLE OF CONTENTS
    DESCRIPTION
    Usage
    Notes
    COPYRIGHT

If you need to understand a program written by somebody else, it is often useful to run it in a debugger to see what it is doing, but that can be time-consuming. Adding write statements to the program is an alternative, but again time-consuming.

The module w_ is meant, in conjunction with the Tcl program instrument.tcl to automate the process of adding such write statements. The write statements that are added record:

Calls to a subroutine (which routine, where)
Returns from the subroutine
Gotos within the main program or subroutine
Opening/closing of files
Stop statements

Messages indicating what is happening in the program are written to the screen (unit * to be more precise), because that way no extra logical unit is consumed and it is easier to see the program's actions in conjunction to the output it produces.

The design goals were:

The code transformations should be simple (because these would be easier to implement!)
The code transformations should not change the program's logic (of course!)

The module uses alternative returns to succeed in achieving these goals, even though they are marked as depricated in the Fortran 90 standard.

Usage

Using the module and the instrumentation program is easy:

Run the Tcl program instrument.tcl in the directory with source files:
> tclsh <directory containing the source>/instrument.tcl
This will create an instrumented version of all source files in the directory that have an extension .f, .for or .f90. The original files are first renamed, so that they can be retrieved. (See the tests/checking directory for an example).
Add the file "w_.f90" to the list of source files for building the program.
Build the program by the means you ordinarily use.

Notes

It can not easily log where functions are called, as calls to functions are much more difficult to identify in the source code than subroutine calls. Still, the source code for functions is instrumented in the same way as subroutines (with the exception of pure and elemental functions and subroutines!)
The instrumentation program is not foolproof: the generated source will not be correct Fortran, if you use variable names equal to keywords such as "return" or "open". (It is not a full parser of Fortran code, it merely detects certain string patterns and acts accordingly)
The name "w_" was chosen, because it is unlikely to be used in any ordinary program as the name of a module or routine.
Running the Tcl program requires either an installation of Tcl or a standalone Tcl "runtime program" (tclkit).

For the first: have a look at http://www.activestate.com/tcl

For the second: http://www.equi4.com/tclkit/index.html

The advantage of the tclkit family of programs is that installation is simply a matter of copying one single file, an executable program and de-installation is a matter of deleting that program.

The advantage of the complete installation is that it comes with an extensive set of examples, libraries and documentation on Tcl/Tk.

(Note: I chose Tcl as the implementation language for this program, because it is very easy to manipulate strings in Tcl. It could be reprogrammed in Fortran - the string matching via regular expressions is the hardest part, but even that can be done by standard means)