fpt and WinFPT Reference Manual - Command-line Commands

| SimCon Home | Ref Manual Home |

BUILD PROJECT

Syntax:

BUILD PROJECT

fpt Version

This command is available in fpt version 4.1-t and later.

Function:

This command automates the process of building an fpt project.

If a Fortran program contains only a small number of primary files fpt may be run from the operating system command line by a simple command of the form:

$ fpt file_1 file_2 command_1 command_2 ...

Where a program is made up of many files distributed across a complex directory structure it is necessary to create an fpt project file. This is a text file with the file name extension ".fsp". The project fsp file describes the file structure of the program, the way fpt output files are to be organised and, optionally, engineering and analysis tasks to be carried out. fpt is then run by a command of the form:

$ fpt my_project.fsp

For example, the small project drx occupies the directory structure:

drx/ !-- inc/ |-- dcomm.for |-- ddata.for |-- dparam.for |-- drxres.for !-- dareao.for !-- darear.for !-- dareaw.for !-- drxerr.for !-- drx.for !-- drxrep.for !-- memmap.for

To build the fpt project automatically, we first create a working directory named fpt. We cd to this directory and run the script project_directory_setup. This script prompts for the location of the directory containing the files and sets up the recommended directory structure. For example, under Linux:

$ mkdir fpt $ cd fpt $ project_directory_setup Please enter the base directory of your files: ../drx

This creates the directory structure:

!-- fpt/ !-- fpt_output/ !-- drx !-- inc/ !-- modified_source/ !-- drx/ !-- inc/ !-- original_source/ !-- drx/ !-- inc/ |-- dcomm.for |-- ddata.for |-- dparam.for |-- drxres.for !-- dareao.for !-- darear.for !-- dareaw.for !-- drxerr.for !-- drx.for !-- drxrep.for !-- memmap.for

• The fpt directory will contain the fpt project and the fpt listing file.
  
• The fpt_output directory structure will contain the fpt Fortran output files, organised in the same directories as the input files.
• The modified_source directory structure will contains any files modified by hand as a result of the analysis by fpt.
  
• The original_source directory structure contains the files at the start of the project. These files will not change.

fpt is then launched with the command (e.g. under Linux):

$ fpt "% build project"

fpt will prompt for the main program file, and will then search for missing components within the original_source directory structure. If there are duplicate include files, modules or sub-programs fpt will prompt for clarification. In the case of this simple program fpt will output:

john@impala:~/projects/fortran_codes/drx/drx2/fpt$ fpt "% build project" Building an fpt Project ======================= The project will be created in the current directory: /media/john/projects/fortran_codes/drx/drx2/fpt/ Continue [Y/n]: y Project name: drx Use the ../original_source ../modified_source ../fpt_output directory structure [Y|n]: > y Additional files & commands, blank line to end entry > % input file name extension: .for > % edit input file names: lower case > % free format > % primary output file name extension: .f90 > % include output file name extension: .i90 > Ignore directories in INCLUDE statements [Y/n]: > y Create a makefile [Y/n]: y Choose an input format 1. % infer input code layout from file name extension 2. % free format input 3. % fixed format input 4. % fixed_format input extended source 5. Infer the layout and use long lines for fixed format 6. The format is already specified Format [1-6]: > 1 Choose a top-level file from which to start File: ../original_source/drx/drx.for Iteration: 1 2 3 4 drx.fsp and drx_files.fsp are ready for use

This process generates two fsp files in the current directory:

File: drx.fsp:

!H!**************************************************************************** !H! File: drx.fsp !H! Output by fpt 4.1-sA Intel-Linux On 31:Dec:50 At 00:00:00 !H!**************************************************************************** ! Additional files and commands % input file name extension: .for % edit input file names: lower case ! Additional files and commands % free format % primary output file name extension: .f90 % include output file name extension: .i90 ! Project input files drx_files.fsp ! Project output directories % output directory: ../fpt_output % keep directories % keep file name extensions % edit output file names: replace "original_source" by "fpt_output" % edit output file names: replace "modified_source" by "fpt_output" % ignore directories in include statements % make makefile ! End of drx.fsp

