Using Project Files

This section contains detailed information on how to use project files most effectively, and how to avoid some pitfalls.

One can divide the checks ftnchek does into two categories, local and global. Local checking is restricted to within a single routine, and catches things like uninitialized variables, unintended loss of precision in arithmetic expressions, etc. This sort of checking can be done on each subprogram independently. Furthermore, local checking of a subprogram does not need to be repeated when some other subprogram is changed. Global checking catches things like calling a subroutine with the wrong argument types, or disagreeing in common block declarations. It requires looking at the whole set of subprograms interacting with each other.

The purpose of project files is to allow the local checking and global checking steps to be separated. Assuming that each subprogram is in its own source file, you can run ftnchek once on each one to do local checking while suppressing global checking. Then ftnchek can be run once on all the project files together to do the global checking. The sample makefile below shows how to automate this task. The ``.f.prj '' target updates a project file for a particular file any time the source file changes. The information needed for global checking is saved in the project file. The ``check '' target does the combined global checking. Typically ``make check '' would repeat the ``ftnchek -project '' step only on changed source files, then do the global check. This is obviously a big advantage for large programs, when many subprograms seldom if ever change.

It is best when using project files to place each subprogram in a separate source file. If each source file may contain more than one subprogram, it complicates the definition of ``local'' and ``global'' checking because there is some inter-module checking that is contained within a file. ftnchek tries to do the right thing in this case, but there are some complications (described below) due to the trade-off between avoiding re-doing cross-checks and preserving information about the program's structure.

Ordinarily, to do the least amount of re-checking, project files should be created with the -library flag in effect. In this mode, the information saved in the project file consists of all subprogram declarations, all subprogram invocations not resolved by declarations in the same file, and one instance of each COMMON block declaration. This is the minimum amount of information needed to check agreement between files.

If the source file contains more than one routine, there are some possible problems that can arise from creating the project file in library mode, because the calling hierarchy among routines defined within the file is lost. Also, if the routines in the file make use of COMMON blocks that are shared with routines in other files, there will not be enough information saved for the correct checking of set and used status of COMMON blocks and COMMON variables according to the -usage setting. Therefore if you plan to use project files when -usage checking is turned on (which is the default situation), and if multiple routines in one project file share COMMON blocks with routines in other files, the project files should be created with the -library flag turned off. In this mode, ftnchek saves, besides the information listed above, one invocation of each subprogram by any other subprogram in the same file, and all COMMON block declarations. This means that the project file will be larger than necessary, and that when it is read in, ftnchek may repeat some inter-module checks that it already did when the project file was created. If each project file contains only one module, there is no loss of information in creating the project files in library mode.

Because of the possible loss of information entailed by creating a project file with the -library flag in effect, whenever that project file is read in later, it will be treated as a library file regardless of the current setting of the -library flag. On the other hand, a project file created with library mode turned off can be read in later in either mode.

Here is an example of how to use the UNIX make utility to automatically create a new project file each time the corresponding source file is altered, and to check the set of files for consistency. Add these lines to your makefile . The example assumes that a macro OBJS has been defined which lists all the names of object files to be linked together to form the complete executable program. (In this makefile , the indented lines should each begin with a tab, not blanks.) If any source file contains multiple routines that share common blocks among themselves, then the no-com-\* option should be removed from NOGLOBAL , and/or drop the -library flag.

    # tell make what a project file suffix is
    .SUFFIXES: .prj

    # these options suppress global checks.
    NOGLOBAL=-usage=no-ext-undefined,no-com-\\*

    # tell make how to create a .prj file from a .f file
    .f.prj:
            ftnchek -project $(NOGLOBAL) -library $<

    # set up macro PRJS containing project filenames
    PRJS= $(OBJS:.o=.prj)

    # "make check" will check everything that has been changed.
    check: $(PRJS)
            ftnchek $(PRJS)

Next: an Example