Portability Related Modules
	============================

These modules are available through the NTCC Webpage,
w3.pppl.gov/NTTC  under "Modules Library", as compressed
tarfiles, <name>.tar.gz, and as zip archives, <name>.zip.
Alternatively they can be obtained from ftp.pppl.gov
in pub/NTCC/.


****************
REVISION HISTORY
****************
      date         Description

  May 20, 1999  -- Created

******************
    MODULES
******************

   MODULE	Synopsis
   ------       -----------------         --------	

  PortLib	a library of interfaces to operating system functions
               	(such as "getenv", "getcwd", "system", etc), which hides
               	operating system dependency from the user code.

  FPreProc	a set of python scripts and ".h" files for preprocessing
                of fortran sources, to support conditional compilation
                and macro substitution, that give methods for implementing
                portable code from a single source.

  FToken	this is a small collection of programs based on a
               	subroutine library "ftoken" which detects symbols
               	or "tokens" in fortran code, while screening out
               	comments and quoted strings.  The programs included
               	in the ftoken module are useful for portability
               	conversions.  These programs are:

       => fgtok -- program for wholesale manipulation of names and
               declarations in fortran codes (mainly:  fixed format
               fortran).  The `fgtok' program, with accompanying name
               substitution tables, can perform such operations as
                 => perform any user specified table driven token (name)
                    substitution operations (for example, change from 
                    using single precision "nag" to double precision "nag"
                    subroutine calls).
                 => convert all floating point declarations to "REAL*8"
                    and "COMPLEX*16".
                 => declare "IMPLICIT NONE" in all routines.
                 => convert all floating point constants to D-exponent 
                    form.
                 => convert all non-generic intrinsic function references
                    to their generic form.
                 => "detab" source code.
                 => check that all source lines satisfy the 72 character
                    length limit.

       => r8_convert -- a script to conveniently run fgtok, idecl and
	       cpcheck to convert source files into portable form.

       => r8_convert_include  -- a script to conveniently run fgtok
	       to convert include files into portable form.


       => idecl -- a program for generating the declaration of formerly 
               implicitly declared items in fixed format fortran source.
               Reason:  when converting code for greater portability,
               it is often a good idea to convert it to use IMPLICIT NONE.
               But that requires declaring all previously implicitly 
               declared names.  The idecl program does this.

       => cpcheck -- a program that scans a named fortran source looking
               for macros specified in a named cpp #include file; it
               simply writes "present" if macros are found, "absent"
               otherwise.

       => r8real -- a program that automatically generates an interface,
               written in fortran-90 using copies from/to dynamically
               allocated arrays, which allows a REAL*8 code to call 
               subroutines in a library written with REAL arguments.


********************  
Contents of Archives
********************


   portlib	- README (brief description and building instructions)
		- Makefile and python scripts for building
		- sources for the library libport.a
		- sources for porttest
		- man page

   ftoken	- README (this file)
		- INSTALL (Building / Installation Instructions)
		- Makefiles and python scripts for building
		- sources and driver scripts for programs:

		  program	driver(s)	input(s)
		  -------	---------	--------
        	  cpcheck	  NA		  NA        

        	  fgtok		fgtok_list.csh	int_precision.sub
				intcon.csh	r8_icomplex.sub
				r8con.csh	r8_intrinsic.sub
				r8_convert	r8_precision.sub

		  idecl 	  NA		f77_exclude.list

		  r8real	r8igen.csh 	  NA

		- sources for the internally used libraries portlib
                  and ftoken.
                - test program and reference output
	        - man pages

   fpreproc	- README (description)
		- Makefile to install the scripts
		- fpreproc:
                    - the python script: fppfile.py
                      and various internally used *.py scripts
                    - convenience script: fpreproc
                    - man page
		- include: cpp include files


Detailed information of each module is provided in
 
   http://w3.pppl.gov/NTCC/Port
and 
   http://w3.pppl.gov/~pshare/help/port_strategy.htm


*************************
Installation Instructions
*************************
 
For FToken module see INSTALL provided with the ftoken.{tar.gz,zip} archive.

For PortLib (standalone) see ./portlib/README.


IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT:


        transp_support, Princeton University
                transp_support@pppl.gov