OS/2 Shareware BBS: 10 Tools/10-Tools.zip/fchek284.zip/README

Text File | 1995-06-01 | 24KB | 554 lines

         README file for Ftnchek Version 2.8.1

Author: Robert Moniot
    Fordham University
    New York, NY  10023  USA
    Telephone: [phone]
    Bitnet:    MONIOT@FORDMULC
    Internet:  [e-mail]

Date:    February 1, 1995

Ftnchek is written in a portable style of C.  You must have a C
compiler for the machine on which you wish to build it.
Information about the latest version and the status of the project can be
obtained by the Internet command ``finger [e-mail]''.

If the file you received is a UNIX compressed tar file, suffix .Z, you
should first unzip it using the UNIX ``uncompress'' command, and then
give it as input to ``tar'' to unpack the files.  For example, assuming
the file has been placed in the desired directory, and is named
ftnchek.tar.Z, you would give the two UNIX commands
    uncompress ftnchek.tar.Z
    tar -xf ftnchek.tar
If the suffix is .gz instead of .Z, use the program ``gunzip'' in
place of ``uncompress''.  The gunzip program is publicly available
from the GNU project.

After accomplishing this step, you should find that you have received
the following set of source files:

       exprtype.c       intrins.h        project.c
       forlex.c         iokeywds.h       symtab.c
       fortran.c        keywords.h       symtab.h
       ftnchek.c        pgsymtab.c       tokdefs.h
       ftnchek.h        plsymtab.c

These are all necessary for compiling Ftnchek on any system.

You should also have received a number of auxiliary files described
later.  There is also a directory named ``test'' containing a suite of
test programs for verifying the operation of ftnchek after you have
compiled it.


          INSTALLING FTNCHEK
          ------------------

To install Ftnchek, follow the instructions below for your operating
system.  The section ``CUSTOMIZING'' describes options that allow
compiling with bigger table sizes or accepting/rejecting certain
syntax extensions.



(1) UNIX and UNIX-like systems

   Give the command:

        $ make

Note: System-specific compilation options are provided for some
systems.  Users installing Ftnchek on one of these systems should
say

    $ make system

where system is one of the following words:

DEC-ALPHA       LINUX           SOLARIS2.x-apcc SUNOS5.x
DJGPP           LINUX-486       SOLARIS2.x-gcc  SUNOS5.x-apcc
GENERIC         MIPS-MIPS       STARDENT        SUNOS5.x-gcc
HP              SGI             SUNOS4.0        ULTRIX-MIPS
IBM-RS6000      SOLARIS2.x      SUNOS4.1        UNIX


To verify correct operation of the newly created ftnchek, you can
now issue the command

    $ make check

This will run ftnchek on the suite of test programs in the
subdirectory ``test'' and report on any discrepancies.  Please
note: the last test in the suite tests dcl2inc, which uses the
"new awk", namely AT&T nawk or GNU gawk.  By default, the check
is done assuming you have nawk.  If you have gawk, you should use
the command
    $ make check AWK=gawk
Some systems, such as AIX and Linux, have the new awk but call it
awk.  For these systems, or use the command
    $ make check AWK=awk
Alternatively, you can modify the makefile appropriately.

Once ftnchek is working properly, issue the command (requiring
super-user authority):

    $ make install

This will install the executable in /usr/local/bin and the manpage in
/usr/local/man by default.  For SGI give the command

    $ make SGI-INSTALL



(2a) VAX/VMS

   Give the command

        $ @BUILD

   After the program has been compiled, you must turn it into a
   so-called "DCL foreign command" so that it can be invoked by
   giving its name on a command line, instead of using the RUN
   command.  Do this with the command

        $ FTNCHEK :== $disk:[directory]FTNCHEK

   where you substitute the disk and directory names where the file
   FTNCHEK.EXE resides.  This command must be executed once per
   login.  It is suggested you put this command into your LOGIN.COM
   file.

   The BUILD procedure also creates a VMS help library named
   FTNCHEK.HLB.  To access it from the VMS HELP command, you must
   give the command

        $ DEFINE HLP$LIBRARY disk:[directory]FTNCHEK.HLB"

   Again, this command must be executed once per login to have effect.

   Note that BUILD.COM uses the files CC.COM and LINK.COM which are
   conditional compilation and link scripts that allow re-making
   ftnchek by compiling only what has changed.

