UNIX/IRAF (Berkeley UNIX) Porting Notes 18 January 1986 (dct), 28 March 1988 (sr) ----------------------------------------- The 4.3BSD VAX version of UNIX/IRAF will run almost without change on other BSD-based systems. In particular, the kernel should not have to be changed. The changes which are required are due to machine differences, e.g., in the assemblers and machine constants. The affected files are summarized below. Source for much of the existing IRAF system documentation is in the directory iraf/doc, with notes on previous ports in iraf/doc/ports. Other documentation is generally in "doc" subdirectories throughout the system. It is useful to be familiar with Doug Tody's paper "The IRAF Data Reduction and Analysis System" (IRAF System Handbook, Vol. 3A), as it is with "A Reference Manual for the IRAF System Interface" (Vol. 3B). You will want to read and refer to the UNIX/IRAF Installation and Maintenance Guide as well. Please keep a detailed notes file in $iraf/local on any files edited for the port, similar to the ones in "$iraf/doc/ports". Virtually all the work on the port (excluding any new device interfaces) should be in the Host System Interface (HSI) directories, which in this case are rooted at "iraf/unix". A source tape may also contain other HSI's, such as "iraf/vms". Summary of Steps Required for a BSD-derived UNIX Port o create the `iraf' account and root directory o read the source distribution tape (UNIX "tar" format) o edit system-dependent files in the HSI o bootstrap the HSI utilities o test the bootstrap utilities o perform a full IRAF sysgen o configure the device tables and complete the installation o test and benchmark the system Edit the Files that Describe the Host System ------------------------------------------------------------------------------ The Host System Interface comprises all the subdirectories of "$iraf/unix", but in general for a new port only a handful of files need be modified; the most likely of these are listed here. unix/as/*.s All of the assembler sources are of course different for a VAX and other machines. The various UNIX assemblers for the MC68000 UNIX implementations are also different, e.g., in the comment convention, use of $ or # to denote a numeric constant, etc. Despite the differences there are many similarities, and the translation is usually not difficult. Note that only a couple of assembler sources are required, although half a dozen or so should eventually be implemented for efficiency reasons. To modify the AS directory for a non-VAX, rename the original AS directory to "vaxas", create a new "as" directory, and code at least ZSVJMP.S (see below) for your machine. Other assembler routines in "vaxas" may be coded later for enhanced efficiency. unix/as/zsvjmp.s The "zsvjmp.s" distributed in the source tape is for VAX/UNIX. This is the only assembler routine required for running IRAF; it executes a non-local goto in the context of the "calling routine" (this is why we cannot simply use the UNIX "setjmp / longjmp" calls directly). See also LEN_JMPBUF in config.h and spp.h. In the VAX "zsvjmp.s" the location of the "mem" common block is fixed at virtual address zero. This is desirable, but not essential. However, it is essential that it be at least aligned to an even 64-bit boundary in memory, due to requirements of the SPP language. Note that as long as the library function "setjmp(3)" is implemented, all "zsvjmp.s" has to do is manipulate a few words, and jump to "setjmp" without putting anything on the stack. pkg/cl/main.c pkg/cl/pfiles.c In a recent port to a machine requiring 64-bit alignment of double precision words in memory (HP-9000 Series 800), we had to modify some code in these two files. The symptom showed up after the CL was running, when giving the command "lpar urand" after loading the "utilities" package; a fatal bus error ensued. We have not checked the fix out thoroughly yet, so it is not merged into the master system. If you run into a situation like this, please contact me for the modification. unix/boot/mkpkg/scanlib.c This file contains code that opens and reads IRAF object libraries in order to compare the insertion dates against source file dates. Not all UNIX systems store the date or module names the same way, so if you later find that MKPKG is always recompiling all modules, you will need to modify this file. unix/boot/spp/xc.c This is the IRAF XC compiler. Among other things, it preprocesses SPP code into Fortran and executes the host system compilers and linker. Examine the occurrences of "f77" and "cc", and make sure the right libraries are in FORTLIB[123]. It is assumed that "f77" can compile C code and "cc" can run the loader in the current version, requiring minor code additions if not. unix/boot/spp/rpp/ratlibc/ratdef.h If your compilers do anything with Fortran external identifiers other than appending an underscore to them, including leaving them intact, edit this file. unix/boot/spp/rpp/ratlibc/ratdef.h If your Fortran compiler does anything with external identifiers other than appending a trailing underscore (including doing nothing with them at all), edit this file. In it, the names of Fortran routines that may be called from C are given with the trailing underscore. unix/boot/spp/xpp/xppcode.c See the comments about type coercion for INT2 and INT4, and edit if necessary. unix/gdev/* No changes should be required, unless new graphics devices have to be interfaced. unix/hlib/config.h This file should be inspected for machine dependencies; e.g., LEN_JUMPBUF may need modification; note that it should be 1 greater than what is allocated for "jmp_buf" in "". unix/hlib/iraf.h Do not confuse this file with the "iraf.h" in hlib/libc (which is for inclusion in C programs). There are several things to check in this file, e.g. the value of the "indefinites" INDEFR, etc. In particular, be sure to map the Fortran intrinsics "and, or, xor," and "not" if your Fortran compiler uses different names for them. Also, if Fortran external identifiers are not distinguished from their C counterparts automatically by the compilers, there may be some name collisions between SPP and C routines, which would show up as runtime errors. (E.g. if "blogs" were both an SPP routine and a UNIX routine, rename "blogs" to "xblogs" or something in iraf.h [and libc/xnames.h]. In a recent port we redefined "getpid" as "xgetpd", "rename" as "xfrnam", and "getuid" as "xgetud".) unix/hlib/irafuser.csh Edit the three compile/link flags (HSI_**) for the Host System Interface routines -- there is little or no floating point used in the HSI. Also edit the pathname to the IRAF root directory if yours is different. unix/hlib/mach.h (see portkit/mach.h.ieee) unix/hlib/[dir]1mach.f (see portkit/[dir]1mach.f.ieee) Change the machine constants to those for your hardware. If the machine has IEEE floating point, these constants are independent of the host operating system (e.g., SUN or ISI). The directory "unix/portkit" contains several files ending in ".ieee" as examples. These files should not be used to simply replace those in the distributed source tape, as they may not be up to date; a diff/merge is recommended, or just use them for reference in editing the distributed versions. In only the machine epsilon and byte-swap flags usually need to be changed; the values for INDEF, MAX_LONG, etc. are the same for most modern minicomputers. The utility $iraf/sys/osb$zzeps.f may be used to determine the machine epsilon. The values determined for a SUN/MC68020 with software floating point were the following: EPSILONR (1.192e-7) EPSILOND (2.220d-16) BYTE_SWAP = NO means the most significant byte of a word comes first in a stream of bytes, as in the MC68*** machines (this is called "big-endian"). VAXes have swapped bytes. Note the examples in $iraf/unix/portkit/*.IEEE. unix/hlib/mkiraf.csh Change the IRAF root pathnames in these files. unix/hlib/libc/iraf.h /usr/include/iraf.h -> $iraf/unix/hlib/libc/iraf.h Replace ALL existing occurrences of the IRAF root pathname with your own pathname to the IRAF root directory. This would normally be done by the "install" script, but you may not wish to install IRAF solely for purposes of the port. Also edit the value of TMP to be the location of a publicly writeable scratch directory. If symbolic links are available, simply establish one in "/usr/include" pointing to "iraf.h" (you probably have to be superuser to do this). If not, copy "iraf.h" to "/usr/include", and remember to do so again after any subsequent edits. unix/hlib/libc/kernel.h The only parameter which might need to be modified is _NFILE, which should reflect the host sytem's open file capacity (this will be defined in in many BSD derived systems). unix/hlib/libc/knames.h If your compilers do anything with Fortran external identifiers other than appending an underscore to them, including leaving them intact, edit this file. unix/hlib/libc/libc.h "libc.h" contains some definitions for external names of certain Fortran identifiers such as common blocks -- in a few places, C code needs access to these locations (see paragraph labelled "[MACHDEP]"). On the VAX, all f77 external identifiers are given a trailing underscore. unix/hlib/libc/spp.h (see portkit/spp.h.ieee) Enter the EPSILON[RD]'s determined earlier for hlib/mach.h and the INDEF's. Also, make sure LEN_JUMPBUF matches the one in "hlib/config.h". In general, look for the string "MACHDEP" in these files. unix/hlib/libc/xnames.h See comments under "unix/hlib/iraf.h" concerning name collisions. unix/os/zxwhen.c This file contains machine-specific hardware exception codes. This ends the list of likely source files to be edited. Later, when installing a new version of UNIX/IRAF it is usually best to install the new UNIX directories as well, and then modify or replace the above files as necessary for your machine. All revisions are thus automatically picked up, and the modifications required for your machine are probably relatively minor. Bootstrap the HSI Utilities ------------------------------------------------------------------------ This may take a while (10's of minutes), so it is advisable to spool the output. % cd $iraf/unix % sh -x mkpkg.sh >& spool & Examine the spool file for any compilation errors and attempt to deduce and correct any that are encountered. Test the Bootstrap Utilities -------------------------------------------------------------------------------- When the bootstrap has completed successfully, it is time to test the bootstrap utilities. The most important of these are XC and MKPKG. For purposes of a port, you may establish symbolic links to the bootstrap utilities and later runtime executables within the IRAF directory system, rather than in a public directory. This should be "$iraf/local/bin". Edit the ".login" file of the "iraf" account to include "$iraf/local/bin" in its search path, and establish the links as follows: % cd $iraf/local % mkdir bin % cd $iraf/local/bin % ln -s $iraf/bin/cl.e cl % ln -s $iraf/unix/hlib/generic.e generic % ln -s $iraf/unix/hlib/mkiraf.csh mkiraf % ln -s $iraf/unix/hlib/mkmlist.csh mkmlist % ln -s $iraf/unix/hlib/mkpkg.e mkpkg % ln -s $iraf/unix/hlib/rmbin.e rmbin % ln -s $iraf/unix/hlib/rmfiles.e rmfiles % ln -s $iraf/unix/hlib/rtar.e rtar % ln -s $iraf/unix/hlib/sgidispatch.e sgidispatch % ln -s $iraf/unix/hlib/wtar.e wtar % ln -s $iraf/unix/hlib/xc.e xc" unix/hlib/mkpkg.inc Edit "mkpkg.inc" to establish compiler and linker switches for SPP programs. unix/hlib/mkpkg.sf The special file list "mkpkg.sf" will be involved later, if compiler bugs during a sysgen require special compilation (e.g. without optimization). In a recent port to a vector machine, separate MKPKG flags were created for several classes of routines, those benefitting from vectorization, those calling lower-level C routines, etc. Contact us if you feel your Fortran compiler may have similar needs (if so, a number of "mkpkg" files in various directories will also need to be edited). Perform an IRAF Sysgen -------------------------------------------------------------------------------- If the bootstrap utilities appear to be in good shape, it is time to perform a full IRAF sysgen. This will preprocess all the SPP code in IRAF into Fortran, compile and delete the intermediate Fortran source, load all the object libraries, and link the executables. There are invariably problems with the Fortran compiler. There will probably be some compile time compiler failures, maybe some linker failures, and probably some run time IRAF bugs that end up being due to compiler bugs, usually in the optimizer. IRAF is a large system, and we haven't gotten through an installation yet on any host where this was not the case (although in a couple of recent ports only a few files were affected). You will definitely want to spool the output; even on fast machines a full sysgen may take over 5 hours. % cd $iraf % mkpkg >& spool & You will certainly have to perform the sysgen multiple times, as you identify and correct problems. Files successfully compiled and loaded into object libraries will not be compiled in succeeding sysgens, so each one takes less time than its predecessor. Be sure to inspect the spoolfile during or after your second sysgen to make sure this is the case. If all files are being automatically recompiled, there is something wrong with the routine that compares file dates in the object libraries with source file dates. Library module dates are determined in iraf$unix/boot/mkpkg/scanlib.c, module h_scanlibrary. Note that the bootstrap utility RMBIN may be used to remove binary files should this be desired during multiple cycles of sysgens. The hardest part starts when you begin debugging problems with the run-time system; it helps to know IRAF well enough to know how something is supposed to work. This could well be the most labor-intensive part of the port. Note that the file "$iraf/unix/hlib/mkpkg.sf" is used for handling files requiring special compilation. Test and Benchmark the System -------------------------------------------------------------------------------- If all the preceding steps are complete, you are ready to begin testing the system. A normal user would run "mkiraf" from their desired IRAF home directory ("$iraf/local" for the IRAF account itself) to tailor the runtime environment. Since you are doing a port instead, you may want to simply edit the startup file ("$iraf/local/login.cl") for the two environment variables "home" and "imdir". Most users locate their bulk image storage directory on a temp disk to simplify disk backups, but to keep the port compact, you could instead create a pixel storage directory under "$iraf/local". Edit "$iraf/local/login.cl"; replace the home directory below with your own: set home = "/iraf/local/" set imdir = "home$pix/" The test procedures assume a complete installation, so even though you don't know if the port is successful yet, you might as well configure the device tables and complete the installation as in the "UNIX/IRAF Installation and Maintenance Guide", section 2.3 (at least install the magtape devices in "dev$devices" as in section 2.3.2). Since we cannot guarantee that a binary image file from a VAX/UNIX system will be readable by an arbitrary host system, we will have you delete the old binary image (currently implemented as three files), then unpack a machine-independent image file to replace it. Contact us if the file "fitspix" is not present in the $iraf/dev directory. % cd $iraf/local % cl [IRAF banner, message of the day, top-level packages.] cl> cd dev cl> delete pix.imh,..pix.imh,pix.pix # if present cl> set imdir = HDR$ cl> dataio da> rfits fitspix 1 pix da> bye cl> cd local cl> mkdir pix cl> reset imdir = "home$pix/" You may now undertake the Test Procedures in Volume 1A of the IRAF User Handbook. Benchmark the System -------------------------------------------------------------------------------- When the system is running reasonably well and is bug-free, you can accomplish further testing by running the Benchmark Utilities. See the paper entitled "A Set of Benchmarks for Measuring IRAF System Performance", in the IRAF System Handbook, Volume 3A.