fpt Reference: Running fpt

fpt and WinFPT Reference Manual - Command-line Commands

| SimCon Home | Ref Manual Home |

Running fpt

fpt and WinFPT

There are two implementations of fpt, WinFPT and command-line fpt.

WinFPT is a 32-bit program. Command-line fpt is a 64-bit program which is significantly faster than WinFPT and can process much larger programs.

WinFPT and command-line fpt support the same facilities to analyse and to re-engineer Fortran code, and have the same command set. The commands in WinFPT are accessed through a GUI interface, with dialogues and drop-down menus. The commands in command-line fpt are accessed through a command line interpreter. WinFPT runs under Microsoft Windows. Command-line fpt runs under Linux, Microsoft Windows, macOS, HP-UX and VMS. This manual describes the commands for command-line fpt. WinFPT processes code in the same way, and this manual may be used as a reference for WinFPT.

Running Command-line fpt

Run fpt on the operating system command line with the command:

$ fpt argument_1 [ argument_2 ... ]

where the arguments are:

fpt commands
Fortran file names
fpt script file names with the file name extension ".fsp"
WinFPT project files with the file name extension ".fpp"

Any number of arguments may be specified up to the maximum number (if any limit exists) supported by the operating system. The fpt command may extend over multiple lines, using the line continuation convention of the operating system in use. The simplest command-line command by which fpt is often run is, for example under Linux:

$ fpt my_prog.f90 %i

where my_prog.f90 is a free format Fortran source file in the current working directory, any include files are also in the current working directory, and %i is the fpt command to run fpt interactively.

fpt Commands

The fpt commands specify the directory locations and characteristics of the Fortran input files and the ways they should be analysed, re-engineered and re-written.

On the operating system command line, the commands are introduced by the character "%" under Linux, Unix and VMS, and "/" under Windows and VMS.

Commands written on the operating system command line which contain spaces are enclosed in double quotes. The quotes may, but are not required to enclose the leading "%" or "/" character.

The commands are not case sensitive, but file names and parts of file names specified in commands are case sensitive under Linux and Unix. Strings within commands are enclosed in single quotes.

Fortran File Names

The Fortran file names specify the files to be analysed and re-engineered.

Fortran files are classified as primary files, which are the files which are submitted to the Fortran compiler, and include files, which are referenced by INCLUDE statements in the code. Only the primary files need to be specified. The include files are discovered by fpt as it analyses the code. However, no error occurs if an include file is specified in the list of files to be analysed.

File names may be specified:

With complete directory specifications rooted to the file system or device
With directory specifications relative to the directory in which fpt is run
Without directory specifications, in which case the directories specified by the commands:

INPUT DIRECTORY
PRIMARY INPUT DIRECTORY
INPUT SEARCH PATH
PRIMARY INPUT SEARCH PATH

are used. If no directories are specified by these commands, the files are sought in the current working directory.

The file names are case sensitive under Linux and Unix and case insensitive under Windows and VMS.

File names which contain spaces are enclosed in double quotes.

fpt Script Files - fsp Files

If any project contains more than a small number of source files and fpt commands, it is convenient to set these up in a script file instead of writing them on the command line. Script (fsp) files are recognised by the file name extension ".fsp" or ".FSP" The extension stands for Fortran specification.

The file names are case sensitive under Linux and Unix and case insensitive under Windows and VMS.

The organisation and command conventions in fsp files, and the process of setting up a project are described below.

WinFPT Project - fpp Files

WinFPT project (fpp) files are fsp files which are written automatically by the WinFPT program. An fpp project file contains:

A specification of the input code:

The files which make up a project
The file locations
The file name extensions
The layout of the input Fortran code
The dialect of Fortran

a specifications of the output code:

Specifications of any engineering changes
The destination directories
The output file name extensions
The format and layout of the output code

a specification of the filters which control the sensitivity of the error checks and analyses, but not of the checks themselves. WinFpt runs interactively to carry out the checks.

These files may be used to set up command-line projects, but if they are edited, it is recommended that the file name extension is changed to ".fsp".

Command-line Examples

fpt is run under Linux to analyse a program with three files in the current directory. The command %i instructs fpt to run interactively.

$ fpt %"primary input file name extension: '.for'" milatc.for deviat.for closap.for %i