(2b) ALPHA/VMS

   Same as (2a) except use BUILD-ALPHA.COM instead.


(3) MS-DOS with Borland C

   Rename the file "makefile.bc" to "makefile" and then give the
   command:

        C> MAKE

   Note: Version 2.8 at this time requires the SMALL_MACHINE option in
   Borland C.  There is a bug in Borland C malloc and the workaround
   has not yet been re-implemented in this version of ftnchek.

(4) Macintosh Programmer's Workshop (MPW)

   Rename the file "makefile.mpw" to "makefile".  Edit the file,
   changing character '+' to CHAR(182), option-d on the Macintosh
   keyboard; and the character '/' to CHAR(196), option-f.  Then
   use the "make" command to create Ftnchek.

(5) Other systems

   It should suffice simply to compile all the ".c" files (omitting
   shell_mung.c) and link them, .  The only differences among the
   versions for different operating systems have to do with the use of
   "/" vs. "-" as an option prefix, the default filename extension
   ".FOR" vs. ".f", and the selection of some system-specific language
   extensions.  Selection among these options is done by defining a
   macro name for each system.  The VAX/VMS compiler pre-defines the
   macro name "VMS", while the Turbo C compiler pre-defines
   "__TURBOC__".  The macro names "UNIX" and "MSDOS" are not
   pre-defined and must be defined on the compiler command line or by
   editing ftnchek.h if they are desired.


It has been reported that ftnchek gives parse errors on file average.f
on a Cray Y-MP running UNICOS 8.0 3.0 and SCC 4.0.1. This can be
worked around by creating a new version of fortran.c from fortran.y
using yacc (not bison) on another platform (e.g. IBM/RS6000; the Cray
yacc gave up).  The command to do this is ``rm fortran.c; make
fortran.c''.  Use this version of fortran.c to build ftnchek on the
Cray.

Once Ftnchek is working, you can test it by giving the command:

        $ ftnchek -list -sym average

Then compare the output against the file ``average.out''.  A more
thorough checkout is possible on Unix systems by giving the ``make
check'' command described above.


           NEW FEATURES
           ------------

A new feature included in version 2.8.3 allows you to use ftnchek to
create a graphical representation of the subprogram hierarchy of your
programs.  This feature makes use of the freely available program VCG
which displays graphs in an X-window environment.  To include this
feature, compile ftnchek with the macro name VCG_SUPPORT defined.  In
unix, you can do this by adding the phrase "OPTIONS=VCG_SUPPORT" to
the make command line.  This option adds a new command line switch,
-vcg, to the set of ftnchek options.  The code to generate the vcg
graph description was provided by [e-mail].  The
graph description is embedded in the ftnchek output.  To reduce it to
a file suitable for input to VCG, run the ftnchek output through the
filter fcl2vcg, provided with the distribution.  If you build ftnchek
with this option, you should install this script in a directory on
your path with the command ``make install-vcg''.


Another new feature is a tool to convert ftnchek declarations files
(produced with the -makedcl option) into a format suitable for use as
include files, to allow the elimination of redundant code.  Provided
by Nelson H. F. Beebe ([e-mail]).  This tool is installed
automatically by the ``make install'' command.


           AUXILIARY FILES
           ---------------

This section describes the auxiliary and documentation files included
with the distribution.

The file average.f contains the example program used in the
documentation, and average.out is the result of running Ftnchek on it.
VAX/VMS users should rename "AVERAGE.F" to "AVERAGE.FOR".

The files with extension ``.com'' contain commands for building
ftnchek on VAX and ALPHA systems.

The file fcl2vcg.sh is a shell script to be installed as fcl2vcg,
which is usable on Unix systems to convert ftnchek's output with the
-vcg option into a form suitable for input to the VCG program.

The file dcl2inc.sh is a shell script to be installed as dcl2inc,
which converts declarations files into include files.

The file named makefile is the same as makefile.unix.  The other
makefiles are specialized for Borland C (IBM PC), Macintosh
Programmer's Workbench, and UNIX or UNIX-like systems.

The file fortran.y contains the grammar from which the parser
fortran.c was created.  (The file fortran.c has been trimmed to
shorten it.)  The file fortran.y itself is not needed to compile
Ftnchek.

The file shell_mung.c is needed only for the VMS version of Ftnchek.
It is from the GNU project.

The file pointer.patch provides a modification for minimal
support of ``Cray pointer'' syntax.

