Initial commit

1 files changed, 1606 insertions, 0 deletions

diff --git a/doc/sunsmg.ms b/doc/sunsmg.ms
new file mode 100644
index 00000000..13d0a119
--- /dev/null
+++ b/doc/sunsmg.ms
@@ -0,0 +1,1606 @@
+.RP
+.de XS
+.DS
+.ps -1
+.vs -2p
+.ft CB
+..
+.de XE
+.DE
+.ft R
+.ps
+.vs
+..
+.TL
+Sun/IRAF Site Manager's Guide
+.AU
+Doug Tody
+.AI
+IRAF Group
+.br
+.K2 "" "" "\(dg"
+.br
+June 1989
+.br
+Revised July 1992
+
+.AB
+An IRAF \fIsite manager\fR is anyone who is responsible for installing and
+maintaining IRAF at a site.  This document describes a variety of site
+management activities, including configuring the device and environment
+tables to provide reasonable defaults for the local site, adding interfaces
+for new devices, configuring and using IRAF networking, the installation
+and maintenance of layered software products (external packages),
+and configuring a custom site LOCAL package so that local software may be
+added to the system.  Background information on multiple architecture
+support, shared library support, and the software management tools provided
+with the system is presented.  The procedures for rebooting IRAF and
+performing a sysgen are described.  An introduction to graphics and image
+display on the Sun workstation is provided.  The host system resources
+required to run IRAF are discussed.
+.AE
+
+.pn 1
+.bp
+.ce
+.ps +2
+\fBContents\fR
+.ps -2
+.sp 3
+.sp
+1.\h'|0.4i'\fBIntroduction\fP\l'|5.6i.'\0\01
+.sp
+2.\h'|0.4i'\fBSystem Setup\fP\l'|5.6i.'\0\02
+.br
+\h'|0.4i'2.1.\h'|0.9i'Installing the System\l'|5.6i.'\0\02
+.br
+\h'|0.4i'2.2.\h'|0.9i'Configuring the Device and Environment Tables\l'|5.6i.'\0\02
+.br
+\h'|0.9i'2.2.1.\h'|1.5i'Environment definitions\l'|5.6i.'\0\02
+.br
+\h'|0.9i'2.2.2.\h'|1.5i'The template LOGIN.CL\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.2.3.\h'|1.5i'The TAPECAP file\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.2.4.\h'|1.5i'The DEVICES.HLP file\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.2.5.\h'|1.5i'The TERMCAP file\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.2.6.\h'|1.5i'The GRAPHCAP file\l'|5.6i.'\0\04
+.br
+\h'|0.9i'2.2.7.\h'|1.5i'Configuring IRAF networking\l'|5.6i.'\0\04
+.br
+\h'|0.9i'2.2.8.\h'|1.5i'Configuring the IRAF account\l'|5.6i.'\0\06
+.br
+\h'|0.9i'2.2.9.\h'|1.5i'Configuring user accounts for IRAF\l'|5.6i.'\0\06
+.br
+\h'|0.4i'2.3.\h'|0.9i'Tuning Considerations\l'|5.6i.'\0\06
+.br
+\h'|0.9i'2.3.2.\h'|1.5i'Stripping the system to reduce disk usage\l'|5.6i.'\0\06
+.sp
+3.\h'|0.4i'\fBSoftware Management\fP\l'|5.6i.'\0\07
+.br
+\h'|0.4i'3.1.\h'|0.9i'Multiple architecture support\l'|5.6i.'\0\07
+.br
+\h'|0.4i'3.2.\h'|0.9i'Shared libraries\l'|5.6i.'\0\08
+.br
+\h'|0.4i'3.3.\h'|0.9i'Layered software support\l'|5.6i.'\0\09
+.br
+\h'|0.4i'3.4.\h'|0.9i'Software management tools\l'|5.6i.'\0\09
+.br
+\h'|0.4i'3.5.\h'|0.9i'Modifying and updating a package\l'|5.6i.'\0\10
+.br
+\h'|0.4i'3.6.\h'|0.9i'Installing and maintaining layered software\l'|5.6i.'\0\12
+.br
+\h'|0.4i'3.7.\h'|0.9i'Configuring a custom LOCAL package\l'|5.6i.'\0\13
+.br
+\h'|0.4i'3.8.\h'|0.9i'Updating the full IRAF system\l'|5.6i.'\0\13
+.br
+\h'|0.9i'3.8.1.\h'|1.5i'The BOOTSTRAP\l'|5.6i.'\0\13
+.br
+\h'|0.9i'3.8.2.\h'|1.5i'The SYSGEN\l'|5.6i.'\0\14
+.br
+\h'|0.9i'3.8.3.\h'|1.5i'Localized software changes\l'|5.6i.'\0\15
+.sp
+4.\h'|0.4i'\fBGraphics and Image Display under SunView\fP\l'|5.6i.'\0\16
+.br
+\h'|0.4i'4.1.\h'|0.9i'The SunView environment\l'|5.6i.'\0\16
+.br
+\h'|0.4i'4.2.\h'|0.9i'Vector graphics capabilities\l'|5.6i.'\0\17
+.br
+\h'|0.4i'4.3.\h'|0.9i'Image Display capabilities\l'|5.6i.'\0\17
+.br
+\h'|0.4i'4.4.\h'|0.9i'Using the workstation with a remote compute server\l'|5.6i.'\0\18
+.sp
+5.\h'|0.4i'\fBInterfacing New Graphics Devices\fP\l'|5.6i.'\0\19
+.br
+\h'|0.4i'5.1.\h'|0.9i'Graphics terminals\l'|5.6i.'\0\19
+.br
+\h'|0.4i'5.2.\h'|0.9i'Graphics plotters\l'|5.6i.'\0\19
+.br
+\h'|0.4i'5.3.\h'|0.9i'Image display devices\l'|5.6i.'\0\20
+.sp
+6.\h'|0.4i'\fBHost System Requirements\fP\l'|5.6i.'\0\20
+.br
+\h'|0.4i'6.1.\h'|0.9i'Memory requirements\l'|5.6i.'\0\20
+.br
+\h'|0.4i'6.2.\h'|0.9i'Disk requirements\l'|5.6i.'\0\20
+.br
+\h'|0.4i'6.3.\h'|0.9i'Diskless nodes\l'|5.6i.'\0\20
+.sp
+\fBAppendix A.\0The IRAF Directory Structure\fP\l'|5.6i.'\0\21
+.nr PN 0
+.bp
+
+.NH
+Introduction
+.PP
+Once the IRAF system has been installed it will run, but there remain many
+things one might want to do to tailor the system to the local site.
+Examples of the kinds of customizations one might want to make are the
+following.
+.RS
+.IP \(bu
+Edit the default IRAF environment definitions to provide reasonable
+defaults for your site.
+.IP \(bu
+Make entries in the device descriptor tables for the devices in use at
+your site.
+.IP \(bu
+Code and install new device interfaces.
+.IP \(bu
+Enable and configure IRAF networking, e.g., to permit remote image
+display, tape drive, or file access.
+.IP \(bu
+Perform various optimizations, e.g., stripping the system to reduce disk
+usage.
+.IP \(bu
+Extend the system by installing layered software products.
+.IP \(bu
+Configure a custom LOCAL package so that locally developed software
+may be installed in the system.
+.RE
+.PP
+This document provides sufficient background information and instructions to
+guide the IRAF site manager in performing such customizations.  Additional
+help is available via the IRAF HOTLINE (602 323-4160), or by sending mail to
+\f(CWiraf@noao.edu\fR (internet) or \f(CW5355::iraf\fP (SPAN).
+Contributions of interfaces developed for new devices, or any other software
+of general interest, are always welcome.
+.PP
+The IRAF software is organized in a way which attempts to isolate, so far as
+possible, the files or directories which must be modified to tailor the
+system for the local site.  Most or all changes should affect only files in
+the local, dev, and hlib (unix/hlib) directories.  Layered software
+products, including locally added software, reside outside of the IRAF core
+system directory tree and are maintained independently of the core system.
+.PP
+A summary of all modifications made to the IRAF system for a given IRAF
+release is given in the \fIRevisions Summary\fR distributed with the
+system.  Additional information will be found in the system notes files
+(notes.v29, notes.v210, etc.) in the iraf/local and iraf/doc directories.
+This is the primary source of technical documentation for each release and
+should be consulted if questions arise regarding any of the system level
+features added in a new release of the core system.
+
+.bp
+.NH
+System Setup
+.NH 2
+Installing the System
+.PP
+The procedure for installing or updating Sun/IRAF is documented in the
+\fISun/IRAF Installation Guide\fR.  In short, an IRAF tape or network
+distribution is obtained and installed according to the instructions.
+The result is a full IRAF system, including both sources and executable
+binaries for the architectures to be supported.  The system will
+have been modified to reflect the new IRAF root directory and should run,
+but will otherwise be a generic IRAF distribution.  To get the most out
+of an IRAF installation it will be necessary to perform some of the
+additional steps outlined in the remainder of this document.
+
+.NH 2
+Configuring the Device and Environment Tables
+.PP
+Teaching IRAF about the devices, network nodes, external programs,
+and other special resources available at a site is largely a matter of
+editing a standard set of device descriptor and environment setup files,
+all of which are simple text files.
+The versions of these files provided with the distribution are simply
+those in use on the NOAO system from which the tapes were made,
+at the time the tapes were generated.
+Hence while these files may be useful as examples of properly
+configured descriptor files, the defaults, and many specific device entries,
+will in many cases be meaningless for a different site.  This is harmless
+but it may be confusing to the user if, for example, the default printer
+doesn't exist at your site.
+.PP
+The device and environment files also contain much material which any site
+will need, however, so care must be taken when editing the files.  Important
+changes may be made to the global portions of these files as part of any
+IRAF release.  To facilitate future updates, it is wise where possible to
+isolate any local changes or additions so that they may be copied into the
+new (distributed) version of the file in a future update.
+.NH 3
+Environment definitions
+.PP
+Since IRAF is a machine and operating system independent, distributed system
+it has its own environment facility apart from that of the host system.
+Host system environment variables may be accessed as if they are part of the
+IRAF environment (which is sometimes useful but which can also be
+dangerous), but if the same variable is defined in the IRAF environment it
+is the IRAF variable which will be used.  The IRAF environment definitions,
+as defined at CL startup time, are defined in a number of files in the
+unix/hlib directory.  Chief among these is the \fBzzsetenv.def\fR file.
+Additional user modifiable definitions may be given in the template
+\fBlogin.cl\fR file (see \(sc2.2.2).
+.PP
+The zzsetenv.def file contains a number of environment definitions.
+Many of these define IRAF logical directories and should be left alone.
+Only those definitions in the header area of the file should need to be
+edited to customize the file for a site.  It is the default editor,
+default device, etc. definitions in this file which are most likely to
+require modification for a site.
+.PP
+If the name of a default device is modified, the named device must also have
+an entry in the \fBtermcap\fR file (terminals and printers) or the
+\fBgraphcap\fR file (graphics terminals and image displays) in iraf/dev.
+There must also be an \fIeditor\f(CW.ed\fR file in dev for the
+default editor; \fIedt\fR, \fIemacs\fR, and \fIvi\fR are examples of
+currently supported editors.
+.PP
+Sample values of those variables most likely to require modification for
+a site are shown below.
+.XS
+set editor      = "vi"
+set printer     = "lpr"
+set stdplot     = "lpr"
+set stdimage    = "imt512"
+.XE
+.PP
+For example, you may wish to change the default editor to "emacs", the
+default printer to "lw5", or the default image display to "imt800".  Note
+that the values of terminal and stdgraph, which also appear in the
+zzsetenv.def file, have little meaning except for debugging processes run
+standalone, as the values of the environment variables are reset
+automatically by \fIstty\fR at login time.  The issues of interfacing new
+graphics and image display devices are discussed further in \(sc5.
+.NH 3
+The template LOGIN.CL
+.PP
+The template login.cl file hlib$login.cl, is the file used by \fImkiraf\fR
+to produce the user login.cl file.  The user login.cl file, after having
+possibly been edited by the user, is read by the CL every time a new CL is
+started, with the CL processing all environment and task definitions,
+package loads, etc., in the login file.  Hence this file plays an important
+role in establishing the IRAF environment seen by the user.
+.PP
+Examples of things one might want to change in the template login.cl
+are the commented out environment definitions, the commented out CL
+parameter assignments, the foreign task definitions making up the default
+\f(CWuser\fR package, and the list of packages to be loaded at startup
+time.  For example, if there are host tasks or local packages which
+should be part of the default IRAF operating environment at your site,
+the template login.cl is the place to make the necessary changes.
+.NH 3
+The TAPECAP file
+.PP
+Beginning with V2.10 IRAF magtape devices are described by the tapecap file,
+dev$tapecap.  This replaces the "devices" file used in earlier versions of
+IRAF.  The tapecap file describes each local magtape device and controls all
+i/o to the device, as well as device allocation.
+.PP
+The tapecap file included in the distributed system includes some generic
+device entries such as "mtxb1" (Exabyte unit 1, Sun ST driver), "mthp2"
+(HP7880 9 track drive, unit 2), and so on which you may be able to use as-is
+to access your local magtape devices.  Most likely you will want to add some
+device aliases, and you may need to prepare custom device entries for local
+devices.  There must be an entry in the tapecap file for a magtape device in
+order to be able to access the device from within IRAF.
+.PP
+Instructions for adding devices to the tapecap file are given in the
+document \fIIRAF Version 2.10 Revisions Summary\fR, in the discussion of
+the new magtape system.
+.NH 3
+The DEVICES.HLP file
+.PP
+All physical devices that the user might need to access by name should be
+documented in the file dev$devices.hlp.  Typing
+.XS
+cl> help devices
+.XE
+or just
+.XS
+cl> devices
+.XE
+in the CL will format and output the contents of this file.  It is the IRAF
+name of the device, as given in files such as termcap, graphcap, and
+tapecap, which should appear in this help file.
+.NH 3
+The TERMCAP file
+.PP
+There must be entries in this file for all local terminal and printer
+devices you wish to access from IRAF (there is currently no "printcap" file
+in IRAF).  The entry for a printer contains one special device-specific
+entry, called \f(CWDD\fR.  This consists of three fields: the device name,
+e.g. "node!device", the template for the temporary spoolfile, and the UNIX
+command to be used to dispose of the file to the printer.  On most UNIX
+systems it is not necessary to make use of the node name and IRAF networking
+to access a remote device since UNIX \fIlpr\fR already provides this
+capability, however it might still be useful if the desired device does not
+have a local \fIlpr\fR entry for some reason.
+.PP
+If you have a local terminal which has no entry in the IRAF termcap file,
+you probably already have an entry in the UNIX termcap file.  Simply copy it
+into the IRAF file; both systems use the same termcap database format and
+terminal device capabilities.  However, if the terminal in question is a
+graphics terminal with a device entry in the graphcap file, you should
+add a `\f(CW:gd\fR' capability to the termcap entry.  If the graphcap entry
+has a different name from the termcap entry, make it `\f(CW:gd=\fIgname\fR'.
+.NH 3
+The GRAPHCAP file
+.PP
+There must be entries in the graphcap file for all graphics terminals, batch
+plotters, and image displays accessed by IRAF programs.  New graphics
+terminals will need a new entry.  The IRAF file gio$doc/gio.hlp
+contains documentation describing how to prepare graphcap device entries.  A
+printed copy of this document is available from the iraf/docs directory in
+the IRAF network archive.  However, once IRAF is up you may find it easier
+to generate your own copy using \fIhelp\fR, as follows:
+.XS
+cl> help gio$doc/gio.hlp fi+ | lprint
+.XE
+which will print the document on the default IRAF printer device (use the
+"device=" hidden parameter to specify a different device).  Alternatively,
+to view the file on the terminal,
+.XS
+cl> phelp gio$doc/gio.hlp fi+
+.XE
+.PP
+The help pages for the IRAF tasks \fIshowcap\fR and \fIstty\fR should also
+be reviewed as these utilities are useful for generating new graphcap
+entries.  The i/o logging feature of \fIstty\fR is useful for determining
+exactly what characters your graphcap device entry is generating.  The
+\fIgdevices\fR task is useful for printing summary information about the
+available graphics devices.
+.PP
+Help preparing new graphcap device entries is available if needed.  We ask
+that new graphcap entries be sent back to us so that we may include them in
+the master graphcap file for all to benefit.
+.NH 3
+Configuring IRAF networking
+.PP
+The dev directory contains several files (\f(CWhosts\fR,
+\f(CWirafhosts\fR, and \f(CWuhosts\fR) used by the IRAF network interface.
+IRAF networking is used to access remote image displays, printers, magtape
+devices, files, images, etc. via the network.  Nodes do not necessarily have
+to have the same architecture, or even run the same operating system, so
+long as they can run IRAF.
+.PP
+To enable IRAF networking for a Sun/IRAF system, all that is necessary is to
+edit the "hosts" file.  Make an entry for each logical node, in the format
+.XS
+\fInodename\fR [ \fIaliases\fR ] ":" \fIirafks.e-pathname\fR
+.XE
+following the examples given in the hosts file supplied with the
+distribution (which is the NOAO/Tucson hosts file).  Note that there may be
+multiple logical entries for a single physical node.
+.PP
+The "uhosts" file is not used by UNIX/IRAF systems hence does not need to
+be modified (it used by VMS/IRAF).  The "irafhosts" file is the template
+file used to create user .irafhosts files.  It does not have to be modified,
+although you can do so if you wish to change the default parameter values
+given in the file.
+.PP
+To enable IRAF networking on a particular IRAF host, the SunOS
+\fBhostname\fR must appear as a primary name or alias somewhere in the IRAF
+hosts table.  During process startup, the IRAF VOS looks for the system name
+for the current host and automatically disables networking if this name is
+not found.  Hence IRAF networking is automatically disabled when the
+distributed system is first installed - unless you are unlucky enough to
+have installed the system on a host with the same name as one of the nodes
+in the NOAO host table.
+.PP
+Once IRAF networking is configured, the following command may be typed in
+the CL to verify that all is well:
+.XS
+cl> netstatus
+.XE
+This will print the host table and state the name of the local host.
+Read the output carefully to see if any problems are reported.
+.PP
+For IRAF networking to be of any use, it is necessary that IRAF be installed
+on at least two systems.  In that case either system can serve as the server
+for an IRAF client (IRAF program) running on the other node.  It is not
+necessary to have a separate copy of IRAF on each node, i.e., a single copy
+of IRAF may be NFS mounted on all nodes (you will need to run the IRAF
+\fIinstall\fR script on each client node).  If it is not possible to install
+IRAF on a node for some reason (either directly or using NFS) it is possible
+to manage by installing only enough of IRAF to run the IRAF kernel server.
+Contact IRAF site support if you need to configure things in this manner.
+.PP
+Sun/IRAF currently supports only TCP/IP based networking.  Networking
+between any heterogeneous collection of systems is possible provided they
+support TCP/IP based networking (virtually all UNIX-based systems do).  The
+situation with networking between UNIX and VMS systems is more complex.
+V2.9 and earlier versions of VMS/IRAF support client-side only TCP/IP using
+the third party Wollongong software.  For V2.10 we plan to drop support for
+the Wollongong software and switch to the more fully-featured Multinet
+instead (another third party product).  We have long had an experimental
+DECNET networking interface for SunOS which is based on Sun's DECNET
+implementation, however at this time it does not appear worthwhile to
+release this as a supported product.  Contact the IRAF project for further
+information on networking between UNIX and VMS systems.
+.PP
+Once IRAF networking is enabled, objects resident on the server node may be
+accessed from within IRAF merely by specifying the node name in the object
+name, with a "\fInode!\fR" prefix.  For example, if \fIfoo\fR is a network
+node,
+.XS
+cl> page foo!hlib$motd
+cl> allocate foo!mta
+cl> devstatus foo!mta
+.XE
+.PP
+In a network of "trusted hosts" the network connection will be made
+automatically, without a password prompt.  A password prompt will be
+generated if the user does not have permission to access the remote node
+with UNIX commands such as \fIrsh\fR.  Each user has a .irafhosts file in
+their UNIX login directory which can be used to exercise more control over
+how the system connect to remote hosts.  See the discussion of IRAF
+networking in the \fIIRAF Version 2.10 Revisions Summary\fR, or in the V2.10
+system notes file, for a more in-depth discussion of how IRAF networking
+works.
+.PP
+To keep track of where files are in a distributed file system, IRAF uses
+\fBnetwork pathnames\fR.  A network pathname is a name such as
+"foo!/tmp3/images/m51.pix", i.e., a host or IRAF filename with the node name
+prepended.  The network pathname allows an IRAF process running on any node
+to access an object regardless of where it is located on the network.
+.PP
+Inefficiencies can result when image pixel files are stored on disks which
+are cross-mounted using NFS.  The typical problem arises when imdir (the
+pixel file storage directory) is set to a path such as "/data/iraf/user/",
+where /data is a NFS mounted directory.  Since NFS is transparent to
+applications like IRAF, IRAF thinks that /data is a local disk and the
+network pathame for a pixel file will be something like "foo!/data/iraf"
+where "foo" is the hostname of the machine on which the file is written.  If
+the image is then accessed from a different network node the image data will
+be accessed via an IRAF networking connection to node "foo", followed by an
+NFS connection to the node on which the disk is physically mounted, causing
+the data to traverse the network twice, slowing access and unnecessarily
+loading the network.
+.LP
+A simple way to avoid this sort of problem is to include the server name
+in the imdir, e.g.,
+.XS
+cl> set imdir = "server!/data/iraf/user/"
+.XE
+This also has the advantage of avoiding NFS for pixel file access - NFS is
+fine for small files but can load the server excessively when used to access
+bulk image data.
+.PP
+Alternatively, one can set imdir to a value such as "HDR$pixels/", or
+disable IRAF networking for disk file access.  In both cases NFS will be
+used for image file access.
+.NH 3
+Configuring the IRAF account
+.PP
+The IRAF account, i.e., what one gets when one logs into SunOS as "iraf",
+is the account used by the IRAF site manager to work on the IRAF system.
+Anyone who uses this account is in effect a site manager, since they have
+permission to modify, delete, or rebuild any part of IRAF.  For these and
+other reasons (e.g., concurrency problems) it is recommended that all routine
+use of IRAF be performed from other accounts (user accounts).
+.PP
+If the system has been installed according to the instructions given in the
+installation guide the login directory for the IRAF account will be
+iraf/local.  This directory contains both a \f(CW.login\fR file
+defining the environment for the IRAF account, and a number of other "dot"
+files used to setup a sample SunView screen of the type that an IRAF user
+will want, i.e., with the IRAF graphics and image display windows.
+.PP
+Most site managers will probably want to customize these files according to
+their personal preferences.  In doing this please use caution to avoid losing
+environment definitions, etc., which are essential to the correct operation
+of IRAF, including IRAF software development.
+.PP
+The default login.cl file supplied in the IRAF login directory uses machine
+independent pathnames and should work as-is (no need to do a \fImkiraf\fR -
+in fact \fImkiraf\fR has safeguards against inadvertent use within the IRAF
+directories and may not work in iraf/local).  It may be necessary to edit
+the .login file to modify the way the environment variable
+\f(CWIRAFARCH\fR is defined.  This variable, required for software
+development but optional for merely using IRAF, must be set to the name of
+the desired machine architecture, e.g., sparc, f68881, etc.  If it is set to
+the name of an architecture for which there are no binaries, e.g., generic,
+the CL may not run, so be careful.  The alias \fIsetarch\fR, defined in the
+iraf account .login, is convenient for setting the desired architecture for
+IRAF execution and software development.
+.NH 3
+Configuring user accounts for IRAF
+.PP
+User accounts should be loosely modeled after the IRAF account.  All that is
+required for a user to run IRAF is that they run \fImkiraf\fR in their
+desired IRAF login directory before starting up the CL.  In many cases it
+may be desirable for the user, if using SunView, to copy the default SunView
+startup files from iraf/local as well (see \(sc4.1).  Defining
+\f(CWIRAFARCH\fR in the user environment is not required unless the user
+will be doing any IRAF based software development (including IMFORT).
+
+.NH 2
+Tuning Considerations
+.NH 3
+Stripping the system to reduce disk usage
+.PP
+If the system is to be installed on multiple CPUs, or if a production
+version is to be installed on a workstation, it may be necessary or
+desirable to strip the system of all non-runtime files to save disk space.
+This equates to deleting all the sources and all the reference manuals and
+other documentation, excluding the online manual pages.  A special utility
+called \fIrmfiles\fR (in the SOFTOOLS package) is provided for this
+purpose.  It is not necessary to run \fIrmfiles\fR directly to strip the
+system.  The preferred technique is to use "mkpkg strip" as in the following
+example (this may be executed from either the host system or from within
+IRAF).
+.XS
+% cd $iraf
+% mkpkg strip
+.XE
+.PP
+This will preserve all runtime files, permitting use of the standard system
+as well as user software development.  Note that only the IRAF core system
+is stripped, i.e., if you want to strip any external layered software
+products, such as the NOAO package, a \fImkpkg strip\fR must be executed
+separately for each - \fIcd\fR to the root directory of the external package
+first.  A tape backup of a system should always be made before the system is
+stripped; keep the backup indefinitely as it may be necessary to restore the
+sources in order to, e.g., install a bug fix or add-on software product.
+
+.NH
+Software Management
+.NH 2
+Multiple architecture support
+.PP
+Often the computing facilities at a site consist of a heterogeneous network
+of workstations and servers.  These machines will often have quite different
+architectures.  Considering only a single vendor like Sun, as of 1992 one
+sees the three major architectures SPARC, Motorola 68020, and Intel 80386,
+and several minor variations on these architectures, i.e., the floating
+point options for the Sun-3, namely the Motorola 68881 coprocessor, the Sun
+floating point accelerator (FPA), and software floating point (Sun is trying
+to phase some of these out but the need for multiple architecture support is
+not likely to go away).
+.PP
+Since IRAF is a large system it is undesirable to have to maintain a separate
+copy of IRAF for each machine architecture on a network.  For this reason
+IRAF provides support for multiple architectures within a single copy of IRAF.
+To be accessible by multiple network clients, this central IRAF system will
+typically be NFS mounted on each client.
+.PP
+Multiple architecture support is implemented by separating the IRAF sources
+and binaries into different directory trees.  The sources are architecture
+independent and hence sharable by machines of any architecture.  All of the
+architecture dependence is concentrated into the binaries, which are collected
+together into the so-called BIN directories, one for each architecture.
+The BIN directory contains all the object files, object libraries, executables,
+and shared library images for an architecture, supporting both IRAF execution
+and software development for that architecture.  A given system can support
+any number of BIN directories, and therefore any number of architectures.
+.PP
+In IRAF terminology, when we refer to an "architecture" what we really
+mean is a type of BIN.  The correspondence between BINs and hardware
+architectures is not necessarily one-to-one, i.e., multiple BINs can exist
+for a single compiler architecture by compiling the system with different
+compilation flags, as different versions of the software, and so on.
+Examples of some currently supported software architectures are shown below.
+.DS
+.TS
+center;
+ci ci ci
+l l l.
+Architecture	System	Description
+.sp
+f68881	Sun-3	mc68020, 68881 floating point coprocessor
+ffpa	Sun-3	mc68020, Sun floating point accelerator board
+generic	any	no binaries
+i386	386i	Intel 80386, 80387 floating point coprocessor
+pg	any	compiled with -pg option for profiling
+sparc	Sun-4	Sun SPARC (RISC) architecture, integral fpu
+.TE
+.DE
+.PP
+Most of these correspond to hardware architectures or floating point hardware
+options.  The exceptions are the generic architecture, which is what
+the distributed system is configured to by default (to avoid having any
+architecture dependent binary files mingled with the sources), and the
+"pg" architecture, which is not normally distributed to user sites,
+but is a good example of a custom software architecture used for software
+development.
+.PP
+When running IRAF on a system configured for multiple architectures,
+selection of the BIN (architecture) to be used is controlled by the UNIX
+environment variable \f(CWIRAFARCH\fR, e.g.,
+.XS
+% setenv IRAFARCH f68881
+.XE
+would cause IRAF to run using the f68881 architecture, corresponding to the
+BIN directory bin.f68881.  Once inside the CL one can check the current
+architecture by entering one of the following commands (the output in each
+case is shown as well).
+.XS
+cl> show IRAFARCH
+f68881
+.XE
+or
+.XS
+.cc #
+cl> show arch
+.f68881
+#cc
+.XE
+.LP
+If IRAFARCH is undefined at CL startup time a default architecture will be
+selected based on the current machine architecture, the available floating
+point hardware, and the available BINs.  The IRAFARCH variable controls not
+only the architecture of the executables used to run IRAF, but the libraries
+used to link IRAF programs, when doing software development from within the
+IRAF or host environment.
+.PP
+Additional information on multiple architecture support is provided in the
+system notes file for V2.8, file doc$notes.v28.
+
+.NH 2
+Shared libraries
+.PP
+Sun/IRAF provides a shared library facility for SunOS 4.0 and later versions
+of SunOS (but not for SunOS-3).  All architectures are supported.
+So long as everything is working properly, the existence and use of the shared
+library should be transparent to the user and to the site manager.
+This section gives an overview of the shared library facility to point
+the reader in the right direction in case questions should arise.
+.PP
+What the shared library facility does is take most of the IRAF system
+software (currently the contents of the \f(CWex\fR, \f(CWsys\fR,
+\f(CWvops\fR, and \f(CWos\fR libraries) and link it together into a special
+sharable image, the file \f(CWS\fIn\fP.e\fR in each core system BIN
+directory (\fIn\fR is the shared image version number, e.g. "S6.e").  This
+file is mapped into the virtual memory of each IRAF process at process
+startup time.  Since the shared image is shared by all IRAF processes, each
+process uses less physical memory, and the process pagein time is reduced,
+speeding process execution.  Likewise, since the subroutines forming the
+shared image are no longer linked into each individual process executable,
+substantial disk space is saved for the BIN directories.  Link time is
+correspondingly reduced, speeding software development.
+.PP
+The shared library facility consists of the \fBshared image\fR itself,
+which is an actual executable image (though not runnable on all systems),
+and the \fBshared library\fR, contained in the library lib$libshare.a,
+which defines each VOS symbol (subroutine), and which is what is linked
+into each IRAF program.  The shared library object module does not consume
+any space in the applications program, rather it consists entirely of symbols
+pointing to \fBtransfer vector\fR slots in the header area of the shared
+image.  The transfer vector slots point to the actual subroutines.
+.PP
+When an IRAF program is linked with \fIxc\fR, one has the option of linking
+with either the shared library or the individual system libraries.  Linking
+with the shared library is the default; the \f(CW-z\fR flag disables linking
+with the shared library.  In the final stages of linking \fIxc\fR runs the
+HSI utility \fIedsym\fR to edit the symbol table of the output executable,
+modifying the shared library (VOS) symbols to point directly into the shared
+image (to facilitate symbolic debugging), optionally deleting all shared
+library symbols, or performing some other operation upon the shared library
+symbols, depending upon the \fIxc\fR link flags given.
+.PP
+At process startup time, upon entry to the process main (a C main for
+Sun/IRAF) the shared image will not yet have been mapped into the address
+space of the process, hence any attempted references to VOS symbols would
+result in a segmentation violation.  The \fIzzstrt\fR procedure, called by
+the process main during process startup, opens the shared image file and
+maps it into the virtual space of the IRAF program.  Once the IRAF main
+prompt appears (when running an IRAF process standalone), all initialization
+will have completed.
+.PP
+Each BIN, if linked with the shared library, will have its own shared image
+file \f(CWS\fIn\fP.e\fR.  If the shared image is relinked this file will be
+moved to \f(CWS\fIn\fP.e.1\fR and the new shared image will take its place;
+any old shared image files should eventually be deleted to save disk space,
+once any IRAF processes using them have terminated.   Normally when the
+shared image is rebuilt it is not necessary to relink applications programs,
+since the transfer vector causes the linked application to be unaffected
+by relocation of the shared image functions.
+.PP
+If the shared image is rebuilt and its version number (the \fIn\fR in
+\f(CWS\fIn\fP.e\fR) is incremented, the transfer vector is rebuilt the new
+shared image cannot be used with previously linked applications.  These
+old applications will still continue to run, however, so long as the older
+shared image is still available.  It is common practice to have at least
+two shared image versions installed in a BIN directory.
+.PP
+Further information on the Sun/IRAF shared library facility in given in the
+IRAF V2.8 system notes file.  In particular, anyone doing extensive IRAF
+based software development should review this material, e.g., to learn how
+to debug processes that are linked with the shared image.
+
+.NH 2
+Layered software support
+.PP
+An IRAF installation consists of the core IRAF system and any number of
+external packages, or "layered software products".  As the name suggests,
+layered software products are layered upon the core IRAF system.  Layered
+software requires the facilities of the core system to run, and is portable
+to any computer which already runs IRAF.  Any number of layered products can
+be installed in IRAF to produce the IRAF system seen by the user at a
+given site.
+.PP
+The support provided by IRAF for layered software is essentially the same as
+that provided for maintaining the core IRAF system itself (the core system
+is a special case of a layered package).  Each layered package (usually this
+refers to a suite of subpackages) is a system in itself, similar in
+structure to the core IRAF system.  Hence, there is a LIB, one or more BINs,
+a help database, and all the sources and runtime files.  A good example of
+an external package is the NOAO package.  Except for the fact that NOAO is
+rooted in the IRAF directories, NOAO is equivalent to any other layered
+product, e.g., STSDAS, TABLES, XRAY, CTIO, NLOCAL, ICE, and so on.  In
+general, layered products should be rooted somewhere outside the IRAF
+directory tree to simplify updates.
+
+.NH 2
+Software management tools
+.PP
+IRAF software management is performed with a standard set of tools,
+consisting of the tasks in the SOFTOOLS package, plus the host system
+editors and debuggers.  Some of the most important and often used tools for
+IRAF software development and software maintenance are the following.
+.sp
+.RS
+.IP \f(CWmkhelpdb\fP 20
+Updates the HELP database of the core IRAF system or an external package.
+The core system, and each external package, has its own help database.
+The help database is the machine independent file \f(CWhelpdb.mip\fR in the
+package library (LIB directory).  The help database file is generated with
+\fImkhelpdb\fR by compiling the \f(CWroot.hd\fR file in the same directory.
+.IP \f(CWmkpkg\fP 20
+The "make-package" utility.  Used to make or update package trees.
+Will update the contents of the current directory tree.  When run at
+the root iraf directory, updates the full IRAF system; when run at the
+root directory of an external package, updates the external package.
+Note that updating the core IRAF system does not update any external
+packages (including NOAO).  When updating an external package, the
+package name must be specified, e.g., "\fImkpkg -p noao\fR".
+.IP \f(CWrmbin\fP 20
+Descends a directory tree or trees, finding and optionally listing or
+deleting all binary files therein.  This is used, for example, to strip
+the binaries from a directory tree to leave only sources, to force
+\fImkpkg\fR to do a full recompile of a package, or to locate all the
+binaries files for some reason.  IRAF has its own notion of what a binary
+file is.  By default, files with the "known" file extensions
+(.[aoe], .[xfh] etc.) are classified as binary or text
+(machine independent) files immediately,
+while a heuristic involving examination of the file data
+is used to classify other files.  Alternatively, a list of file extensions
+to be searched for may optionally be given.
+.IP \f(CWrtar,wtar\fP 20
+These are the portable IRAF tarfile writer (\fIwtar\fR) and reader
+(\fIrtar\fR).  About the only reasons to use these with Sun/IRAF
+are if one wants to move only the machine independent or source files
+(\fIwtar\fR, like \fIrmbin\fR, can discriminate between machine
+generated and machine independent files), or if one is importing files
+written to a tarfile on a VMS/IRAF system, where the files are blank
+padded and the trailing blanks need to be stripped with \fIrtar\fR.
+.IP \f(CWxc\fP 20
+The X (SPP) compiler.  This is analogous to the UNIX \fIcc\fR except
+that it can compile ".x" or SPP source files, knows how to link with the
+IRAF system libraries and the shared library, knows how to read the
+environment of external packages, and so on.
+.RE
+.sp
+.PP
+The SOFTOOLS package contains other tasks of interest, e.g., a program
+\fImktags\fR for making a tags file for the \fIvi\fR editor, a help
+database examine tool, and other tasks.  Further information on these
+tasks is available in the online help pages.
+
+.NH 2
+Modifying and updating a package
+.PP
+IRAF applications development is most conveniently performed from within the
+IRAF environment, since testing must be done from within the environment.
+The usual  edit-compile-test development cycle is illustrated below.  This
+takes place within the \fIpackage directory\fR containing all the files
+specific to a given package.
+.RS
+.IP \(bu
+Edit one or more source files.
+.IP \(bu
+Use \fImkpkg\fR to compile any modified files, or files which include a
+modified file, and relink the package executable.
+.IP \(bu
+Test the new executable.
+.RE
+.PP
+The mkpkg file for a package can be written to do anything,
+but by convention the following commands are usually provided.
+.sp
+.RS 
+.IP "\f(CWmkpkg\fP" 20
+The \fImkpkg\fR command with no arguments does the default mkpkg operation;
+for a subpackage this is usually the same as \fImkpkg relink\fR below.  For
+the root mkpkg in a layered package it udpates the entire layered package.
+.IP "\f(CWmkpkg libpkg.a\fP" 20
+Updates the package library, compiling any files which have been modified or
+which reference include files which have been modified.  Private package
+libraries are intentionally given the generic name libpkg.a to symbolize
+that they are private to the package.
+.IP "\f(CWmkpkg relink\fP" 20
+Rebuilds the package executable, i.e., updates the package library and
+relinks the package executable.  By convention, this is the file
+xx_\fIpkgname\fR.e\fR in the package directory, where \fIpkgname\fR is the
+package name.
+.IP "\f(CWmkpkg install\fP" 20
+Installs the package executable, i.e., renames the xx_foo.e file to x_foo.e
+in the global BIN directory for the layered package to which the subpackage
+\fIfoo\fR belongs.
+.IP "\f(CWmkpkg update\fP" 20
+Does everything, i.e., a \fIrelink\fR followed by an \fIinstall\fR.
+.RE
+.sp
+.PP
+If one wishes to test the new program before installing it one should do a
+\fIrelink\fR (i.e., merely type "mkpkg" since that defaults to relink), then
+run the host system debugger on the resultant executable.  The process is
+debugged standalone, running the task by giving its name to the standalone
+process interpreter.  The CL task \fIdparam\fR is useful for dumping a
+task's parameters to a text file to avoid having to answer parameter queries
+during process execution.  The LOGIPC debugging facility introduced in V2.10
+is also useful for debugging subprocesses.  If the new program is to be
+tested under the CL before installation, a \fItask\fR statement can be
+interactively typed into the CL to cause the CL to run the "xx_" version of
+the package executable, rather than old installed version.
+.PP
+When updating a package other than in the core IRAF system, the \f(CW-p\fR
+flag, or the equivalent \f(CWPKGENV\fR environment variable, must be used to
+indicate the system or layered product being updated.  For example, "mkpkg
+-p noao update" would be used to update one of the subpackages of the NOAO
+layered package.  If the package being updated references any libraries or
+include files in \fIother\fR layered packages, those packages must be
+indicated with a "-p pkgname" flag as well, to cause the external package to
+be searched.
+.PP
+The CL process cache can complicate debugging and testing if one forgets
+that it is there.  When a task is run under the CL, the executing process
+remains idle in the CL process cache following task termination.  If a new
+executable is installed while the old one is still in the process cache, the
+CL will automatically run the new executable (the CL checks the modify date
+on the executable file every time a task is run).  If however an executable is
+currently running, either in the process cache or because some other user is
+using the program, it may not be possible to set debugger breakpoints.
+.PP
+The IRAF shared image can also complicate debugging, although for most
+applications-level debugging the shared library is transparent.  By default
+the shared image symbols are included in the symbol table of an output
+executable following a link, so in a debug session the shared image will
+appear to be part of the applications program.  When debugging a program
+linked with the shared library, the process must be run with the \f(CW-w\fR
+flag to cause the shared image to be mapped with write permission, allowing
+breakpoints to be set in the shared image (that is, you type something like
+":r -w" when running the process under the debugger).  Linking with the
+\f(CW-z\fR flag will prevent use of the shared image entirely.
+.PP
+A full description of these techniques is beyond the scope of this manual,
+but one need not be an expert at IRAF software development techniques to
+perform simple updates.  Most simple revisions, e.g., bug fixes or updates,
+can be made by merely editing or replacing the affected files and typing
+.XS
+cl> mkpkg
+.XE
+or
+.XS
+cl> mkpkg update
+.XE
+to update the package.
+
+.NH 2
+Installing and maintaining layered software
+.PP
+The procedures for installing layered software products are similar to those
+used to install the core IRAF system, or update a package.
+Layered software may be distributed in source only form, or with binaries;
+it may be configured for a single architecture, or may be preconfigured
+to support multiple architectures.  The exact procedures to be followed
+to install a layered product will in general be product dependent, and should
+be documented in the installation guide for the product.
+.LP
+In brief, the procedure to be followed should resemble the following:
+.RS
+.IP \(bu
+Create the root directory for the new software, somewhere outside the
+IRAF directories.
+.IP \(bu
+Restore the files to disk from a tape or network archive distribution file.
+.IP \(bu
+Edit the core system file hlib$extern.pkg to "install" the new package in
+IRAF.  This file is the sole link between the IRAF core system and the
+external package.
+.IP \(bu
+Configure the package BIN directory or directories, either by restoring
+the BIN to disk from an archive file, or by recompiling and relinking the
+package with \fImkpkg\fR.
+.RE
+.LP
+As always, there are some little things to watch out for.
+When using \fImkpkg\fR on a layered product, you must give the name
+of the system being operated upon, e.g.,
+.XS
+cl> mkpkg -p foo update
+.XE
+where \fIfoo\fR is the system or package name, e.g., "noao", "local", etc.
+The \f(CW-p\fR flag can be omitted by defining \f(CWPKGENV\fR in your
+UNIX environment, but this only works for updates to a single package.
+.PP
+An external system of packages may be configured for multiple architecture
+support by repeating what was done for the core system.  One sets up several
+BIN directories, one for each architecture, named \f(CWbin.\fIarch\fR, where
+\fIarch\fR is "f68881", "ffpa", "sparc", etc.  These directories, or
+symbolic links to the actual directories, go into the root directory of the
+external system.  A symbolic link \f(CWbin\fR pointing to an empty directory
+bin.generic, and the directory itself, are added to the system's root
+directory.  The system is then stripped of its binaries with \fIrmbin\fR, if
+it is not already a source only system.  Examine the file zzsetenv.def in
+the layered package LIB directory to verify that the definition for the
+system BIN (which may be called anything) includes the string "(arch)",
+e.g.,
+.XS
+set noaobin = "noao$bin(arch)/"
+.XE
+.LP
+The binaries for each architecture may then be generated by configuring the
+system for the desired architecture and running \fImkpkg\fR to update the
+binaries, for example,
+.XS
+cl> cd foo
+cl> mkpkg sparc
+cl> mkpkg -p foo update >& spool &
+.XE
+where \fIfoo\fR is the name of the system being updated.  If any questions
+arise, examination of a working example of a system configured for multiple
+architecture support (e.g., the NOAO packages) may reveal the answers.
+.PP
+Once installed and configured, a layered product may be deinstalled merely
+by archiving the package directory tree, deleting the files, and commenting
+out the affected lines of hlib$extern.pkg.  With the BINs already configured
+reinstallation is a simple matter of restoring the files to disk and editing
+the extern.pkg file.
+
+.NH 2
+Configuring a custom LOCAL package
+.PP
+Anyone who uses IRAF enough will eventually want to add their own software
+to the system, by copying and modifying the distributed versions of
+programs, by obtaining and installing isolated programs written elsewhere,
+or by writing new programs of their own.  A single user can do this by
+developing software for their own personal use, defining the necessary
+\fItask\fR statements etc.  to run the software in their personal login.cl
+or loginuser.cl file.  To go one step further and install the new software
+in IRAF so that it can be used by everyone at a site, one must configure a
+custom local package.
+.PP
+The procedures for configuring and maintaining a custom LOCAL package are
+similar to those outlined in \(sc3.5 for installing and maintaining
+layered software, since a custom LOCAL will in fact be a layered software
+product, possibly even something one might want to export to another site
+(although custom LOCALs may contain non-portable or site specific software).
+.PP
+To make a custom local you make a copy of the "template local" package
+(iraf$local) somewhere outside the IRAF directory tree, change the name
+to whatever you wish to call the new layered package, and install it as
+outlined in \(sc3.5.  The purpose of the template local is to provide the
+framework necessary for a external package; a couple of simple tasks are
+provided in the template local to serve as examples.  Once you have
+configured a local copy of the template local and gotten it to compile and
+link, it should be a simple matter to add new tasks to the existing
+framework.
+
+.NH 2
+Updating the full IRAF system
+.PP
+This section will describe how to recompile or relink IRAF.  Before we get
+into this however, it should be emphasized that \fImost users will never
+need to recompile or relink IRAF\fR.  In fact, this is not something that
+one should attempt lightly - don't do it unless you have some special
+circumstance which requires a custom build of the system (such as a port).
+Even then you might want to set up a second copy of IRAF to be used for the
+experiment, keeping the production system around as the standard system.  If
+you change the system it is a good idea to make sure that you can undo the
+change.
+.PP
+While the procedure for building IRAF is straightforward, it is easy to make
+a mistake and without considerable knowledge of IRAF it may be difficult to
+recover from such a a mistake (for example, running out of disk space during
+a build, or an architecture mismatch resulting in a corrupted library or
+shared image build failure).  More seriously, the software - SunOS, the Sun
+Fortran compiler, the local system configuration, and IRAF - is changing
+constantly.  A build of IRAF brings all these things together at one time,
+and every build needs to be independently and carefully tested.  An OS
+upgrade or a new version of the Fortran compiler may not yet be supported by
+the version of IRAF you have locally. Any problems with the SunOS
+configuration can cause a build to fail, or introduce bugs (for example, Sun
+Fortran problems have been common since the compiler was unbundled).
+.PP
+The precompiled binaries we ship with IRAF have been carefully prepared and
+tested, usually over a period of months.  They are the same as are used at
+NOAO and at most IRAF sites, so even if there are bugs they will likely have
+already been seen elsewhere and a workaround determined.  If the bugs are
+new then since we have the exact same IRAF system we are more likely to be
+able to reproduce and fix the bug.  Often the bug is not in the IRAF
+software at all but in the host system or IRAF configuration.  As soon as an
+executable is rebuilt (even something as simple as a relink) you have new,
+untested, software.
+.NH 3
+The BOOTSTRAP
+.PP
+To fully build IRAF from the sources is a three step process.  First the
+system is "bootstrapped", which builds the host system interface (HSI)
+executables.  A "sysgen" of the core system is then performed; this compiles
+all the system libraries and builds the core system applications.  Finally,
+the bootstrap is then repeated, to make use of some of the functions from
+the IRAF libraries compiled in step two.
+.PP
+To bootstrap Sun/IRAF, login as IRAF and enter the commands shown below.
+This takes a while and generates a lot of output, so the output should be
+spooled in a file.
+.LP
+For a Sun-4 (sparc) system:
+.XS
+% cd $iraf
+% mkpkg sparc
+% cd $iraf/unix
+% reboot >& spool &
+.XE
+For a Sun-3 system:
+.XS
+% cd $iraf
+% mkpkg f68881
+% cd $iraf/unix
+% reboot >& spool &
+.XE
+.PP
+There are two types of bootstrap, the initial bootstrap starting from a
+source only system, called the NOVOS bootstrap, and the final or VOS
+bootstrap, performed once the IRAF system libraries \f(CWlibsys.a\fR and
+\f(CWlibvops.a\fR exist.  The bootstrap script \fIreboot\fR will
+automatically determine whether or not the VOS libraries are available and
+will perform a NOVOS bootstrap if the libraries cannot be found.  It is
+important to restore the sparc or f68881 architecture before attempting a
+bootstrap, as otherwise a NOVOS bootstrap will be performed.
+.NH 3
+The SYSGEN
+.PP
+By sysgen we refer to an update of the core IRAF system - all of the files
+comprising the runtime system, excluding the HSI which is generated by the
+bootstrap.  On a source only system, the sysgen will fully recompile the
+core system, build all libraries and applications, and link and install the
+shared image and executables.  On an already built system, the sysgen
+scans the full IRAF directory tree to see if anything is out of date,
+recompiles any files that need it, then relinks and installs new executables.
+.PP
+To do a full sysgen of IRAF one merely runs \fImkpkg\fR at the IRAF root.
+If the system is configured for multiple architecture support one must
+repeat the sysgen for each architecture.  Each sysgen builds or updates a
+single BIN directory.  Since a full sysgen takes a long time and generates a
+lot of output which later has to be reviewed, it is best to run the job in
+batch mode with the output redirected.  For example to update the sparc
+binaries:
+.XS
+% cd $iraf
+% mkpkg sparc
+% mkpkg >& spool &
+.XE
+To watch what is going on after this command has been submitted and while
+it is running, try
+.XS
+% tail -f spool
+.XE
+Sysgens are restartable, so if the sysgen aborts for any reason, simply fix
+the problem and start it up again.  Modules that have already been compiled
+should not need to be recompiled.  How long the sysgen takes depends upon
+how much work it has to do.  The worst case is if the system and
+applications libraries have to be fully recompiled.  If the system libraries
+already exist they will merely be updated.  Once the system libraries are up
+to date the sysgen will rebuild the shared library if any of the system
+libraries involved were modified, then the core system executables will be
+relinked.
+.PP
+A full sysgen generates a lot of output, too much to be safely reviewed for
+errors by simply paging the spool file.  Enter the following command to
+review the output (this assumes that the output has been saved in a file
+named "spool").
+.XS
+% mkpkg summary
+.XE
+It is normal for a number of compiler messages warning about assigning
+character data to an integer variable to appear in the spooled output
+if the full system has been compiled.  There should be no serious error
+messages if a supported and tested system is being recompiled.
+.PP
+The above procedure only updates the core IRAF system.  To update a layered
+product one must repeat the sysgen process for the layered system.  For
+example, to update the sparc binaries for the NOAO package:
+.XS
+% cd $iraf/noao
+% mkpkg sparc
+% mkpkg -p noao >& spool &
+.XE
+This must be repeated for each supported architecture.  Layered systems are
+independent of one another and hence must be updated separately.
+.PP
+To force a full recompile of the core system or a layered package, one can
+use \fIrmbin\fR to delete the objects, libraries, etc. scattered throughout
+the system, or do a "mkpkg generic" and then delete the \f(CWOBJS.arc.Z\fR
+file in the BIN one wishes to regenerate (the latter approach is probably
+safest).
+.PP
+A full IRAF core system sysgen currently takes anywhere from 3 to 30 hours,
+depending upon the system (e.g. from 30 hours on a VAX 11/750, to 3 hours on
+a big modern server).  On most systems a full sysgen is a good job to run
+overnight.
+.PP
+.NH 3
+Localized software changes
+.PP
+The bootstrap and the sysgen are unusual in that they update the entire
+HSI, core IRAF system, or layered package.  Many software changes are more
+localized.  If only a few files are changed a sysgen will pick up the changes
+and update whatever needs to be updated, but for localized changes a sysgen
+really does more than it needs to (if the changes are scattered all over
+the system an incremental sysgen-relink will still be best).
+.PP
+To make a localized change to a core system VOS library and update the
+linked applications to reflect the change all one really needs to do is
+change the desired source files, run \fImkpkg\fR in the library source
+directory to compile the modules and update the affected libraries, and then
+build a new IRAF shared image (this assumes that the changes affect only the
+libraries used to make the shared image, i.e., libsys, libex, libvops, and
+libos).  Updating only the shared image, without relinking all the
+applications, has the advantage that you can put the runtime system back the
+way it was by just swapping the old shared image back in - a single file.
+.PP
+For example, assume we want to make a minor change to some files in the VOS
+interface IMIO, compiling for the sparc architecture.  We could do this as
+follows (this assumes that one is logged in as IRAF and that the usual IRAF
+environment is defined).
+.XS
+% whoami
+iraf
+% cd $iraf
+% mkpkg sparc
+% cd imio
+     \fR(edit the files)\fP
+% mkpkg                          \fR# update IMIO libraries (libex)\fP
+%
+% cd $iraf/bin.sparc             \fR# save copy of old shared image\fP
+% cp S6.e S6.e.V210
+%
+% cd shlib
+% tar -cf ~/shlib.tar .          \fR# backup shlib just in case\fP
+% mkpkg update                   \fR# make and install new shared image\fP
+.XE
+.PP
+Changing applications is even easier.  Ensure that the system architecture
+is set correctly (i.e. "mkpkg sparc" at the iraf or layered package root),
+edit the affected files in the package source directory, and type "mkpkg -p
+<pkgname> update" in the root directory of the package being edited.  This
+will compile any modified files, and link and install a new executable.
+You can do this from within the CL and immediately run the revised program.
+.PP
+We should emphasize again that, although we document the procedures for
+making changes to the software here, to avoid introducing bugs we do not
+recommend changing any of the IRAF software except in unusual (or at least
+carefully controlled) circumstances.  To make custom changes to an
+application, it is best to make a local copy of the full package somewhere
+outside the standard IRAF system.  If changes are made to the IRAF system
+software it is best to set up an entire new copy of IRAF on a machine
+separate from the normal production installation, so that one can experiment
+at will without affecting the standard system.  An alternative which does
+not require duplicating the full system is to use the \f(CWIRAFULIB\fR
+environment variable.  This can be used to safely experiment with custom
+changes to the IRAF system software outside the main system; IRAFULIB lets
+you define a private directory to be searched for IRAF global include files,
+libraries, executables, etc., allowing you to have your own private versions
+of any of these.  See the system notes files for further information on how
+to use IRAFULIB.
+
+.NH
+Graphics and Image Display under SunView
+.PP
+Sun/IRAF may be used from any ordinary video or graphics terminal, or from a
+Sun workstation run either as a terminal or under the SunView windowing
+system (IRAF can also be run from X, but full support for X on Suns is not
+yet available at the time this is being written).  Our concern here is with
+the use of IRAF on a Sun workstation running SunView.  [Jul92 note - this
+section, discussing SunView support dates from the original Jun89 document
+and is being left as is.  The X11 support package will be system independent
+and is being distributed separately from Sun/IRAF.  If you wish, you can
+already run Sun/IRAF under X11, using \fIxterm\fR and \fIsaoimage\fR for
+graphics and image display].
+.PP
+The standard SunView system provides standard window tools which can be used
+to run IRAF, e.g., \fIshelltool\fR and \fItektool\fR.  \fIshelltool\fR is ok
+as a terminal but cannot do graphics.  \fItektool\fR can do graphics but is
+much too inflexible, and is not much good as a terminal since it cannot scroll
+or erase text.  To provide a reasonable combination of video terminal and
+vector graphics capabilities, we have extended SunView by adding a general
+purpose virtual graphics terminal window tool called \fIgterm\fR, and an
+image display server window tool called \fIimtool\fR.  Both programs are
+implemented at the SunView level as general purpose window tools, and are
+useful independently of IRAF.  Detailed documentation on the basic operation
+and use of these programs is given in the \fIgterm\fR(l) and \fIimtool\fR(1)
+manual pages.  Our concern in this document is with the use of these programs
+with IRAF.
+.NH 2
+The SunView environment
+.PP
+The graphics and image display tools provided with IRAF operate within the
+SunView windowing environment much like the standard tools provided with
+SunView.  To help illustrate the use of these tools, Sun/IRAF is distributed
+with a sample SunView environment already configured for the IRAF account.
+This consists of the following files in the IRAF account login directory,
+iraf$local.
+.RS
+.IP \f(CW.defaults\fP 20
+Sets up the defaults for how the window system looks, e.g., enables the
+custom rootmenu file.
+.IP \f(CW.rootmenu\fP 20
+An example of a sophisticated, multilevel custom rootmenu, including
+entries for gterm and imtool.
+.IP \f(CW.suntools\fP 20
+Defines a screen layout that includes gterm and imtool windows, including
+sizing and positioning the graphics window.
+.IP \f(CW.sunview\fP 20
+Same as the \f(CW.suntools\fP file, which Sun plans to rename
+to \f(CW.sunview\fP in a future version of SunOS.
+.IP \f(CW.ttyswrc\fP 20
+Defines some function keys for \fItty\fP subwindows (gterm).
+.RE
+.PP
+No one screen layout will suit all users or all applications.
+Everyone will wish to customize the workstation screen to suit their
+preferences and the type of work they are doing, but it is recommended
+that users copy these files to serve as a starting point.
+
+.NH 2
+Vector graphics capabilities
+.PP
+The standard graphics terminal emulator for Sun/IRAF under SunView is
+\fIgterm\fR, which emulates a conventional dual plane text/graphics terminal.
+This software terminal is driven via an ASCII datastream like a conventional
+hard terminal (except that the effective baud rate is much higher).
+The text window behaves like the Sun console and the graphics window
+behaves like a Tektronix 4012, plus some IRAF oriented extensions.
+Since gterm emulates standard text and graphics devices non-IRAF programs
+can easily be run as well as IRAF programs.
+.PP
+Configuring IRAF to use gterm is very simple.  The following command does
+the job.  This is normally executed by the login.cl or loginuser.cl file at
+login time.
+.XS
+cl> stty gterm
+.XE
+.PP
+A number of function keys are recognized by gterm which one should be aware
+of.  Some of these are built into gterm itself, others are defined in the
+default \f(CW.ttyswrc\fR file.
+.RS
+.IP F7
+Toggle between fullscreen graphics window and normal graphics window.
+.IP F8
+Clear (if in graphics mode) or enable (if in text mode) output to the
+graphics plane.  Used to manually put the terminal into 4012 emulation mode.
+.IP F9
+Clear (if in text mode) or enable (if in graphics mode) the text plane.
+Closing the graphics plane will also enable the text plane.
+.IP R1
+Set text window size to 24 lines by 80 columns.
+.IP R2
+Set text window size to 34 lines by 80 columns.
+.IP R3
+Set text window size to 40 lines by 80 columns.
+.IP R5
+Set text window size to 54 lines by 80 columns.
+Tallest possible text window using standard font.
+.RE
+.PP
+The text window may also be manually resized using the mouse but the
+function keys are most convenient for rapid changes to the window height.
+The IRAF software will automatically sense that the window size has
+changed whenever a screen oriented program is run.  The current window size
+can be printed with \f(CWstty show\fR, or updated with \f(CWstty resize\fR.
+.PP
+There is a \fBframe menu\fR which may be used to access a number of
+useful functions, e.g., logging of all output to the terminal, or bitmap
+hardcopies of the text or graphics windows or the full screen.  Control
+over the terminal setup is provided by a \fBsetup panel\fR.
+.PP
+Note that the \fIgraphics\fR window may also be resized and moved about on the
+screen.  A number of predefined standard window sizes are provided via the
+gterm setup panel, ranging from pretty small to the full screen.
+The graphics window may also be interactively adjusted with the mouse
+to some arbitrary size, but the advantage of the predefined window sizes
+is that they all have the same standard aspect ratio and size in characters
+(35x80).  Multiple IRAF sessions running in multiple gterm windows are
+possible; using different colors makes it easier to remember which window
+is which. 
+.PP
+Aside from the dynamic nature of windows in the SunView environment,
+operation of IRAF from a gterm window is straightforward and should present
+no problems for someone already familiar with the use of IRAF on a conventional
+graphics terminal.  Further information is given in the gterm manual page,
+\fIgterm\fR(l) (a UNIX level manpage).
+.NH 2
+Image Display capabilities
+.PP
+Image display for IRAF running in the SunView environment is provided
+by the \fIimtool\fR display server prototype.  The current \fIimtool\fR
+program provides a basic display capability, including programmed access
+from the IRAF environment to load images, interactive windowing of the
+display, pseudocolor, dithered (Postscript) or Sun rasterfile image hardcopy,
+an interactive image cursor readback capability, zoom and pan, a variety
+of frame buffer sizes, independent frame buffer and display window sizing,
+up to four frames, each with its own state, and programmable frame blink.
+\fIimtool\fR runs as a display server, meaning that it sits idle most of
+the time, waiting for some client, e.g., IRAF, to send it an image to be
+displayed via some form of interprocess communication.
+.PP
+To use imtool from within IRAF one must define the logical device and
+enable image cursor input.  For example,
+.XS
+cl> reset stdimage = imt512
+.XE
+would configure IRAF and imtool for use with a 512 pixel square frame buffer
+(image display image memory).  A variety of frame buffer sizes are
+predefined; see the \f(CWimtoolrc\fR file (normally in /usr/local/lib) for a
+complete list of possible configurations.
+.LP
+The image cursor is enabled by
+.XS
+cl> reset stdimcur = stdimage
+.XE
+.LP
+This is the default for Sun/IRAF.  Setting \f(CWstdimcur\fR to "text"
+disables the image cursor, allowing cursor values to be typed in interactively
+in the terminal window.  This is useful, for example, when running image
+oriented programs from a simple terminal.
+.PP
+The standard IRAF interface to the display server is the \fIdisplay\fR program
+in the TV package.  Automatic determination of the optimum intensity mapping
+to the 200 imtool greylevels is provided.  Entire frames can be displayed,
+or one can write to subregions of the display.  Other programs useful with
+the image display include \fIimexamine\fR, used to interactively examine
+images under image cursor control, \fIimedit\fR, used to edit images using
+the display, and \fItvmark\fR, used to write color graphics into a display
+frame.
+.PP
+The display server has the capability of displaying the cursor (mouse)
+position and pixel value in image pixel units as the mouse is moved about
+in the window.  In addition, text file cursor lists can be generated and
+displayed, or the image cursor can be read interactively from within IRAF.
+The image cursor may be called up at any time by typing
+.XS
+cl> =imcur
+.XE
+into the CL.  Applications programs which read the interactive image cursor
+will do this automatically during program execution.
+.PP
+Imtool supports a number of special function keys and other keyboard
+accelerators, a \fBframe menu\fR, a \fBsetup panel\fR and so on.
+Further information on the operation of imtool is given in the online manual
+page, \fIimtool\fR(l) (a UNIX level manpage).  Further information on the
+use of the image cursor is given in the online help page \f(CWcursors\fR.
+.NH 2
+Using the workstation with a remote compute server
+.PP
+A common mode of operation with a workstation is to run Sun/IRAF under
+SunView directly on the workstation which runs IRAF, accessing files either
+on a local disk, or on a remote disk via a network interface (NFS, IRAFKS,
+etc.).  It is also possible, however, to run SunView with gterm and imtool
+on the workstation, but run IRAF on a remote node, e.g., some powerful
+compute server such as a large Sun server, a large VAX, or a vector
+minisupercomputer or supercomputer, possibly quite some distance away.
+This is done by logging onto the workstation, starting up SunView and a
+\fIgterm\fR window, logging onto the remote machine with \fIrlogin\fR,
+\fItelnet\fR, or whatever, and starting up IRAF on the remote node.
+.LP
+After IRAF comes up one need only type
+.XS
+cl> stty gterm
+cl> reset node = \fIhostname\fP
+.XE
+to tell the remote IRAF that it is talking to a gterm window and that
+the image display is on the network node \fIhostname\fR.
+.PP
+In this mode one is effectively using the workstation as a sort of super
+terminal with powerful graphics and image display capabilities.  One gets
+the best of both worlds, i.e., a state of the art user interface, and the
+compute power of a large machine.  It matters little what operating system
+is used on the remote machine, so long as it also runs IRAF.
+Except for the details of the login sequence, operation is completely
+transparent; gterm does not care whether the process it is talking to is
+on a local or remote node.  Performance, e.g,. for image loads, is often
+\fIbetter\fR than when everything is run directly on the local node,
+due to the more powerful server.
+
+.NH
+Interfacing New Graphics Devices
+.PP
+There are three types of graphics devices that concern us here.
+These are the graphics terminals, graphics plotters, and image displays.
+.NH 2
+Graphics terminals
+.PP
+The IRAF system as distributed is capable of talking to just about any
+conventional graphics terminal or terminal emulator, using the \fIstdgraph\fR
+graphics kernel supplied with the system.  All one need do to interface to a
+new graphics terminal is add new graphcap and termcap entries for the device.
+This can take anywhere from a few hours to a few days, depending on one's
+level of expertise, and the characteristics of the device.  Be sure to check
+the contents of the dev$graphcap file to see if the terminal is already
+supported, before trying to write a new entry.  Useful documentation for
+writing graphcap entries is the GIO reference manual and the HELP pages for
+the \fIshowcap\fR and \fIstty\fR tasks (see \(sc2.2.6).  Assistance with
+interfacing new graphics terminals is available via the IRAF Hotline.
+.NH 2
+Graphics plotters
+.PP
+The current IRAF system comes with several graphics kernels used to drive
+graphics plotters.  The standard plotter interface the SGI graphics kernel,
+which is interfaced as the tasks \fIsgikern\fR and \fIstdplot\fR in the
+PLOT package.  Further information on the SGI plotter interface is given in
+the paper \fIThe IRAF Simple Graphics Interface\fR, a copy of which is
+included with the IRAF installation kit.
+.PP
+SGI device interfaces for most plotter devices already exist, and adding
+support for new devices is straightforward.  Sources for the SGI device
+translators supplied with the distributed system are maintained in the
+directory iraf/unix/gdev/sgidev.  NOAO serves as a clearinghouse for new SGI
+plotter device interfaces; contact us if you do not find support for a local
+plotter device in the distributed system, and if you plan to implement a new
+device interface let us know so that we may help other sites with the same
+device.
+.PP
+The older NCAR kernel is used to generate NCAR metacode and can be
+interfaced to an NCAR metacode translator at the host system level to get
+plots on devices supported by host-level NCAR metacode translators.  The
+host level NCAR metacode translators are not included in the standard IRAF
+distribution, but public domain versions of the NCAR implementation for UNIX
+systems are widely available.  A site which already has the NCAR software
+may wish to go this route, but the SGI interface will provide a more
+efficient and simpler solution in most cases.
+.PP
+The remaining possibility with the current system is the \fIcalcomp\fR kernel.
+Many sites will have a Calcomp or Versaplot library (or Calcomp compatible
+library) already available locally.  To make use of such a library to get
+plotter output on any devices supported by the interface, one may copy
+the library to the hlib directory and relink the Calcomp graphics
+kernel.
+.PP
+A graphcap entry for each new device will also be required.  Information on
+preparing graphcap entries for graphics devices is given in the GIO design
+document, and many actual working examples will be found in the graphcap
+file.  The best approach is usually to copy one of these and modify it.
+.NH 2
+Image display devices
+.PP
+The standard image display facility for a Sun workstation running the
+SunView window system is \fIimtool\fR (\(sc4.3).  Image display under the
+MIT X window system is also available using the \fIsaoimage\fR display
+server.  This was developed for IRAF by SAO; distribution kits are available
+from the IRAF network archive.
+.PP
+Some interfaces for hardware image display devices are also available,
+although a general display interface is not yet included in the system.
+Only the IIS model 70 and 75 are current supported by NOAO.  Interfaces for
+other devices are possible using the current datastream interface, which is
+based on the IIS model 70 datastream protocol with extensions for passing
+the WCS, image cursor readback, etc. (see the ZFIOGD driver in unix/gdev).
+This is how all the current displays, e.g., imtool and ximage, and the IIS
+devices, are interfaced, and there is no reason why other devices could not
+be interfaced to IRAF via the same interface.  Eventually this prototype
+interface will be obsoleted and replaced by a more general interface.
+
+.NH
+Host System Requirements
+.PP
+IRAF is currently supported on all Sun models, i.e., the Sun-3, Sun-4,
+Sun-386i, and SPARCstation (as well as many systems other than Sun of course).
+Any of these system will make excellent IRAF hosts.  Be aware that the
+386i is architecturally incompatible with the other Suns, which will cause
+problems in client/server configurations.
+.PP
+In a typical installation
+there will be a large central compute server, usually a fast Sun-4 with
+several Gb of fast SMD or IPI disk and 32-64 Mb of memory, serving a number
+of SPARCstation or Sun-3 or 4 nodes.  For scientific use, a color screen
+(16 inch is fine) and several hundred Mb of local disk is desirable.
+The local SCSI disk is comparatively slow and is no substitute for the large,
+fast disks on the server, but is cheap and is worthwhile for server
+independence alone.  The GX graphics accelerator option available on the
+newer systems is attractive and is recommended, finances permitting.
+.NH 2
+Memory requirements
+.PP
+The windowing systems used in these workstations tend to be very memory
+intensive; the typical screen with ten or so windows uses a lot of memory.
+With the introduction of the virtual files system in SunOS 4.0, the memory
+requirements of SunOS have increased ever further.  Interactive performance
+will suffer greatly if the system pages a lot.  Fortunately, memory is
+becoming relatively cheap.  No Sun system, including personal diskless
+nodes, should be configured with less than 8 Mb of main memory; 20 Mb or
+more is recommended if you plan to do a lot of image processing.  On
+servers, 32, 64, or even 128 Mb is not an unreasonable amount of memory to
+try to configure the system with.
+.NH 2
+Disk requirements
+.PP
+The amount of disk required by a user depends greatly on the application,
+so it is hard to recommend a minimum disk size.  For a system with access
+to a central server, no disk or 200-300 Mb of local SCSI disk is fine.
+For a standalone system with no access to large server, 500-600 Mb is
+about the minimum.  A server should have several Gb of fast disk.
+.NH 2
+Diskless nodes
+.PP
+For an application such as programming or word processing, a diskless node
+connected to a large file server is a cost effective approach delivering
+good performance.  Some local disk for boot, swap, and local file storage
+is desirable but not essential.  For most IRAF applications however, where
+serious image processing is planned, one is inevitably going to want to
+run large batch image processing jobs directly on the server, implying that
+a \fIcompute\fR rather than \fIfile\fR server is what is needed (i.e., one
+will want to avoid heavy NFS loading on the server).  A diskless node is
+still viable, but one will want to run jobs which involve heavy disk i/o 
+directly on the server, reserving the workstation for the interactive
+things, e.g., graphics and image display, and compute bound image analysis
+tasks.  Small SCSI disks are getting cheap enough that almost any color
+workstation equipped with say, 12-16 Mb of memory, probably warrants several
+Mb of local disk for server independence, swap, and local file storage.
+
+.SH
+Appendix A.  The IRAF Directory Structure
+.PP
+A graph of the current full Sun/IRAF directory structure is given at the
+end of this document.  The main branches of the tree are summarized below.
+Beneath the directories shown are some 300 subdirectories, the largest
+directory trees being \f(CWsys\fR, \f(CWpkg\fR, and \f(CWnoao\fR.
+The entire contents of all directories other than \f(CWunix\fR, \f(CWlocal\fR,
+and \f(CWdev\fR are fully portable, and are identical in all installations
+of IRAF sharing the same version number.
+.XS
+bin        \fR- the IRAF BIN directories\fP
+dev        \fR- device tables (termcap, graphcap, etc.)\fP
+doc        \fR- assorted IRAF manuals\fP
+lib        \fR- the system library; global files\fP
+local      \fR- iraf login directory; locally added software\fP
+math       \fR- sources for the mathematical libraries\fP
+noao       \fR- packages for NOAO data reduction\fP
+pkg        \fR- the IRAF applications packages\fP
+sys        \fR- the virtual operating system (VOS)\fP
+unix       \fR- the UNIX host system interface (HSI = kernel + bootstrap utilities)\fP
+.XE
+.LP
+The contents of the \f(CWunix\fR directory (host system interface) are
+as follows:
+.XS
+as         \fR- assembler sources\fP
+bin        \fR- the HSI BIN directories\fP
+boot       \fR- bootstrap utilities (mkpkg, rtar, wtar, etc.)\fP
+gdev       \fR- graphics device interfaces (SGI device translators)\fP
+hlib       \fR- host dependent library; global files\fP
+os         \fR- OS interface routines (UNIX/IRAF kernel)\fP
+reboot     \fR- executable script run to reboot the HSI\fP
+shlib      \fR- shared library facility sources\fP
+sun        \fR- gterm and imtool sources\fP
+.XE
+.PP
+If you will be working with the system much at the system level, it will be
+well worthwhile to spend some time exploring these directories and gaining
+familiarity with the system.