From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001 From: Joe Hunkeler Date: Tue, 11 Aug 2015 16:51:37 -0400 Subject: Repatch (from linux) of OSX IRAF --- unix/portkit/README | 356 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 356 insertions(+) create mode 100644 unix/portkit/README (limited to 'unix/portkit/README') diff --git a/unix/portkit/README b/unix/portkit/README new file mode 100644 index 00000000..17177d88 --- /dev/null +++ b/unix/portkit/README @@ -0,0 +1,356 @@ +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. -- cgit