fpt is run under Windows in batch mode to process a program to move COMMON blocks to include files:

> fpt helisim_move_commons.fsp

Fortran Specification, fsp, Files

Fortran specification, fsp, files contain:

Comments, delimited by leading "!" characters
fpt commands
Fortran file specifications
Nested fsp file specifications
Blank lines, which are ignored

The file names and commands are written one to each line, except that some commands may continue over multiple lines as described below.

The fsp file may be of any length.

fpt Commands

Commands are introduced by the character "%".

If a command contains two or more words, the words are separated by one or more white space (space or tab) characters. Spaces are not required, but may be used to separate delimiters such as ":" characters from words. The command line length is 132 characters. Commands longer than this may be continued by writing a line continuation character at the end of the line. By default, this is the character "-" but it may be changed by the command COMMAND CONTINUATION CHARACTER. Note that this command may be written in the configuration file.

The commands are not case sensitive, but file names and parts of file names specified in commands are case sensitive under Linux and Unix. Strings within commands are enclosed in single or double quotes.

Fortran File Names

The Fortran file names specify the files to be analysed and re-engineered.

As on the operating system command line, file names may be specified:

With complete directory specifications rooted to the file system or device
With directory specifications relative to the directory in which fpt is run
Without directory specifications, in which case the directories specified by the directory and search path commands described below. If no directories are specified by these commands, the files are sought in the current working directory.

The file names are case sensitive under Linux and Unix and case insensitive under Windows and VMS.

File names which contain space characters are enclosed in double quotes.

Optionally, a file name may be followed by a specification of the Fortran compilation switches required to compile it. The switches are introduced by the keyword FCFLAGS= and are enclosed in double quotes. They may be specified explicitly or as a Makefile symbol. Please see the command WRITE MAKEFILE for a description of Makefile generation.

Nested fsp Files

fsp files may reference nested fsp files to a maximum nesting depth of 10.

Setting Up a Command-Line fpt Project

Building the Project Automatically

Command-line fpt versions 4.1-t and later support the command BUILD PROJECT. The user specifies a top-level primary file, and fpt automatically searches for missing INCLUDE files, Fortran modules and sub-programs. If they cannot be found, fpt prompts for the locations of the missing objects.

The use of the BUILD PROJECT is optional and may not be appropriate for all uses of fpt. If it is not used (and in explanation of the output generated by the command) the steps in building a command-line project are described below.

The Fortran input Files

The first task in setting up a command-line fpt project is to read the input files. The recommended procedure is to set up an fsp file which handles the input code. If the project is named my_project then this file might be named my_project_files.fsp. This is recommended because there may eventually be a family of top-level fsp files with different analysis and engineering commands, all of which reference my_project_files.fsp.

Create the text file my_project_files.fsp. Begin by specifying the directories from which the files are to be read. The commands used are:

INPUT DIRECTORY
PRIMARY INPUT DIRECTORY
INPUT SEARCH PATH
PRIMARY INPUT SEARCH PATH
ADD TO INPUT SEARCH PATH
ADD TO PRIMARY INPUT SEARCH PATH

These commands are all position-sensitive in the fsp file. They apply to the Fortran files which follow them until a new specification is made.

Use the INPUT DIRECTORY and SEARCH PATH commands for groups of files where the include files are in the same directory as the primary files. Use the PRIMARY commands if the include files are in different directories.

The SEARCH PATH commands are useful if code is modified during a project to make tests. If, for example, the fsp file contains the fragment:

% input search path: "../modified_source/aero/" "../original_source/aero/" trotor.f90

Then trotor.f90 will be sought first in the modified_source/ directory structure and will default to the original_source/ directory structure if the user has not made a new version.

It may also be necessary to specify the directories for the include files. The commands are:

INCLUDE INPUT FILES FROM PRIMARY DIRECTORIES (The default setting)
INCLUDE INPUT DIRECTORY
INCLUDE INPUT SEARCH PATH
ADD TO INCLUDE INPUT SEARCH PATH

Note that fpt will exit with a fatal error if it cannot open an include file. This is done because include files usually contain declarations of variables, and fpt cannot make meaningful analyses and engineering changes when declarations are missing.

