[comment {-*- flibs -*- doctools manpage}]
[manpage_begin checking n 1.0]
[copyright {2007 Arjen Markus <arjenmarkus@sourceforge.net>}]
[moddesc flibs]
[titledesc {Instrument source code for tracing execution}]

[description]

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.

[para]
The module [emph w_] is meant, in conjunction with the Tcl program
[emph instrument.tcl] to automate the process of adding such
write statements.

The write statements that are added record:
[list_begin bullet]
[bullet]
Calls to a subroutine (which routine, where)
[bullet]
Returns from the subroutine
[bullet]
Gotos within the main program or subroutine
[bullet]
Opening/closing of files
[bullet]
Stop statements
[list_end]

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.

[para]
The design goals were:
[list_begin bullet]
[bullet]
The code transformations should be simple (because these would
be easier to implement!)
[bullet]
The code transformations should not change the program's logic
(of course!)
[list_end]

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


[section Usage]
Using the module and the instrumentation program is easy:
[list_begin bullet]
[bullet]
Run the Tcl program [emph instrument.tcl] in the directory with source
files:

[example {
   > 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).

[bullet]
Add the file "w_.f90" to the list of source files for building the
program.

[bullet]
Build the program by the means you ordinarily use.
[list_end]


[section Notes]
[list_begin bullet]
[bullet]
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!)

[bullet]
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)

[bullet]
The name "w_" was chosen, because it is unlikely to be used in
any ordinary program as the name of a module or routine.

[bullet]
Running the Tcl program requires either an installation of Tcl
or a standalone Tcl "runtime program" (tclkit).
[nl]
For the first: have a look at http://www.activestate.com/tcl
[nl]
For the second: http://www.equi4.com/tclkit/index.html
[nl]
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.
[nl]
The advantage of the complete installation is that it comes with
an extensive set of examples, libraries and documentation on Tcl/Tk.
[nl]
(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)

[list_end]
[manpage_end]