Documentation: The file ftnchek.doc is a flat text file
containing the ftnchek user's manual.  The file ftnchek.ps is a
PostScript version of the same.  Ftnchek.hlp is for making a HELP
library for VMS systems.  Ftnchek.man is the file from which
these files and the Unix manual page are derived.  PATCHES
contains a list of changes made since the original release of
version 2.8.

The file ftnchek.def is a module definition file for IBM PC-OS/2.

The UNIX Makefile employs a private script, man2ps, for converting
manual pages to PostScript (linked to names me2ps, mm2ps, and ms2ps,
it will support the -me, -mm, and -ms formats as well).  The script
currently knows about GNU groff, Sun Solaris 2.x troff + dpost and
psroff; it will use any of these, with groff preferred.  For troff +
dpost, if you get errors like this

troff: Can't open /usr/lib/font/devpost/C.out; line 818, file <standard input>

you can repair them if you have appropriate privileges:

% cd /usr/lib/font/devpost
% ln CO C
% ln CO.name C.name
% ln CO.out C.out

These commands simply create links between a Courier font that Sun
named CO, and the one named C that is expected by ftnchek.man.  If
some troff expert knows a better way to handle this, please tell us.
Additional alternatives in the man2ps script to support ditroff and
other vendors' troff-to-PostScript solutions will also be welcome.




             CUSTOMIZING
             -----------

This section gives details about using macro names to control the
system-dependent choices available in compiling Ftnchek.

Ftnchek has a number of fixed internal parameters that affect its
operation, such as the symbol table sizes and support for various
extensions and particular operating systems.  The following is a
description of the most important of these parameters.  They are
implemented as C language macro names.  If you wish to change a
parameter defined by one of these macros, it is necessary to recompile
Ftnchek with the macro definition changed to the desired value.

Briefly, the effect of the macro names specifying the system is as
follows: If VMS or __TURBOC__ or MSDOS is defined, then both "/" and
"-" are allowed as option prefixes.  Otherwise only "-" is allowed.
If VMS or __TURBOC__ or MSDOS is defined, then ".FOR" will be the
default extension for source files, otherwise ".f" is used.  If VMS is
defined, then the VMS extensions controlled by VMS_INCLUDE,
VMS_INTRINSICS, and VMS_IO will be supported.  If UNIX is defined,
then the UNIX nonstandard intrinsic functions will be supported.  More
detailed control over these options is possible by defining other
macro names described below.

This can usually be done without editing any of the source files, by
specifying the macro definition on the C compiler command line.  Under
UNIX, this is done with the -D option.  For example, to define the
macro BpW that sets the default word size to be eight bytes, the
compiler would be invoked with the additional option -DBpW=8.  Under
VMS, the corresponding option would be /DEFINE=("BpW=8").  For other
systems, consult your C compiler manual.

Unless otherwise noted, the following macro names need not have any
particular value.  They only need to be defined in order to have
effect.  For more details on these parameters, look at ftnchek.h.

  Macro                 Meaning                           Remarks
UNIX                  Compile Ftnchek for UNIX-like    Default for most
                       operating system                 choices
VMS                   Compile Ftnchek for VAX/VMS      Automatically defined
                       operating system                 by VAX C compiler
MSDOS                 Compile Ftnchek for MS-DOS       Automatic if compiler
                       operating system                 is Turbo C

VMS_IO                Add support for VMS-Fortran      Implied by VMS unless
                       I/O keywords                     NO_VMS_IO defined
NO_VMS_IO             Do not support VMS-Fortran       For VMS but not VMS_IO
                       I/O keywords
VMS_INCLUDE           Add support for VMS-style        Implied by VMS unless
                       INCLUDE statement features        NO_VMS_INCLUDE defined
                       (default extension, /NOLIST)
NO_VMS_INCLUDE        Do not support VMS-style         For VMS but not
                       INCLUDE statement features       VMS_INCLUDE
OPTION_PREFIX_SLASH   Allow options to start with      Implied by VMS and by
                       either - or /.                   MSDOS
DEF_SRC_EXTENSION     Default extension expected       Defaults:
                       for input source files            VMS, MSDOS: ".for"
                                                        All others: ".f"
DEF_LIST_EXTENSION    Default extension for output     Default: ".lis"
                       list-files
DEF_PROJ_EXTENSION    Default extension for input      Default: ".prj"
                       and output project files
