Initial commit

1 files changed, 356 insertions, 0 deletions

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 "<setjmp.h>".
+
+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 <mach.h> 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 <stdio.h> 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.