home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / fchk294s.zip / ftnchek-2.9.4 / README < prev    next >
Text File  |  1996-05-15  |  22KB  |  476 lines

  1.          README file for Ftnchek Version 2.9
  2.  
  3. Author: Robert Moniot
  4.     Fordham University
  5.     New York, NY  10023  USA
  6.     Telephone: (212) 636-6311
  7.     Internet:  moniot@mary.fordham.edu
  8.  
  9. Date:    March 4, 1996
  10.  
  11. Ftnchek is written in a portable style of C.  You must have a C
  12. compiler for the machine on which you wish to build it.
  13. Information about the latest version and the status of the project can be
  14. obtained by the Internet command ``finger ftnchek@mary.fordham.edu''.
  15.  
  16. If the file you received is a UNIX compressed tar file, suffix .Z, you
  17. should first unzip it using the UNIX ``uncompress'' command, and then
  18. give it as input to ``tar'' to unpack the files.  For example, assuming
  19. the file has been placed in the desired directory, and is named
  20. ftnchek.tar.Z, you would give the two UNIX commands
  21.     uncompress ftnchek.tar.Z
  22.     tar -xf ftnchek.tar
  23. If the suffix is .gz instead of .Z, use the program ``gunzip'' in
  24. place of ``uncompress''.  The gunzip program is publicly available
  25. from the GNU project.
  26.  
  27. The tar command creates a directory named ftnchek-2.9.1 containing the
  28. files of the distribution.  These files are described briefly below.
  29. You should change directory to this directory and follow the
  30. installation instructions.
  31.  
  32.  
  33.           INSTALLING FTNCHEK
  34.           ------------------
  35.  
  36. See the file INSTALL for detailed instructions on how to install
  37. ftnchek on your system.  Once Ftnchek is working, you can test it by
  38. giving the command:
  39.  
  40.         $ ftnchek -list -sym average
  41.  
  42. Then compare the output against the file ``average.out''.  A more
  43. thorough checkout is possible on Unix systems by giving the ``make
  44. check'' command described above.
  45.  
  46.  
  47.            NEW FEATURES
  48.            ------------
  49.  
  50. Here are the new features in version 2.9, aside from bug fixes:
  51.  
  52.     o New warnings: statement function defined but not used; and
  53.       common block and subprogram that have the same name.
  54.  
  55.     o The -f77, -portability, -pretty, and -truncation options now
  56.       take lists of keywords to provide finer control over
  57.       warnings.  The -hollerith flag is eliminated: use
  58.       -port=hollerith instead.
  59.  
  60.     o The -backslash and -tab flags are replaced with -source=num
  61.       setting, which also includes control of VMS syntax for
  62.       INCLUDE statement (defaulting extension, /LIST qualifier).
  63.  
  64.     o New setting -intrinsic=num to control treatment of
  65.       nonstandard intrinsic functions.  Ones digit selects which
  66.       set of intrinsic functions to recognize.  Tens digit
  67.       controls RAND syntax and hundreds digit IARGC syntax.  These
  68.       were formerly compilation options when building ftnchek.
  69.  
  70.     o The -usage flag is now a 3-digit number, for separate
  71.       control of checking of subprograms, common variables, and
  72.       local variables.  See the manual for details.
  73.  
  74.     o The -calltree option now takes various numeric settings to
  75.       specify options for the form of the output.
  76.  
  77.     o The -noverbose flag is changed to -quiet.
  78.  
  79.     o New flag -version to print ftnchek's name and version.
  80.  
  81.     o New flag, -nocheck, useful to suppress warnings when using
  82.       ftnchek for purposes other than checking.
  83.  
  84.     o New -makedcls value: 512=no-array-dimensions.  This bit is
  85.       for users who have code lacking type declarations so they
  86.       can insert the dcl files without change into the code.
  87.  
  88.     o Command-line numeric settings can omit the number, giving
  89.       them default turn-on values.
  90.  
  91.     o Ftnchek now reads a startup file named .ftnchekrc or
  92.       ftnchek.ini located in the current directory or in the home
  93.       directory.
  94.  
  95.     o Made the non-parenthesis PARAMETER statement variant part of
  96.       the distribution, i.e. no longer as a patch accompanying the
  97.       source.
  98.  
  99.     o Made the "Cray" POINTER statement part of the distribution,
  100.       i.e. no longer as a patch accompanying the source.
  101.  
  102.     o The support for VCG has been improved so that ftnchek now
  103.       sends VCG output to a file that is suitable for direct input
  104.       to xvcg.  The script fcl2vcg is now obsolete.  Support for
  105.       VCG is now automatic.
  106.  
  107.     o Some improvements to help in maintaining and distributing
  108.       ftnchek: the source code has been augmented with function
  109.       prototypes, and a configure script is used to handle
  110.       variations among systems automatically.  Hopefully some of
  111.       the glitches in installation will be smoothed over by this.
  112.       (Please report any glitches that remain so the configure
  113.       script can be fixed.)
  114.  
  115.                  SOURCE FILES
  116.                  ------------
  117.  
  118. The minimum set of source files needed to compile ftnchek is:
  119.  
  120. Header files:
  121.     ftnchek.h intrins.h iokeywds.h keywords.h
  122.     symtab.h tokdefs.h
  123.  
  124. C source:
  125.     exprtype.c forlex.c fortran.c ftnchek.c
  126.     pgsymtab.c plsymtab.c project.c symtab.c
  127.  
  128. For VAX, there is also required:
  129.     shell_mung.c
  130.  
  131. An associated file, not needed to compile ftnchek, is the Yacc grammar:
  132.     fortran.y
  133. The file fortran.c is generated from fortran.y by yacc or bison.  The
  134. file tokdefs.h is a copy of the y.tab.h file also generated from fortran.y.
  135.  
  136. There is a module definition file for IBM PC-OS/2:
  137.     ftnchek.def 
  138.  
  139.  
  140.            AUXILIARY FILES
  141.            ---------------
  142.  
  143. This section describes the auxiliary and documentation files included
  144. with the distribution.
  145.  
  146. The example program used in the documentation, the result of running
  147. Ftnchek on it, and the example program, corrected:
  148.     average.f average.out correct.f
  149.  
  150. NOTE: VAX/VMS users should rename "AVERAGE.F" to "AVERAGE.FOR".
  151.  
  152. DCL command files for building ftnchek on DEC VAX and Alpha under VMS:
  153.     build.com build-alpha.com cc.com link.com link-alpha.com
  154.  
  155. An awk script which converts declarations files into include files,
  156. and a file used to create a shell script (to be installed as dcl2inc):
  157.     dcl2inc.awk dcl2inc.sh.in
  158.  
  159. Files used to create Makefile:
  160.     configure configure.in Makefile.in
  161.  
  162. Specialized makefiles for Borland C (IBM PC), Macintosh
  163. Programmer's Workbench, OS/2 and UNIX or UNIX-like systems:
  164.     makefile.bc makefile.mpw makefile.os2 makefile.generic makefile.unix
  165.  
  166. The file configure_os2.cmd mimics configure in an OS/2 environment.
  167. Use it to create a Makefile from Makefile.in, substituting appropriate
  168. values for options and command paths for your system.  The file
  169. makefile.os2 is no longer supported, but should work if
  170. configure_os2.cmd does not work for you.
  171.  
  172. The file makefile.unix is the former distribution makefile, with lots
  173. of specific targets.  It is no longer being maintained, but should
  174. still work.  Use configure to build a local Makefile instead.  If you
  175. cannot use configure for some reason, makefile.generic should be OK
  176. for most cases, and can be fixed up to suit your needs.  The file
  177. makefile.generic is created from Makefile.in by the shell script
  178. configure.generic.  It uses vanilla configuration options.  The
  179. purpose of makefile.generic is to provide a starting point for editing
  180. to suit a non-Unix system.
  181.  
  182. Documentation files:
  183.     ftnchek.doc    ftnchek user's manual in flat text format.
  184.     ftnchek.ps    PostScript version of the same.
  185.     ftnchek.hlp    Source for a HELP library for VMS systems.
  186.     ftnchek.man    The file from which these files are derived.
  187.     dcl2inc.doc    dcl2inc user's manual in flat text format.
  188.     dcl2inc.ps    same in PostScript.
  189.     man2ps        script for converting man pages to PostScript
  190.  
  191. The Unix manual page, ftnchek.1, is generated from ftnchek.man during the
  192. installation process.  The VMS help library, ftnchek.hlb, is generated
  193. from ftnchek.hlp by the build.com script.
  194.  
  195. A list of changes made since the original release of this version:
  196.     PATCHES
  197.  
  198. The UNIX Makefile employs a private script, man2ps, for converting
  199. manual pages to PostScript (linked to names me2ps, mm2ps, and ms2ps,
  200. it will support the -me, -mm, and -ms formats as well).  The script
  201. currently knows about GNU groff, Sun Solaris 2.x troff + dpost and
  202. psroff; it will use any of these, with groff preferred.  For troff +
  203. dpost, if you get errors like this
  204.  
  205. troff: Can't open /usr/lib/font/devpost/C.out; line 818, file <standard input>
  206.  
  207. you can repair them if you have appropriate privileges:
  208.  
  209. % cd /usr/lib/font/devpost
  210. % ln CO C
  211. % ln CO.name C.name
  212. % ln CO.out C.out
  213.  
  214. These commands simply create links between a Courier font that Sun
  215. named CO, and the one named C that is expected by ftnchek.man.  If
  216. some troff expert knows a better way to handle this, please tell us.
  217. Additional alternatives in the man2ps script to support ditroff and
  218. other vendors' troff-to-PostScript solutions will also be welcome.
  219.  
  220.  
  221.  
  222.              CUSTOMIZING
  223.              -----------
  224.  
  225. This section gives details about using macro names to control the
  226. system-dependent choices available in compiling Ftnchek.
  227.  
  228. NOTE: if you choose to alter the definitions of any of these macros
  229. from their default values, then "make check" will probably give some
  230. differences.  You should first build ftnchek using the default
  231. definitions, run "make check" to catch any problems, then rebuild
  232. ftnchek with your preferred definitions before doing "make install".
  233.  
  234. Ftnchek has a number of fixed internal parameters that affect its
  235. operation, such as the symbol table sizes and support for various
  236. extensions and particular operating systems.  The following is a
  237. description of the most important of these parameters.  They are
  238. implemented as C language macro names.  If you wish to change a
  239. parameter defined by one of these macros, it is necessary to recompile
  240. Ftnchek with the macro definition changed to the desired value.
  241.  
  242. Briefly, the effect of the macro names specifying the system is as
  243. follows: If VMS or __TURBOC__ or MSDOS is defined, then both "/" and
  244. "-" are allowed as option prefixes.  Otherwise only "-" is allowed.
  245. If VMS or __TURBOC__ or MSDOS is defined, then ".FOR" will be the
  246. default extension for source files, otherwise ".f" is used.  If VMS is
  247. defined, then support for VMS extensions is enabled by default: this
  248. changes the default values of options -source to 2 (VMS include
  249. syntax) and -intrinsics to 223 (VMS intrinsics set).  If UNIX is
  250. defined, then only "-" is allowed as an option prefix, the default for
  251. -source is 0 and -intrinsics is 222 (UNIX intrinsic set).  More
  252. detailed control over these options is possible by defining other
  253. macro names described below.
  254.  
  255. This can usually be done without editing any of the source files, by
  256. specifying the macro definition on the C compiler command line.  Under
  257. UNIX, this is done with the -D option.  For example, to define the
  258. macro BpW that sets the default word size to be eight bytes, the
  259. compiler would be invoked with the additional option -DBpW=8.  Under
  260. VMS, the corresponding option would be /DEFINE=("BpW=8").  For other
  261. systems, consult your C compiler manual.  When using make, specify
  262. these definitions by setting the macro OPTIONS, e.g.
  263.     make "OPTIONS= -DBpW=8"
  264. If you want to put such definitions into the Makefile, do not edit
  265. Makefile.  Edit Makefile.in and re-run the configure script.
  266.  
  267. Unless otherwise noted, the following macro names need not have any
  268. particular value.  They only need to be defined in order to have
  269. effect.  For more details on these parameters, look at ftnchek.h.
  270. These fall into three broad groups: system-dependent aspects, features
  271. and options, and table sizes.
  272.  
  273.   --- System-dependent defines
  274.  
  275.   Macro                 Meaning                           Remarks
  276. UNIX                  Compile Ftnchek for UNIX-like    Default for most
  277.                        operating system                 choices
  278. VMS                   Compile Ftnchek for VAX/VMS      Automatically defined
  279.                        operating system                 by VAX C compiler
  280. MSDOS                 Compile Ftnchek for MS-DOS       Automatic if compiler
  281.                        operating system                 is Turbo C
  282. NO_PROTOTYPES         Compiler does not accept         Defined by configure
  283.                        ANSI C prototypes
  284. NO_FLOATING_POINT     Suppress floating point          Unimportant--define if
  285.                        computations internally           no hardware f.p.
  286. DEC_TABS              Default value of -source bit 1   Default = 0 (NO)
  287. VMS_INCLUDE           Default value of -source bit 2   Default=0 for Unix,
  288.                                                          1 for VMS
  289. UNIX_BACKSLASH        Default value of -source bit 4   Default = 0 (NO)
  290. OPTION_PREFIX_SLASH   Allow options to start with      Implied by VMS and by
  291.                        either - or /.                   MSDOS
  292. NO_OPTION_PREFIX_SLASH Prohibit options with /         To override VMS or
  293.                              MSDOS default
  294. SPECIAL_HOMEDIR       Home directory for non-unix     VMS default:"SYS$DISK:[]"
  295. UNIX_RC_FILE          Name of startup file.            Default: ".ftnchekrc"
  296. NONUNIX_RC_FILE       Alternate startup filename.      Default: "ftnchek.ini"
  297. DEF_SRC_EXTENSION     Default extension expected       Defaults: VMS, MSDOS:
  298.                        for input source files            ".for" All others: ".f"
  299. DEF_LIST_EXTENSION    Default extension for output     Default: ".lis"
  300.                        list-files
  301. DEF_PROJ_EXTENSION    Default extension for input      Default: ".prj"
  302.                        and output project files
  303. DEF_DCL_EXTENSION     Default extension for            Default: ".dcl"
  304.                        declaration files
  305. DEF_INC_EXTENSION     Default extension for            Default:
  306.                        include files                     DEF_SRC_EXTENSION
  307. DEF_VCG_EXTENSION     Default extension for VCG        Default: ".vcg"
  308.                        output files
  309. STDIN_PROJ_FILENAME   Output project-file name used    Default: "ftnchek.prj"
  310.                        when input source is stdin
  311. ENV_PREFIX            Prefix for environment           Default "FTNCHEK_"
  312.                        variables that set options
  313.  
  314.  
  315.    --- macros that control ftnchek behavior (syntax, options, etc.)
  316. VCG_SUPPORT           Add the -vcg switch to allow     Default: -vcg supported
  317.                        call graph to be visualized.
  318. NO_VCG_SUPPORT        Suppress -vcg support
  319. VCG_GRAPH_OPTIONS     Global vcg graph options.       "color: lightgray\n"
  320. STRICT_SYNTAX         Set default -f77=all             Default is -f77=none
  321. STRICT_PORTABILITY    Set default -port=all            Default is -port=none
  322. UGLY_IS_OK            Set default -pretty=none         Default is -pretty=all
  323. LAX_TRUNCATION        Set default -trunc=none          Default is -trunc=all
  324.  
  325. The following macros control whether ftnchek accepts certain syntax
  326. extensions.  They are all defined and cannot be undefined without
  327. editing ftnchek.h.  If the macros are undefined, then support for the
  328. extension is completely removed.  This means that the corresponding
  329. extension will generate syntax or parse errors, not non-standard
  330. warnings.  Some users might want to do this to make ftnchek smaller
  331. and more efficient, or out of a sense of fanaticism.
  332.  
  333. ALLOW_CRAY_POINTERS    Cray pointer syntax
  334. ALLOW_DOLLARSIGNS    $ in variable names
  335. ALLOW_DO_ENDDO        DO ... ENDDO and related
  336. ALLOW_INCLUDE        INCLUDE statement
  337. ALLOW_QUOTEMARKS    Strings delimited by "
  338. ALLOW_TYPELESS_CONSTANTS  Binary, octal, hex
  339. ALLOW_UNDERSCORES    _ in variable names
  340. ALLOW_UNIX_BACKSLASH    Unix escape sequences in strings
  341. ALLOW_UNIX_CPP        Unix C preprocessor directives
  342. ALLOW_VMS_IO        VMS I/O keywords
  343.  
  344. The following macros determine the default value of the -intrinsic
  345. setting.  The nonstandard double complex intrinsic functions are
  346. always recognized since they are needed by the double complex
  347. datatype.  Other groups of nonstandard functions can be selected to be
  348. recognized by default using these macros.
  349.  
  350. STANDARD_INTRINSICS   Do not recognize extended set
  351.                        of intrinsic functions (Set 0)
  352. NONSTD_INTRINSICS     Support commonly available       Default behavior
  353.                        intrinsic functions (Set 1)
  354. UNIX_INTRINSICS       Support UNIX-specific            Default if UNIX defined
  355.                        intrinsic functions (Set 2)
  356. NO_UNIX_INTRINSICS    Do not support UNIX-specific
  357.                        intrinsic functions
  358. VMS_INTRINSICS        Support VMS-specific             Default if VMS defined
  359.                        intrinsic functions (Set 3)
  360. NO_VMS_INTRINSICS     Do not support VMS-specific
  361.                        intrinsic functions
  362. DEF_INTRINSIC_SET     Specify intrinsic set            Override above defaults
  363.  
  364. RAND_NO_ARG           RAND/IRAND function has no       Default behavior:
  365.                        argument                         allows both 0 argument
  366. RAND_ONE_ARG          RAND/IRAND function has one       and 1 argument forms
  367.                        argument
  368. IARGC_NO_ARG          IARGC has no argument            Default behavior:
  369. IARGC_ONE_ARG         IARGC has 1 argument              both forms allowed
  370.  
  371. NO_BLANKS_IN_NUMBERS  Numeric constants cannot have    Default: blanks allowed
  372.                        embedded blanks.
  373. BLANKS_IN_NUMBERS     Numeric constants may have
  374.                        embedded blanks.
  375. BpW                   Default bytes per word           Default=4
  376.                         (for -wordsize setting) 
  377.  
  378.  
  379.   --- Macros that set table sizes, limits, etc.
  380.  
  381. MAXLINE               Maximum input line length.       Default 132
  382.                         Ignores past this.
  383. MAXIDSIZE             Longest identifier allowed       Default 31
  384. MAX_SRC_TEXT          Longest text string of a token   Default 20*66
  385. MAX_CHAR_CODE         Largest char value               Default 255
  386. MAX_INCLUDE_DEPTH     Max nesting depth of include     Default 16
  387.                        files
  388. MAXEXPRTEXT           Length of expr text saved in     Default 15
  389.                        arg lists
  390. MAX_RC_LINE           Max input line in rc file        Default 500
  391. RC_COMMENT_CHAR       Start of comment in rc file      Default '#'
  392. ENV_INCLUDE_VAR       Name of environment variable     Default "INCLUDE"
  393.                        specifying include directory
  394.  
  395. DEFAULT_INCLUDE_DIR   Name of default include          Defaults:
  396.                        directory                        UNIX: "/usr/include"
  397.                                                         VMS: "SYS$LIBRARY:"
  398.                                                         MSDOS: "\\include"
  399.  
  400.  
  401. The following macros specify various internal table sizes.  If neither
  402. SMALL_MACHINE nor LARGE_MACHINE is defined, intermediate table sizes
  403. will be used.  In any case, individual table sizes can be chosen by
  404. defining the corresponding macro name.  The defaults for the three
  405. size choices (small, default, large) are listed in the Remarks column.
  406.  
  407. SMALL_MACHINE         Table sizes appropriate for a
  408.                        PC without much memory
  409. LARGE_MACHINE         Table sizes appropriate for a
  410.                        mainframe or workstation
  411.  
  412.                                                       small  default large
  413. HASHSZ                Identifier hash table (elements)  798   2002  20930
  414. LOCSYMTABSZ           Local symbol table (entries)      300    800   8000
  415. GLOBSYMTABSZ          Global symbol table (entries)     400   1200  12000
  416.    The following sizes are *chunk sizes*, specifying the initial table
  417.    size and the size of new blocks to allocate when initial amounts
  418.    are used up.  Optimum sizes are dependent on properties of alloc
  419.    function, and do not set limits on total amounts of space.
  420. STRSPACESZ            Identifier string space (bytes)  4000  10000  10000
  421. PARAMINFOSPACESZ      Parameter info field space     20     50    200
  422.             (ParamInfo's)
  423. TOKHEADSPACESZ        Token list header element space    50    200    500
  424.                        (TokenListHeader's)
  425. TOKENSPACESZ          Token list space (tokens). Used   200   1000  10000
  426.                        to store subroutine arguments
  427.                        and other temporary lists.
  428. ARGLISTHEADSZ         Argument list header element      300   1500  15000
  429.                        space (ArgListHeader's)
  430. ARGLISTELTSZ          Argument list element space      1000   5000  50000
  431.                        (ArgListElement's)
  432. COMLISTHEADSZ         Common block list header space    200   1000 10000
  433.                        (ComListHeader's)
  434. COMLISTELTSZ          Common block list element space  1000   4000 50000
  435.                        (ComListElement's)
  436. PTRSPACESZ            Pointers to array dim text and    200    400  2000
  437.                        parameter text (char *'s)
  438. WRAP_COLUMN           Default value for -wrap          Default=79
  439.                       setting.
  440.  
  441.  
  442. For the truly adventurous:
  443.  
  444. Ftnchek has two different memory-management schemes to choose from.
  445. In the default case, space for the hashtable and the local and global
  446. symbol tables is allocated at compile time.  These tables cannot
  447. change size afterwards.  Initial space for strings, tokens (in lists
  448. and trees), token list headers, token source text, pointers to array
  449. dim and parameter text is allocated at compile time.  These areas can
  450. grow as needed by allocating additional chunks that are chained
  451. together in a linked-list arrangement.  Space for argument list
  452. headers and elements, and common list headers and elements starts at
  453. zero and new chunks are allocated as needed.  (None of the newly
  454. allocated chunks are freed, since it is considered likely that the
  455. space will be
  456. needed again.)
  457. This scheme is well
  458. suited to machines with large address spaces and virtual memory.  The
  459. sizes of the fixed tables and chunk sizes for the others can be chosen
  460. in three standard sets: default, SMALL_MACHINE, and LARGE_MACHINE.
  461. The latter is preferred for any virtual-memory machine since memory
  462. does not become "really" allocated until needed.
  463.  
  464. The second memory-management scheme is selected by the compile-time
  465. option DYNAMIC_TABLES.  In this case, the fixed-size arrays for the
  466. hashtable and the local and global symbol tables are replaced by
  467. pointers, and the space they point to is allocated at the start of
  468. program execution.  Everything else is the same.  This version runs
  469. somewhat slower than the first scheme on machines I have tested.  I
  470. have not proceeded to take advantage of the possibility of letting the
  471. table sizes be selected at run time by means of command-line settings.
  472. To do so would require moving the allocation step performed by
  473. init_tables() to just before the start of processing, analogously to
  474. init_typesizes().  It would also need a set of command-line options to
  475. be installed for specifying the different table sizes.
  476.