Installation Instructions for Portability-related Modules Prepared by C.Ludescher transp_support@pppl.gov 10/14/99 Index: 1. UNPACKING INSTRUCTIONS 2. CONTENTS and DESTINATIONS 3. BUILDING INSTRUCTIONS 4. TESTING 5. RUNNING INSTRUCTIONS 6. FINAL INSTALLATION ************************** 1. UNPACKING INSTRUCTIONS: ************************** for tarfile: > gunzip ftoken.tar.gz > tar xvf ftoken.tar for zip archive: > unzip ftoken.zip ***************************** 2. CONTENTS and DESTINATIONS: ***************************** Or where do the files go? (this refers to building; see FINAL INSTALLATION for end result) When you extract the tar file you get: README -- Brief descriptions of the other files. INSTALL -- This file. Instructions for building. Makefile -- NOTE, "GNU make" must be used (usually in /usr/gnu/bin or /usr/local/bin). Makefile to invoke Makefiles in all subdirectories. Subdirectories: ./cpcheck -- Sources, etc. for cpcheck ./fgtok -- Sources, etc. for fgtok ./idecl -- Sources, etc. for idecl ./r8real -- Sources, etc. for r8real ./share -- Include file for makefiles ./fpreproc -- Scripts for preprocessing ./include/fpreproc -- Include files for programs ./ftoken -- Copy of README and INSTALL sources for internally used library ./portlib -- Sources for internally used library ./test -- Samples for testing The makefile will create the following sub directories, bin: for the programs lib: for the internally used libraries obj: for preprocessed sources and objects By default these directories are created in ./, which is determined by Make.flags. e.g.: if you are running Linux, and the tar file resides in $HOME/foo, the directories would be $HOME/foo/bin $HOME/foo/LINUX/lib etc. You can overwrite the destination by defining OBJ, as an environment variable (e.g. in your login setup, export OBJ=/dir1/dir2), or with make (e.g. "make OBJ=."). If OBJ is defined, the destinations will be $OBJ/bin, etc. If OBJ is defined as "." then in the example above, the destination would be $HOME/foo/bin. The rationale behind is to facilitate building for various platforms. ************************* 3. BUILDING INSTRUCTIONS: ************************* NOTE, "GNU make" must be used (usually in /usr/gnu/bin or /usr/local/bin). You also need gcc for pre-processing (exept on CRAY). > gmake -- to compile/link all programs > gmake checklibs -- tells you what the makefile will do (without any action); it sais which libraries it will make and which ones it already found and where. It also tells you how to rebuild an existing library. > gmake clean -- to remove all objects > gmake realclean -- to remove everything but sources. Compiling on Linux: ------------------- At present, there is no native Linux fortran 90 compiler. However, many vendors offer good quality compilers. The following have been successfully used: -Fujitsu f95 -PGI pgf77 / pgf90 By default the Makefile will select Fujitsu f95. To select a different compiler define FORTRAN_VARIANT to "Portland" "NagWare" "Fujitsu" or "Absoft" e.g.: setenv FORTRAN_VARIANT Portland (csh) FORTRAN_VARIANT=Portland; export FORTRAN_VARIANT (sh) Alternatively, FORTRAN_VARIANT can be passed directly to the gmake command, as in: gmake FORTRAN_VARIANT=Portland To use vastf90: > gmake VAST90=y Caveat: Be careful to use the same compiler for all objects. *********** 4. TESTING: *********** The installation includes in directory /bin: (Note: the Makefile did copy the files from ./test) fgtok_test.csh -- test driver script bcspeval.f -- sample REAL fortran source r8_names.table -- REAL to REAL*8 conversion table bcspeval.f_ref -- reference for REAL*8 version of bcspeval.f bcspeval.r8i_ref -- reference for REAL*8 interface bcspeval.f fgtok_test.csh runs (1) r8con.csh -- to make REAL*8 version of REAL routine bcspeval.f runs fgtok, idecl and cpcheck (2) r8igen.csh -- to make REAL*8 interface to REAL routine bcspeval.f runs r8real (3) compares results to reference files. To run the test: ---------------- > cd /bin where is the directory where you downloaded the tar file. > fgtok_test.csh ************************ 5. RUNNING INSTRUCTIONS: ************************ Unless you installed the programs, and have /bin and /etc in your PATH: type > cd /bin where is the directory where you downloaded the tar file. It is highly recommanded that you install the package. You can install it in PREFIX=$HOME. Then you only need $HOME/bin and $HOME/etc in your PATH and the scripts should find everything. fgtok: ====== Define environment variable S_TABLE_DIR to point to the *.sub files ../../fgtok : if you are just building /etc/ftoken : if program is installed Define environment variable CPP_HFILE_DIR to point to the *.h files ../../include : if you are just building /include/fpreproc : if program is installed Use driver scripts ------------------- The driver scripts provide a convenient way of using the programs and should handle most user's needs. Note: Since the scripts are executing the programs fgtok, idecl, cpcheck and r8real, these programs must be in your PATH, or you must define PREFIX. r8_convert input.f output.f [s-file(s)...] [CONST] [TEX] to conver source code r8_convert_include input.inc output.inc [s-file(s)...] [CONST] [TEX] to convert include files r8con.csh input.f output.f user_subs.table to make a program portable. intcon.csh input.f output.f to clean up a source code, with respect to INTEGER declarations. fgtok_list.csh to output, in uppercase, global names found in the sources. Substitution tables: -------------------- r8_precision.sub : map all real & complex types to real*8 and complex*16 r8_icomplex.sub : map all real & complex intrinsics to standard names r8_intrinsic.sub : convert to generic intrinsic functions int_precision.sub : to clean up INTEGER and LOGICAL declarations cpp #include files: ------------------- fpreproc/f77_dcomplx.h : to substitute intrinsic functions fpreproc/byte_declare.h : BYTE/INTEGER*1 To run program: fgtok input.f [] or fgtok input.f output.f [switches] To convert code to use as standard names AREAL, AIMAG and CMPLX fgtok input.f output.f \ -p PATH -s r8_icomplex.sub -incl_cpp f77_dcomplx.h cpcheck: ======== cpcheck [source-filename] [-p path [paths...]] -incl_cpp header-file[s] idecl: ====== Define environment variable EXCLUDE_SYMBOLS ../../idecl : if you are just building /etc/ftoken : if program is installed Default exclude-symbols-file: ----------------------------- f77_exclude.list -- file containing language reserved symbols To generate declarations of undeclared symbols in a fixed code: idecl input.f output.f r8real: ======= To run program: r8real input.f output.f90 > output.sub To run driver script: r8igen.csh output.f90 output.sub "output.sub" may be used as input to fgtok. ========================================================== See http://w3.pppl.gov/~pshare/help/port_strategy.htm As a minimum read section "Quick Start Guide" ========================================================== ********************** 6. FINAL INSTALLATION: ********************** Choose or create the root directory in which you wish to install the software. A common location would be /usr/ntcc, but installation can occur in any directory where you have appropriate permissions. You define your choice of root directory via PREFIX. There is "no default" for PREFIX. The assumptions are: executables in: $PREFIX/bin = $BINDIR scripts in: $PREFIX/etc = $ETCDIR input tables in: $PREFIX/etc/ftoken = $ETCDIR/ftoken *.h files in: $PREFIX/include/fpreproc = $INCLDIR/fpreproc man pages in: $PREFIX/man/man1 = $MANDIR/man1 To install the software, return to the top directory (the directory, where you downloaded the tar files) and type > gmake install PREFIX=/dir1/dir2/ to install into /dir1/dir2/... If you want things elsewhere, you can overwrite the default with > gmake install BINDIR=/xxx ETCDIR=/yyy MANDIR=/zzz INCLDIR=/aaa After you have installed the software, you can delete the entire tree with > cd .. > rm -r foo assuming the previous example.