DEF_DCL_EXTENSION     Default extension for            Default: ".dcl"
                       declaration files
STDIN_PROJ_FILENAME   Output project-file name used    Default: "ftnchek.prj"
                       when input source is stdin

DEC_TABS              Default value of -tab option    Default = 0 (NO)

STRICT_SYNTAX         Disallow inline (with !         Individual options
              character). Always warn about   controlled by macros
              underscores or dollar signs     listed below.
              in variable names, INCLUDE or
              DO .. ENDDO statements,
              variable field widths in
              FORMAT, and hex, octal and
              binary constants.

INLINE_COMMENT_CHAR   Allow Inline comments starting   Must be defined
                       with '!'                          as '!'

VCG_SUPPORT           Add the -vcg switch to allow     Default: no vcg
                      call graph to be visualized.        support


The following macros are used to control the default treatment of some
special syntax extensions.  The default value of each macro is 1,
which means that the corresponding extension will be warned about only
if the -f77 flag is set.  If STRICT_SYNTAX is defined, then the
default value of each macro will be 0, which means that the extension
will be warned about regardless of the status of the -f77 flag.  In
either case the extension will be correctly processed.  The default
setting of each individual macro can be overridden by an explicit
define.  The plan is eventually to turn these macro values into
default values which could be changed at runtime by command-line
flags, but at present there is no such option.

ALLOW_DO_ENDO         DO ... ENDDO statements
ALLOW_DOLLARSIGNS     Dollar signs in variable
                       names
ALLOW_FORMAT_DOLLARSIGNS  $ control code in
                       FORMAT statements
ALLOW_INCLUDE         INCLUDE 'filename' statement
ALLOW_QUOTEMARKS      Strings delimited by "quote
                       marks"
ALLOW_TYPELESS_CONSTANTS  Z'19AF' and similar hex,
                       octal and binary constants
ALLOW_UNDERSCORES     Underscores in variable
                       names
ALLOW_UNIX_BACKSLASH  Backslash escape in strings
ALLOW_UNIX_CPP        UNIX preprocessor
                       lines starting with #
ALLOW_VARIABLE_FORMAT Accept <integer_expr> in format
                       for repeat or field width

The nonstandard double complex intrinsic functions are always
supported since they are needed by the double complex datatype.  Other
groups of nonstandard functions can be selected by the following group
of macros.

STANDARD_INTRINSICS   Do not support extended set
                       of intrinsic functions
NONSTD_INTRINSICS     Support commonly available       Default behavior
                       intrinsic functions
UNIX_INTRINSICS       Support UNIX-specific            Default if UNIX defined
                       intrinsic functions
NO_UNIX_INTRINSICS    Do not support UNIX-specific
                       intrinsic functions
VMS_INTRINSICS        Support VMS-specific             Default if VMS defined
                       intrinsic functions
NO_VMS_INTRINSICS     Do not support VMS-specific
                       intrinsic functions

NO_BLANKS_IN_NUMBERS  Numeric constants cannot have   Default: blanks allowed
                       embedded blanks.
BLANKS_IN_NUMBERS     Numeric constants may have
                       embedded blanks.

RAND_NO_ARG           RAND/IRAND function has no       Default behavior:
                       argument                         allows both 0 argument
RAND_ONE_ARG          RAND/IRAND function has one       and 1 argument forms
                       argument

ENV_PREFIX            Prefix for environment           Default "FTNCHEK_"
                       variables that set options

MAXLINE               Maximum input line length.       Default 132
                        Ignores past this.
MAXIDSIZE             Longest identifier allowed       Default 31
MAX_SRC_TEXT          Longest text string of a token   Default 20*66
MAX_CHAR_CODE         Largest char value               Default 255
MAX_INCLUDE_DEPTH     Max nesting depth of include     Default 16
                       files
MAXEXPRTEXT           Length of expr text saved in     Default 15
                       arg lists
ENV_INCLUDE_VAR       Name of environment variable     Default "INCLUDE"
                       specifying include directory

DEFAULT_INCLUDE_DIR   Name of default include          Defaults:
                       directory                        UNIX: "/usr/include"
                                                        VMS: "SYS$LIBRARY:"
                                                        MSDOS: "\\include"


The following macros specify various internal table sizes.  If neither
SMALL_MACHINE nor LARGE_MACHINE is defined, intermediate table sizes
will be used.  In any case, individual table sizes can be chosen by
defining the corresponding macro name.  The defaults for the three
size choices (small, default, large) are listed in the Remarks column.

