path: root/unix/portkit/README

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.