File: drx_files.fsp. Note that this is referenced in drx.fsp.

!H!**************************************************************************** !H! File: drx_files.fsp !H! Output by fpt 4.1-sA Intel-Linux On 31:Dec:50 At 00:00:00 !H!**************************************************************************** % infer input code layout from file name extension ! Start of paths % include input search path: "../modified_source/drx/inc" % add to include input search path: "../original_source/drx/inc" ! End of paths ! Start of files % primary input search path: "../modified_source/drx" % add to primary input search path: "../original_source/drx" drx.for dareao.for darear.for dareaw.for drxrep.for memmap.for drxerr.for ! End of files ! End of drx_files.fsp

Extending the Automatically Generated Project Files

The automatically generated project should contain a complete, or at least adequate description of the input files and rules for writing the output files if these are required. It is expected that users will specify additional commands on the command-line, will run the project interactively to make additional commands, or will edit the project files as required.

How Does it Work?

The automated process of building a project is iterative. After the user has specified a starting main program, module or sub-program, it runs as follows:

1. The initial pass of fpt, the lexical analyser, is called to identify any missing INCLUDE files. If any are detected, and the original_source directory structure is present, system calls are made to search the directory structure for the files. If they are not found, fpt prompts for the directories which contain the files. INCLUDE files may reference nested INCLUDE files. If any new INCLUDE files are added the process therefore returns to step 1.
2. The second fpt pass is then called to identify USE statements in the code. This pass finds the names of any missing Fortran modules. If any are detected and the original_source directory structure is present, fpt searches the directory structure for these modules. If they are not found fpt prompts for the files where they reside. Any additional modules may reference more INCLUDE files and if any are added the process therefore returns to steop 1.
3. The next fpt pass is then used to identify missing subroutines and functions. Again fpt uses system calls to find the files where the missing sub-programs reside. If they cannot be found, fpt prompts for the file names. Any additional sub-programs may reference missing INCLUDE files or modules and if any are added the process returns to step 1.

fpt can process code with missing subroutines and functions. The user may choose to terminate the build process at any point.

Note the lines:

! Start of paths

! End of paths

! Start of files

and

! End of files

These lines are sentinels which indicate to fpt where in the project_files the additional directory paths and files are to be inserted. It is possible to stop the build process, edit the project files, and to restart it. Please do not disturb the sentinels.

The original_source - modified_source - fpt_output Directory Structure.

The use of this directory structure enables fpt to use system services to search for missing INCLUDE files, modules and sub-programs. It is not essential to organise the code in this way, but if this structure is not used, fpt must prompt for file and directory locations.

If the original_source - modified_source directories are used, fpt always specifies a search path which begins with modified_source even if the modified_source directory does not contain the file sought. This enables the user to edit original_source files into the modified_source directories or to remove them without changing the project files.

If the original_source - modified_source directories are used and an input file lies outside these directories, fpt has no directory corresponding to the input directory under the fpt_output directory. These files are therefore enclosed in the system library construct to prevent the input files from being overwritten.

Wild Card Specifications

When fpt prompts for missing module or sub-program files wild-card expressions may be used to specify multiple input files in a directory: for example:

File: ~/libs/string_lib/*.f90

This can significantly shorted the process of building a project if the original_source - modified_source directory structure is not used. Please do not use wild-cards within a directory path.

Potential Problems

The following may occur:

1. fpt may detect two or more INCLUDE files or primary files with the same names or containing modules or sub-programs with the same name. When this occurs fpt prompts for the appropriate file or directory. However, problems will occur if two different modules or include files with the same name occur in the same program (in the case of modules this is illegal, but there is nothing in the language design to stop it happening).
2. fpt uses system services to identify missing subroutines and functions. There is no sysntactic difference between a subroutine or function header and the same header written in an interface, and the current version of fpt cannot distinguish them. This may lead to spurious duplicate sub-program identifications.

Where to Use this Command

Copyright ©1995 to 2024 Software Validation Ltd. All rights reserved.