SMALL_MACHINE         Table sizes appropriate for a
                       PC without much memory
LARGE_MACHINE         Table sizes appropriate for a
                       mainframe or workstation

                                                      small  default large
HASHSZ                Identifier hash table (elements)  798   2002  20930
LOCSYMTABSZ           Local symbol table (entries)      300    800   8000
GLOBSYMTABSZ          Global symbol table (entries)     400   1200  12000
   The following sizes are *chunk sizes*, specifying the initial table
   size and the size of new blocks to allocate when initial amounts
   are used up.  Optimum sizes are dependent on properties of alloc
   function, and do not set limits on total amounts of space.
STRSPACESZ            Identifier string space (bytes)  4000  10000  10000
PARAMINFOSPACESZ      Parameter info field space     20     50    200
            (ParamInfo's)
TOKHEADSPACESZ        Token list header element space    50    200    500
                       (TokenListHeader's)
TOKENSPACESZ          Token list space (tokens). Used   200   1000  10000
                       to store subroutine arguments
                       and other temporary lists.
ARGLISTHEADSZ         Argument list header element      300   1500  15000
                       space (ArgListHeader's)
ARGLISTELTSZ          Argument list element space      1000   5000  50000
                       (ArgListElement's)
COMLISTHEADSZ         Common block list header space    200   1000 10000
                       (ComListHeader's)
COMLISTELTSZ          Common block list element space  1000   4000 50000
                       (ComListElement's)
PTRSPACESZ            Pointers to array dim text and    200    400  2000
                       parameter text (char *'s)
BpW                   Default bytes per word.          Default=4

WRAP_COLUMN           Default value for -wrap          Default=79
                      setting.


For the truly adventurous:

Ftnchek has three different memory-management schemes to choose from.
In the default case, space for the hashtable and the local and global
symbol tables is allocated at compile time.  These tables cannot
change size afterwards.  Initial space for strings, tokens (in lists
and trees), token list headers, token source text, pointers to array
dim and parameter text is allocated at compile time.  These areas can
grow as needed by allocating additional chunks that are chained
together in a linked-list arrangement.  Space for argument list
headers and elements, and common list headers and elements starts at
zero and new chunks are allocated as needed.  (None of the newly
allocated chunks are freed, since it is considered likely that the
space will be
needed again.)
This scheme is well
suited to machines with large address spaces and virtual memory.  The
sizes of the fixed tables and chunk sizes for the others can be chosen
in three standard sets: default, SMALL_MACHINE, and LARGE_MACHINE.
The latter is preferred for any virtual-memory machine since memory
does not become "really" allocated until needed.

The second memory-management scheme is selected by the compile-time
option DYNAMIC_TABLES.  In this case, the fixed-size arrays for the
hashtable and the local and global symbol tables are replaced by
pointers, and the space they point to is allocated at the start of
program execution.  Everything else is the same.  This version runs
somewhat slower than the first scheme on machines I have tested.  I
have not proceeded to take advantage of the possibility of letting the
table sizes be selected at run time by means of command-line settings.
To do so would require moving the allocation step performed by
init_tables() to just before the start of processing, analogously to
init_typesizes().  It would also need a set of command-line options to
be installed for specifying the different table sizes.


  --- Note: the third scheme is no longer supported

The third scheme was invented to work around a problem with
malloc/calloc in Borland C on the IBM PC.  It is selected by the
compile-time option T_ALLOC.  (It is automatically selected for Turbo
C.)  Under the huge memory model, calloc is supposed to make use of
all memory from the top of the program stack to the end of RAM.  In
early versions of Borland C it fails after allocating about 55K worth.

In this scheme the needed space is supplied from fixed-size tables,
one for each of the main users of dynamically allocated memory.  Each
table is in a separately compiled module containing only the routine
that allocates space for one or another type of data object, so that
each can occupy up to 64K bytes.

When the -makedcls option was added to ftnchek in version 2.8, it
greatly increased the demand for dynamically allocated memory.  As a
result, the overall 640K limit on program space makes it difficult for
ftnchek to process anything but very small programs.  Instead you
should use dgjpp or a compiler with similar capability to produce a
version that runs in 32-bit virtual mode, so that the entire amount of
installed memory can be utilized.

You should not define DYNAMIC_TABLES at the same time as T_ALLOC.