NAGWare Fortran Tools - f95 Tools - nag_coverage95
Index
- NAME
-
- DESCRIPTION
-
- OPTIONS
-
- FILES
-
- LIMITATIONS
-
- SEE ALSO
-
NAME
nag_coverage95 - Fortran 95 Coverage Tool
DESCRIPTION
nag_coverage95 is the NAGWare f95 Coverage tool which
instruments Fortran 95 source file(s) producing code that has the same
effect but with extra monitoring code added.
The tool breaks down the input Fortran code into segments of
straight-line code and each segment is then instrumented with a
counter. When compiled and executed, the instrumented program will
produce a trace detailing how many times a particular segment of code
was executed. Those segments which are executed most may be the best
places to concentrate efforts in optimising the code if speed of
execution is required. If some segments are not executed at all when
running with test data, the testing strategy may need to be improved.
The tool also reports segments which contain dead code (code that
cannot be reached).
If a filename with no extension is provided the tool will look for a file
with the extension `.f95', and if that does not exist, for a file with the
extension `.f90'.
If a file has the extension `.f90' or `.f95', it will be assumed to
contain free format Fortran code. If a file has the extension `.f',
`.for', `.f77', or `.ftn', the file is assumed to contain fixed format
Fortran code. The options -fixed and -free may be used to
override this behaviour.
Modules (and include files) are expected to exist in the current working
directory or in a directory named by the -I option, see
nag_modules95.
OPTIONS
Coverage Options
- "Collate data from: A single run" (-single_run filename)
-
The default operation of the tool is to produce an instrumented
program that writes single run statistics to the file
`base.out', (see `FILES' below). This option also allows the
output file name to be entered in the box below. After execution of
the instrumented program, this file may be viewed from
nag_tools by selecting "Coverage Report Viewer" from the
Coverage sub-menu of the Tools menu.
- "Collate data from: Multiple runs" (-cumulative filename)
-
This option causes the cumulative trace output across multiple
executions to be output to filename. (The default filename is
`base.out'.) After execution of the instrumented program, this
file may be viewed from nag_tools by selecting "Coverage Report
Viewer" from the Coverage sub-menu of the Tools menu. This option
enables the instrumented program to be invoked with different input
data so that a more general view of its behaviour can be obtained.
The file `filename.hist' is created, if it does not already
exist, when the executable program is run. It contains the internal
tables of cumulative execution frequencies and is not intended to be
viewed. To reset the cumulative counts to zero, simply remove this
file.
- "Executable" (-exename name)
-
Force the instrumented executable to be called name. The
default is to use file1.inst.exe where file1 is the
name of the first source file.
- "Objects before" (-first obj1 ...)
-
Instruct the tool to load with obj1 ... before the instrumented
object files. This option may appear only after the list of source files
to be instrumented (see also -last).
- "Objects after" (-last obj1 ...)
-
Instruct the tool to load with obj1 ... after the instrumented
object files. This option may appear only after the list of source files
to be instrumented (see also -first).
- "Produce: Executable" (-load)
-
Instruct the tool to load all object files into an executable. This is the
default if the -source and -objects options are omitted.
- "Module name" (-modname name)
-
Sets the prefix for the instrumentation module and identifier names
to name. The default is CVG90M.
- "Produce: Object" (-objects)
-
Compile the instrumented source to produce object files, but do not load
them into an executable unless -load is also specified. Without
this option, -load will cause intermediate object files to be
deleted after loading. This option may be useful if the instrumented
object files are to be placed in a library archive.
- "Produce: Source" (-source)
-
Create the instrumented source, but do not compile them unless -load
or -objects is also specified. Without this option, -load and
-objects will delete the instrumented files after compilation. This
option may be useful if the source files are part of a program which is
being built under the control of make(1) (see -first and
-last).
- "Compiler" (-Wf=name)
-
Force the tool to use name to compile instrumented source files
instead of f95. The compiler must accept the command line arguments
`-Idir <flags> -c -o obj src'
to compile the Fortran 95 file
src into the object file obj, where <flags> is all
the -Wf option arguments. Please note that the -source option
may be used to generate instrumented source code files for separate
compilation and linking.
- "Compiler flags" (-Wf,opt1,opt2,...)
-
Instruct the tool to pass options opt1 opt2 ... to the compiler
when producing object files.
- "Loader" (-Wl=name)
-
Force the tool to use name to load compiled object files into an
executable. The loader must accept the options
-o exe <flags> obj1 ...
to load the object files
obj1 ... into the executable exe. The -L and -l
tool options and the arguments to -Wl are passed to name as
<flags>. The default is f95 or, if -Wf= is set, the
same name as specified by the -Wf= option. `obj1 ...'
consists of the arguments to -first, instrumented objects and
finally -last arguments.
Please note that the -source option
may be used to generate instrumented source code files for separate
compilation and linking.
- "Loader flags" (-Wl,opt1,opt2,...)
-
Instruct the tool to pass options opt1 opt2 ... to the loader
when producing the executable.
General Options
- "Source format" (-fixed, -free)
-
Forces the tool to assume fixed or free format for the
input file. If "Automatic" is set, .f90 files will be
assumed to contain free format code , .f, .for, .f77,
or .ftn are assumed to contain fixed format code.
- "Include and module directories" (-I)
-
Add pathname to the list of directories which are to be searched for
include files. The current working directory is always searched
first, then any directories named in -I options.
- "Fixed format source line length" (-132)
-
Increase the length of each fixed source form input line from 72
characters to 132 characters. This has no effect on free source form
input.
- "Allow double complex specific intrinsics" (-dcfuns)
-
Enable recognition of non-standard double precision complex intrinsic
functions. These act as specific versions of the standard generic intrinsics
as follows:
Non-standard Equivalent Fortran 95 Intrinsic
CDABS(A) ABS(A)
DCMPLX(X,Y) CMPLX(X,Y,KIND=KIND(0d0))
DCONJG(Z) CONJG(Z)
DIMAG(Z) AIMAG(Z)
DREAL(Z) REAL(Z) or DBLE(Z)
- "Downgrade legacy code errors to warning" (-dusty)
-
Allows the analysis of ``legacy'' software by
downgrading the category of common errors found in such software from
``Error'' to ``Warning'' (which may then be suppressed entirely with the
-w option).
- "Suppress information messages" (-info)
-
Suppress output of tool analysis stages information messages.
- "Kind numbers"
-
- "Byte kinds" (-kind=byte)
-
Alter the kind numbering system used so that the kind numbers for
INTEGER, REAL and LOGICAL match the number of bytes of storage
(e.g. default REAL is 4 and DOUBLE PRECISION is 8). Note that COMPLEX
kind numbers are the same as its REAL components, and thus half of the
total byte length in the entity.
- "Sequential kinds" (-kind=sequential)
-
This confirms the default kind numbering system where all datatypes
are numbered sequentially from 1 and increase with precision.
This option does not affect the interpretation of byte-length
specifiers (an extension to Fortran 77).
- "Downgrade argument checks between routines in different files" (-mismatch)
-
Downgrade consistency checking of procedure argument lists so that mismatches
produce warning messages instead of error messages.
This only affects calls to a routine which is not in the current file; calls
to a routine in the file being compiled must still be correct.
- "Downgrade argument checks between routines in the same file" (-mismatch_all)
-
Further downgrade consistency checking of procedure argument lists so that
calls to routines in the same file which are incorrect will produce warnings
instead of error messages.
- "Continuation line limit" (-maxcontin)
-
Increase the limit on the number of continuation lines to N. The
default, as specified by the Fortran standard, is 19 for fixed source
form and 39 for free source form. This will not decrease the limit
below the standard number.
- "Output strict Fortran 95 obsolescent messages" (-strict95)
-
Produce obsolescence warning messages for use of ``CHARACTER*'' syntax.
This message is not produced by default since most programs contain this
syntax.
- "Suppress warning messages" (-w=all)
-
Switch on or off tool analysis stages warning messages.
- "Suppress obsolescent feature warning messages" (-w=obs)
-
Switch on or off warning messages about the use of obsolescent features.
- "Suppress unused entity warning messages" (-w=unused)
-
Suppresses warning messages about unused entities.
It is equivalent to
-w=uda -w=uei -w=ulv -w=usy.
- "Suppress unused dummy argument warning messages" (-w=uda)
-
Switch on or off warning messages about unused dummy arguments.
- "Suppress unused explicit import warning messages" (-w=uei)
-
Switch on or off warning messages about unused explicit imports.
- "Suppress unused local variable warning messages" (-w=ulv)
-
Switch on or off warning messages about unused local variables.
- "Suppress unused symbol warning messages" (-w=usy)
-
Switch on or off warning messages about unused symbols.
- "Suppress Fortran 77 extension warning messages" (-w=x77)
-
Switch on or off extension warnings for common extensions to FORTRAN 77.
These are TAB format, byte-length specifiers and Hollerith constants.
- "Suppress Fortran 95 extension warning messages" (-w=x95)
-
Switch on or off extension warnings for extensions to Fortran 95.
FILES
Output files from the tool and the compilation may optionally be
created in a directory specified by the -odir option
otherwise, by default, all files are created in the current directory.
If base
is the base name of the first source file given to the tool then some or
all of following files may be generated:
- base.inst.exe
-
This is the default name for the instrumented executable. Use
-exename to specify an alternative.
- base.cvg.o or base.cvg.obj
-
Tool run time support functions.
- base.out
-
With default options,
the single run coverage results generated from the most recent execution of
the instrumented executable. See also the -single_run and
-cumulative options.
For each source file given to the tool, the following may
be generated (where name is the base name of the file):
- name.inst.f90 or name.inst.f95
-
Instrumented source code. The -osuffix
option may used to change the `.inst' suffix. If -odir
is specified, this file will not have the `.inst' suffix.
- name.inst.o or name.inst.obj
-
Instrumented object file. The -osuffix
option may used to change the `.inst' suffix. If -odir
is specified, this file will not have the `.inst' suffix.
- name.listing.f90
-
The original source file annotated with segment numbers in comments.
Module files (.mod) may be created as well during compilation.
LIMITATIONS
The output statistics are formatted assuming that there are no more than
99999999 segments in the source being instrumented, and that the number
of times a particular segment is executed does not exceed 99999999. If
either of these limits are surpassed then the output table will contain
******** in place of the value which exceeds these limits.
Due to the complexity of FORALL loops with nested WHERE statements, a
FORALL loop will only be reported as one segment no matter how many
statements are contained within the loop. Only the top-level of nested
WHERE statements is instrumented.
The way in which assigned GOTOs (a deleted feature of the Fortran 95
standard) are implemented is not portable.
SEE ALSO
nag_polopt95,
nag_modules95.
Copyright, Numerical Algorithms Group, Oxford, 2001