A further issue is that fpt may be used to process files which have been copied from another operating system. It may be necessary to modify the file names, particularly those in INCLUDE statements, before they can be opened. For example, file names under Windows are case insensitive. Under Linux they are case sensitive. The relevant commands are:

EDIT INPUT FILE NAMES
EDIT FILE NAMES IN INCLUDE STATEMENTS

The next step in setting up the input files is to specify the input code layout. By default, fpt assumes that files with the file name extension ".f90" are written in free format, and files with all other extension are written in fixed format (Though note that defaults may be changed in the configuration file). It may be necessary to specify the code layout used. The commands are:

FREE FORMAT INPUT
FIXED FORMAT INPUT
FIXED FORMAT INPUT EXTENDED SOURCE

As with the other file handling commands, these commands are position sensitive and apply to the files which follow them. A project may therefore contain files with different formats. The layout rules are inherited by the include files. If a primary file has free format layout it is assumed that its include files also have free format layout.

In some cases, additional characteristics of the input code must be specified. These include:

CPP Macro definitions used in the code - see CPP macro handling.
Unusual data kinds and sizes - see DEFINE KIND and DEFAULT SIZE.
Unusual intrinsic functions - see ACCEPT INTRINSIC.
Unusual alphabetic characters (e.g. "@" and ":") - see ACCEPT CHARACTER.
Gould-SEL DATAPOOL handling, see DATAPOOL LISTING FILE.

A final detail, before listing the files to which the directory and file attribute commands apply is to specify the file name extensions. This is done because fpt recognises a default input file name extension for primary files and for include files. If an input file does not conform to this default, the extension is appended to the base file name when the file is written. This overcomes the problem that some projects may contain multiple primary and include files with the same base file name but different extensions. The commands are position-sensitive and apply to the files which follow them. It is therefore possible to specify several different file name extensions in one project. The commands are;

PRIMARY INPUT FILE NAME EXTENSION
INCLUDE INPUT FILE NAME EXTENSION
KEEP FILE NAME EXTENSIONS

The last step is to list the Fortran files, one to each line.

It is recommended that the project is built up progressively, starting with a small number of primary files. A problem with Fortran 90 is that fpt cannot analyse a program if any Fortran modules are missing. It is therefore necessary to identify the modules which have no other module USE dependencies at the start of this process.

Run fpt interactively, with the I command, and use the command SHOW MISSING SUB-PROGRAMS to monitor progress in completing the file list: e.g.

$ fpt my_project_files.fsp %i FPT> show missing sub-programs

Example of fsp File Handling

The example below shows the start of a file-handling fsp file:

! WRFV3.4.1_files.fsp 6-Nov-12 John Collins ! File Handling ! ============= % include input path: Q:\WRF\WRFV3.4.1\gfortran\WRFV3_pre_fpt\inc % primary input file name extension: "f90" % include input file name extension: "inc" % primary input path: Q:\WRF\WRFV3.4.1\gfortran\WRFV3_modified_source\dyn_em\ % add to primary input path: Q:\WRF\WRFV3.4.1\gfortran\WRFV3_pre_fpt\dyn_em\ adapt_timestep_em.f90 couple_or_uncouple_em.f90 init_modules_em.f90 interp_domain_em.f90 module_advect_em.f90 module_avgflx_em.f90 module_bc_em.f90

Setting Up fsp Files for Analysis and Re-engineering

When the initial file-handling has been set up, run fpt interactively to examine any errors reported by fpt and to carry out systematic checks for errors. Please see: Checking For Errors.

Reports may be generated which describe the size and complexity of the code, and show, for example, the symbol table, the COMMON block addresses, the call tree, module USE tree and include tree. Please see: Metrics and Reports.

When the errors have been satisfactorily resolved, set up top-level fsp files for the required engineering changes. For example:

! my_project_coverage.fsp 4-Dec-13 John Collins ! Read the files my_project_files.fsp ! Replace the $ characters in the symbols % edit symbol names: replace "$" by "_d_" ! Insert coverage FPTMAIN:coverage.fsp ! Output file handling % output directory: "../fpt_output" % overwrite changed files % write makefile ! End of my_project_coverage.fsp

For descriptions of the software engineering tools, code reformatting and output file generation please see: