FPPFILE.PY: python scripts for preprocessing FORTRAN code.

Prepared by C.Ludescher-Furth -- ludescher@pppl.gov 07/22/05

Authors: 
 - Original perl scripts:  A. Pletzer

 - Python scripts: R. Andre -- randre@pppl.gov
                   D. McCune -- dmccune@pppl.gov


****************
REVISION HISTORY
****************
      date          Description
August 26, 1999  -- Created perl scripts to be used with cpp
July   22, 2005  -- perl and cpp replaced with python scripts

Index:
   1. Unpacking Instructions
   2. Contents
   3. Usage
   4. Testing
   5. Installing Software
   6. Abstract


**************************
1. Unpacking Instructions:
**************************
  for tarfile:
    > gunzip fpreproc.tar.gz
    > tar xvf fpreproc.tar

  for zip archive:
    > unzip fpreproc.zip

************
2. Contents:
************
  Makefile              -- Main Makefile to envoke Makefile(s) in
                           subdirectories (If you downloded more than 
                           one module).  
  in ./fpreproc/
      README            -- This file.  
      Makefile          -- To install software (gmake)
      fppfile.py        -- python script for pre-processing
      *.py                 various scripts executed by fppfile.py
      fpreproc          -- csh script to facilitate processing
      fpreproc.1        -- man page
      fpre_test.{F,F90} -- fortran source sample for testing
      fpre_test.{f,f90}_ref -- output reference for test sample

  in ./include/fpreproc -- cpp include files
      blas_names.h      -- for mapping BLAS names to single or double
      byte_declare.h    -- for system dependent definition
      f77_dcomplx.h     -- for dealing with conversion intrinsics
      f77name.h         -- to define macro F77NAME(...)
      lapack_names.h    -- for mapping LAPACK names to single or double
      library_names.h   -- to reference an #include file
      nag_names.h       -- for mapping NAG names to E or F

See:  http://w3.pppl.gov/~pshare/help/port_strategy_hlp.html

*********
3. Usage:
*********

Note: When using the cpp *.h files, you should specify:
      #include "fpreproc/<name>.h"
      and preprocess with -I<PREFIX>/include

    
For fixed form (f77/f90) source code:

> python3 fppfile.py source.F newsource.f [options]

  Options:
  -132    extend maximum line width to 132 characters (default is 72).
  -Dname  workstation type e.g. -D__CRAY  -D__NAGWARE
  -Idir   #include dir for gcc/cpp
  -info   writes out debug messages
  -keep   do not delete the intermediate file (for debugging)

For free-form (f90) source code:

> python3 fppfile.py source.F90 newsource.f90 [options] -free


Convenience script: fpreproc
----------------------------
fpreproc envokes above scripts for you.

fpreproc input-file output-file [Includes] [fpp macros] [Format Options]
     
     Includes:
     -Idir       Adds dir to list of directories for #include files

     fpp macros:
     -Dname      Defines preprocessing definitions.
                 e.g. -D__LINUX or -D__F90

     Format Options:
     -132        extend maximum  line  width  to  132  characters
                 (default is 72)

     -free       Fortran 90 free format



***********
4. Testing:
***********

The included fortran code example, fpre_test.F is written in a combination
of lower and upper cases. Comments contain a variety of special characters,
including apostrophes and double quotes. Exclamation marks either indicate
comments or appear in strings/comments. Some strings extend over several lines,
sometimes interrruped by a comment.

To run the tests:
=================

To test fixed-form source code:

> cd fpreproc
>  python3 fppfile.py fpre_test.F fpre_test.f 


You may compare fpre_test.F with fpre_test.f and the included
reference  fpre_test.f_ref.

To test free-form source code:

> cd fpreproc
>  python3 fppfile.py fpre_test.F90 fpre_test.f90 -free 


alternatively using script fpreproc:

> ./fpreproc fpre_test.F90 fpre_test.f90  -free



***********************
5. Installing Software:
***********************

You might wish to install the scripts into an area, defined via PREFIX,
that you have in your PATH. The *.h files can be put elsewhere, they 
can be accessed using "-I...". 

The assumptions are:

scripts in:      $PREFIX/etc                 = $ETCDIR
*.h files in:    $PREFIX/include/fpreproc    = $INCLDIR/fpreproc 
man pages in:    $PREFIX/man/man1            = $MANDIR/man1

To install:
> gmake install PREFIX=/dir1/dir2/
    to install into /dir1/dir2/...

If you want things elsewhere, you can overwrite the default with
> gmake install ETCDIR=/xxx INCLDIR=/yyy MANDIR=/zzz


==============================================================================

***********
6. Abstract
***********

C-preprocessors (cpp's) provide a simple, elegant and efficient 
paradigm for porting C/C++ codes. Preprocessors are also widely used
to port FORTRAN codes; on many UNIX architectures the suffix .F
indicates the presence of pre-processor directives in a FORTRAN code and 
automatically invokes fpp, the FORTRAN equivalent to cpp. Such rules 
are not, however, uniformely and systematically available. FORTRAN 
preprocessors typically have different behaviour on different architectures.

We would like to be able to invoke fpp without assuming the .F suffix.
This can be done by calling cpp instead, or directly the C compiler 
(e.g gcc -E -P). Applying cpp carelessly (or gcc -E) on a FORTRAN code,
however, can produce some unexpected results. Typical problems are:

- cpp macro substitions may expand a line beyond the 72nd character

- cpp does not respect the f77 6-column format

- cpp tends to misinterpret "//" in format statements for C-style comments. 

The following python scripts have been written to remedy these problems.
Comments and strings are left intact. A simple mechanism attempts to compress 
overflowing lines to 72 (or 132) character width, provided they
do not contain strings.

o Language
  Python


