From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001 From: Joe Hunkeler Date: Tue, 11 Aug 2015 16:51:37 -0400 Subject: Repatch (from linux) of OSX IRAF --- doc/sunsmg.ms | 1606 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1606 insertions(+) create mode 100644 doc/sunsmg.ms (limited to 'doc/sunsmg.ms') 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 + 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. -- cgit