README file for Ftnchek Version 2.7 Author: Robert Moniot Fordham University New York, NY 10023 USA Telephone: (212) 636-6311 Bitnet: MONIOT@FORDMULC Internet: moniot@mary.fordham.edu Date: August 1993 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. If the file you received is in the form of a "shell archive" or "shar" file, and you received it by electronic mail, you should first concatenate all parts in order (if it was sent in pieces), removing any mail headers. If you received it by ftp, this step should not be necessary. Next, if you have a UNIX system, simply feed it as input to the program "sh" to unpack it automatically. If you do not have a UNIX system, you will have to use your text editor to clip out each file manually. You will observe that each line of every file has been prefixed with the letter X. You should use your editor to remove all initial X's. It is also possible that tabs may have been converted to blanks during transport over the network. This should not matter for any files except the makefiles, where you should change any indented lines so that the indentation is replaced by a single tab. If the file you received is a Unix compressed tar file, 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 After accomplishing this step, you should find that you have received the following set of source files: exprtype.c ftnchek.h pgsymtab.c symtab.c forlex.c intrins.h plsymtab.c symtab.h fortran.c iokeywds.h project.c tokdefs.h ftnchek.c keywords.h These are all necessary for compiling Ftnchek on any system. You should also have received the following auxiliary files: average.f makefile makefile.unix newcome.c average.out makefile.bc newarge.c newcomh.c build.com makefile.mpw newargh.c shell_mung.c fortran.y 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 file build.com contains the commands for creating the executable and help library for VMS. 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 for transmission over electronic networks.) It 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 files newarge.c, newargh.c, newcome.c, and newcomh.c are used for the Borland C version. Documentation is in the files: ftnchek.doc ftnchek.hlp ftnchek.man ftnchek.ps The first is a flat text file. Ftnchek.hlp is for making a help library for VMS systems. Ftnchek.man and ftnchek.ps are provided for the convenience of those with access to nroff/troff or PostScript, respectively. 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". To install Ftnchek, follow the instructions below for your operating system. (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: IBM-RS6000 SOLARIS2.x SUNOS4.1 ULTRIX-MIPS GENERIC STARDENT SUNOS5.x UNIX SGI SUNOS4.0 Also, see below for options that allow compiling with bigger table sizes or accepting/rejecting certain syntax extensions. (2) 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. (3) MS-DOS with Turbo C Rename the file "makefile.bc" to "makefile" and then give the command: C> MAKE (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 new*.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. See the section below for more 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, VMS_IO, and VMS_TAB will be supported. If UNIX is defined, then the Unix nonstandard intrinsic functions will be supported and preprocessor directives will be tolerated. 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 UNIX_CPP Tolerate Unix preprocessor Default if UNIX defined lines starting with # NO_UNIX_CPP Do not tolerate them For UNIX w/o UNIX_CPP 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 VMS_TAB Accept VMS-style tab-formatted source lines. NO_VMS_TAB Do not accept tab-formatting. For VMS but not VMS_TAB 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 STDIN_PROJ_FILENAME Output project-file name used Default: "ftnchek.prj" when input source is stdin STRICT_SYNTAX Disallow underscores or dollar Each option can be signs in variable names, inline restored by a comments (with ! character) macro in next group INCLUDE or DO .. ENDDO statements. variable field widths in FORMAT, and hex, octal and binary constants The following seven macros are all defined by default unless STRICT_SYNTAX is defined. If STRICT_SYNTAX is defined, then any of the individual options can be selected by defining the corresponding individual macro. ALLOW_DOLLARSIGNS Allow dollar signs in variable names ALLOW_UNDERSCORES Allow underscores in variable names INLINE_COMMENT_CHAR Allow Inline comments starting Must be defined with '!' as '!' ALLOW_INCLUDE Support INCLUDE statement names ALLOW_DO_ENDO Support DO ... ENDDO statements names ALLOW_VARIABLE_FORMAT Accept in format for repeat or field width TYPELESS_CONSTANTS Accept Z'19AF' and similar hex octal and binary constants 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 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. MAXSTR Longest string constant stored Default 200 MAXIDSIZE Longest identifier allowed Default 31 MAX_INCLUDE_DEPTH Max nesting depth of include Default 16 files 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 STRSPACESZ Identifier string space (bytes) 2000 4000 40000 LOCSYMTABSZ Local symbol table (entries) 200 600 6000 GLOBSYMTABSZ Global symbol table (entries) 200 400 4000 TOKENSPACESZ Token list space (tokens). Used 200 1000 10000 to store subroutine arguments and other temporary lists. 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, the identifier string space, local and global symbol tables, hashtable, and space for scratch tokens (used to hold common block declarations and subprogram argument lists during local processing) are allocated as fixed-size arrays at compile time. Other items, including permanent common block variable lists and subprogram argument lists, miscellaneous string space (e.g. for character constants), and other odds and ends, are dynamically allocated using malloc and calloc. This scheme is well suited to machines with large address spaces and virtual memory. The sizes of the fixed tables 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 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 all the different table sizes 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. I find that it fails after allocating about 55K worth. The biggest demand for calloc space comes from the permanent common and argument lists. In this scheme the needed space is supplied from fixed-size tables, one each for argument list headers, argument list elements, common block list headers, and common block list elements. Each table is in a separately compiled module so that each can occupy up to 64K bytes. Therefore, it is necessary to link the additional four routines newarge.c, newargh.c, newcome.c, newcomh.c with the other object modules. (The makefile does all this.) There is an additional option, CALLOC_FALLBACK, that causes calloc to be used if these tables become exhausted. This option is not the default because the program usually hangs when calloc fails. It should only be used if you have to process a very large program that will not fit otherwise. You should not define DYNAMIC_TABLES at the same time as T_ALLOC.