diff options
Diffstat (limited to 'doc/unixiraf.hlp')
| -rw-r--r-- | doc/unixiraf.hlp | 833 |
1 files changed, 833 insertions, 0 deletions
diff --git a/doc/unixiraf.hlp b/doc/unixiraf.hlp new file mode 100644 index 00000000..448013e9 --- /dev/null +++ b/doc/unixiraf.hlp @@ -0,0 +1,833 @@ +.help install Mar86 "UNIX/IRAF Installation Guide" +.sp 3 +.ce +\fBUNIX/IRAF Installation and Maintenance Guide\fR +.ce +(draft) + +.ce +Doug Tody +.ce +March 13, 1986 + +.nh +Introduction + + The procedure for installing IRAF on a UNIX host is complicated by the +great variety of computers which run UNIX, by the many small differences in +the operating system software on these machines, and by the hardware +differences between the machines. In general, the IRAF system can be ported +with a modest effort to any UNIX host which has a reliable and reasonably bug +free Fortran compiler (this cannot be taken for granted). From the standpoint +of ease of installation and reliability, the ideal case is a VAX running 4.2BSD +Berkeley UNIX (or ULTRIX, which is the same thing), since that is the +configuration we run on the IRAF software development machine. +NOAO has also recently ported the system to a SUN workstation running the +SUN version of 4.2BSD UNIX. This is a new system which has not yet seen +heavy use within NOAO and which cannot therefore be said to be as well +tested as the VAX version, but it is already clear that it will be a good +host (the initial port took only a few hours). + +Other ports, e.g., to other workstations or to System V UNIX, have been +talked about and are certainly feasible, but NOAO cannot presently support +such systems since we do not use them internally. This should not discourage +others from developing such systems, as other advantages may outweigh the +expense of having to port and support IRAF locally. To the extent that we +are able, we will be glad to assist with such ports. In the remainder of +this document, we shall assume that the host operating system is some variant +of 4.2BSD Berkeley UNIX. + +The ideal case of installing a "load and go" distribution tape containing +a precompiled and prelinked system is easy, except possibly for the graphics +interfaces. There are various levels of installations beyond this, becoming +progressively more involved, with a port of the system to a new version of +UNIX being the most ambitious. The possible levels of installations are +summarized below. +.ih +Load and Go +The system is read onto disk, several links are made in the UNIX system +directories providing hooks into the system, and the device and network tables +are tailored for the local system. +.ih +Load and Relink +This is like load and go, except that the system was shipped without the +executables to save space. Relinking is necessary but the relinking procedure +is fully automated and does not significantly increase the difficulty of the +installation. +.ih +Full Sysgen +In this case the system tables have already been configured for the host +machine, but neither the executables nor object libraries can be used for +some reason, e.g., because we are starting with a source only distribution. +The sysgen procedure is fully automated and in principle should pose no more +problems than a relink, but in practice it is unusual to get through a full +sysgen on a new machine without encountering compilation errors, usually +due to obscure errors in the Fortran optimizer. This sounds bad, but one can +usually hand compile the affected files with the optimizer turned off, and +then restart the sysgen, which will automatically pick up where it left off. + +On the VAX we routinely perform full system sysgens without any problems +whatsoever. A full sysgen on a VAX 750 class machine requires about 45 +minutes for the bootstrap (building the host interface), plus another 20 +hours to compile and link the machine independent part of the system. +.ih +Port to a New System +To port IRAF to a new version of UNIX requires some modifications to the +files in the host interface directories, followed by a full sysgen and lots +of testing. Typically most of the code in the host interface can be used +without change, with only minor changes to the remaining code, since the +different versions of UNIX are quite similar (as compared to, for example, +a port to a completely different operating system like VMS or AOS/VS). + +Note that even when the target system is a "fully compatible" 4.2BSD UNIX +system, some changes are likely to be necessary since all of these systems +are slightly different. For example, the SUN and ISI implementations of +4.2BSD UNIX employ different assemblers, and the Fortran compilers on the +two systems have diverged considerably. A port to Bell System V or one of +the UNIX look alikes would certainly require some changes to the IRAF kernel, +particularly in the exception handling, process control, and network interface +facilities. + +The changes required are likely to be minor for someone sufficiently familiar +with both IRAF and UNIX, but should not be underestimated. Every new port +produces its share of compile time errors (due to differences in the Fortran +compilers) and finds a few new bugs, both in the IRAF software and often in +the host Fortran compiler as well. A thorough understanding of both IRAF and +the host system is required to rapidly isolate such bugs. +.in -4 + +Fortunately, a port only has to be done once and most of the sites receiving +UNIX/IRAF will not need to do more than a relink or a sysgen, both of which +are straightforward. Many sites will not even need to relink, in which case +the installation is trivial. + +Once the basic system is functioning, it is still necessary to edit the device +and network tables to interface IRAF to the local terminals, printers, magtape +devices, describe the nodes in the local network, and so on. +Once that is done only the graphics device interfaces are left. +Conventional graphics terminals, i.e., Tektronix +compatibles with a serial interface, are not difficult. The worst case is +a new bit mapped display or image (greyscale) display device, which may +require the implementation of a new IRAF GIO graphics kernel for the device. + +The IRAF system is organized in such a way that the machine and device +dependent software is stored separately from the bulk of the software, +which is machine and device independent. This should make it relatively +easy to install new revisions of the system, provided the host and device +interfaces do not have to be modified. The procedure for installing a +minor revision is simply to read the revision tape into the system (containing +the BIN, DOC, LIB, SYS, PKG, and MATH directories), and then possibly do a +partial or full sysgen, depending upon whether the distribution included +executables and objects. The local device and network tables will not be +affected since they are stored in different directories (HOST and DEV) than +those on the tape. Note that a "minor" revision actually updates virtually +the entire system, since the host system interface is small compared to the +rest of the system. + +When a major revision is received it will be necessary to reinstall the +full system, but it is likely that the old device tables can be kept and +used in the new system, in which case even a full installation should only +take a couple of hours, excluding the time for a full sysgen if such is needed. +Once the initial version of IRAF has been installed, the procedure for +installing a minor revision is identical for all systems, including such +systems as VMS and AOS/VS as well as UNIX. + +Sites which are actively using IRAF will probably want to keep their systems +up to date, as the system is continually evolving and improving, and new +software is continually being added. To ensure that it will be easy to +install future updates, it is wise to store locally added software outside +the standard system, and to keep a log of all revisions, if any, made to +the standard system. The subdirectory LOCAL (off the IRAF root directory) +is provided for this purpose. NOAO should be informed of any local revisions +or bug fixes so that we have the opportunity to incorporate them in the +standard system. + +.nh +Installing the System +.nh 2 +Initial System Installation + + This section documents the procedure for installing a binary distribution +tape prepared on a compatible (VAX or SUN) system at NOAO. The procedure +outlined in this section is also used to install a source distribution, the +difference being that when one is done it is still necessary to do a sysgen +to compile and link the system. + +Few problems are expected when installing binary distributions for the VAX, +since all VAX hardware and (UNIX) software is pretty much the same. +For a system like the SUN this is not necessarily the case, e.g., a SUN-3 +distribution will have to be recompiled to run on a SUN-2, and a SUN-2 +distribution compiled with inline floating point instructions for the SKY +floating point board will have to be recompiled if the SKY board is not present. +Conversely, a system compiled with the SUN-2 portable floating point interface +will run whether or not the SKY board is present, but it might be desirable +to recompile the system with the inline code generation option, just for the +added speed. If you have received a binary SUN distribution, be sure to +check the system (SUN-2/3), operating system version, and floating point +compiler option used for compatibility with your system. + +.nh 3 +Create an IRAF Account + + The first step is to set up an account for IRAF. The pathname to the +root directory does not matter, but it is wise to keep it short to speed up +pathname resolution and to minimize the possibility of filename truncation. +The account should be set up to use \fBcsh\fR as the shell. The disk +partition containing IRAF should have about 45 Mb of space available for +the system; if necessary, the system can be stripped later to save space, +but the full 45 Mb is required for the installation. + +In what follows, we shall refer to the IRAF root directory as "$iraf", +as if it were a cshell \fBsetenv\fR variable. It is not however necessary to +define such a variable at this point, provided you do not try to type it +in as shown in the examples (type in the full pathname instead). + +.nh 3 +Read the Distribution Tape + + The system is distributed on one or more TAR format tapes or cassettes. +Login as IRAF, go to the IRAF root directory, and enter the \fBtar\fR command +shown for each tape in the distribution kit. The order in which the tapes +are read is not important. + +.ks +.nf + % cd $iraf + % tar -xpf /dev/XXXX +.fi +.ke + +The full system contains approximately 6000 files in over 200 directories; +the \fBtar\fR flags -tv are not recommended, as printing the filename can +slow things down considerably. It typically takes a half hour or so to read +the tapes. + +.nh 3 +Set up the Host System Environment + + Login as root (type \fIsu\fR) and modify the IRAF account to make +$iraf/local the login directory for user IRAF (this is done by editing the +/etc/passwd file - use \fIvipw\fR). Enter the following commands to enable +device allocation within IRAF. This only works if you have a binary +distribution; if not, it must be done later after the system has been +bootstrapped. + +.ks +.nf + % cd $iraf/unix/hlib + % /etc/chown 0 alloc.e # (zero, not "oh") +.fi +.ke + +While still logged in as root, make the following symbolic links in the +standard UNIX directories. We assume here that local utility programs are +installed in /usr/bin, but a different directory may be used for this +purpose on your system (any public directory which is in the default \fIpath\fR +for the average user will do). Since these are symbolic links, this +step may be performed even if a source distribution is being installed. + +Symbolic links are preferred to file copies because IRAF is a self contained +system and is not set up to install executables, etc. in external host system +directories. Symbolic links also eliminate the possibility of the installed +version of the file being obsolete. Although we use links here, no links are +used within the IRAF system itself. + +.ks +.nf + % cd /usr/include + % ln -s $iraf/unix/hlib/libc/iraf.h . + % cd /usr/bin + % ln -s $iraf/bin/cl.e cl + % ln -s $iraf/unix/hlib/mkiraf.csh mkiraf + % ln -s $iraf/unix/hlib/mkpkg.e mkpkg +.fi +.ke + +The following additional links are optional but are desirable if any IRAF +programming is anticipated. An alternative is to "source" the file +"$iraf/unix/hlib/irafuser.csh" in one's .login file (this only works for cshell +users). + +.ks +.nf + % ln -s $iraf/unix/hlib/generic.e generic + % ln -s $iraf/unix/hlib/rmbin.e rmbin + % ln -s $iraf/unix/hlib/rmfiles.e rmfiles + % ln -s $iraf/unix/hlib/rtar.e rtar + % ln -s $iraf/unix/hlib/wtar.e wtar + % ln -s $iraf/unix/hlib/xc.e xc +.fi +.ke + +Logout of root. If this is done by exiting "su", type "rehash" to make the +cshell aware of the new programs. + +.nh 3 +Configure the IRAF Environment + + While once again logged in as IRAF, edit the .login file in the IRAF +login directory $iraf/local. The \fBsetenv iraf\fR definition must be +changed to reflect the new IRAF root directory; everything else is optional +and may be personalized if desired. Note that IRAF assumes that all host +directory pathnames may be concatenated with a filename to produce the +pathname of the file, hence the directory pathname MUST end with a slash, +contrary to normal UNIX convention. + +.ks +.nf + % cd + % vi .login + % source .login +.fi +.ke + +After editing the .login file, "source" it to pick up the new environment +definitions. Hereafter we shall assume that the directories $iraf, $hlib, +etc. have been defined in the cshell environment by the .login file. At this +point you may want to read the file $hlib/irafuser.csh to see what has been +defined. + +There are several files in $hlib (the host system interface library) which +must now be edited to reflect the host system. Edit the following definitions +in the file $hlib/mkiraf.csh (the trailing slashes are omitted in this case +because this script is pure UNIX). The \fBmkiraf\fR script is run by the user +to autoconfigure the IRAF environment; see the CL User's Guide for additional +information on the use of this task. + +.ks +.nf + set iraf = "/iraf" + set imdir = "/tmp2/iraf" + set ttymsg = "Terminal types: vt100=basic terminal, ..." +.fi +.ke + +Set the value of \fBimdir\fR to the pathname of a public scratch directory +to be used for the storage of bulk image data. The \fBmkiraf\fR script +will create the default user image storage directories as subdirectories of +this directory. A scratch rather than user (login directory) file system is +normally used for this purpose to avoid storing bulk data on a backed up +user file system, and to facilitate the use of file deletion daemons to +automatically delete old files. Note that the user may override the default +\fBimdir\fR pathname defined in the LOGIN.CL file created by \fBmkiraf\fR. + +The \fBttymsg\fR prompt string is printed by the script to help the user +set the default terminal type for IRAF. Each terminal must have an entry +in the IRAF (not UNIX) \fBtermcap\fR file. + +Now descend to the subdirectory LIBC and edit the file "iraf.h", for which +we earlier made a symbolic link. This global C header file is required to +compile any IRAF C sources, and is also used by the system at runtime to +determine the IRAF root directory, as well as the pathnames of the HOST +and TMP logical directories. The definition of TMP defaults to the standard +UNIX /tmp and should not have to be changed. Make the obvious change to +the definitions of HOST and IRAF; HOST is the unix pathname of $iraf/unix. +This has to be defined at the system level because HOST might be, for example, +$iraf/vms instead of $iraf/unix. HOST is the root directory of the IRAF +host system interface. The remainder of the file contains many occurrences +of the pathname to the IRAF root. Use global replacement to change all +these definitions to the new IRAF root. + + +Assuming a full binary distribution, it should now be possible to return to +the IRAF login directory, type \fBmkiraf\fR to configure the IRAF environment, +and then \fBcl\fR to log into IRAF. Indeed, any user should be able to do +the same at this point. + +.ks +.nf + % cd + % mkiraf + % cl +.fi +.ke + +.nh 2 +Relinking the System + + Relinking the system is necessary if the system was shipped without +the executables in the BIN directory. In order to relink the system must +first have been \fIbootstrapped\fR. When the system is shipped without +executables (to save space) it will already have been bootstrapped. +If it is necessary to bootstrap the system, e.g., given a source only +distribution, go read section 2.4 before trying to relink the system. + +The system is relinked by the bootstrap utility program \fBmkpkg\fR. +The \fBmkpkg\fR program is driven by the MKPKG files found in all IRAF +source directories. Running \fBmkpkg\fR in a directory causes the +contents of that directory, normally an applications package or library, +to be updated, along with the contents of all subdirectories referenced +by the root MKPKG file. + +Running \fBmkpkg\fR in the root IRAF directory causes the entire system to +be updated. If the system libraries are all up to date, the effect is to +relink the system. If the system has been modified and some library modules +have to be recompiled and inserted into the system libraries, then the +operation is a partial sysgen. If there are no libraries or object libraries +then we have a full sysgen, which is the topic of the next section. +The \fBmkpkg\fR utility is documented in detail in the IRAF User's Guide, +in the manual pages for the \fBsoftools\fR package. + +To relink all of IRAF, go to the root and run \fBmkpkg\fR, i.e., + +.ks +.nf + % cd $iraf + % mkpkg +.fi +.ke + +The program will inspect all source modules and verify that the system +libraries are up to date, then relink the system executables, followed by +all the applications executables, installing the executable files in the +BIN directory. + +.nh 3 +Relinking Individual Packages + + It is just as easy to relink the individual IRAF packages, e.g., after +a bug has been fixed, or if an update of a package is received by electronic +mail. This would normally be done from within IRAF since the next step +is to test the new package, so we will use the "cl>" prompt in the examples, +but since \fBmkpkg\fR is a bootstrap utility (IRAF foreign task), usage is +the same both in IRAF and in UNIX. + +To relink a package and install the new executable in BIN: + + cl> mkpkg update + +To relink a package, leaving the executable in the package directory for +testing or debugging prior to installation: + + cl> mkpkg + +To install an already linked executable after testing: + + cl> mkpkg install + +To update only the package library without relinking (this assumes that the +name of the library is LIBPKG.A): + + cl> mkpkg libpkg.a + +The "update", "install", and "libpkg.a" identifiers are entry points in the +MKPKG file, which may be read to see what is going on. + +As an actual example of a package relink, suppose we wanted to increase the +size of the stack area in the CL to 8000 elements, e.g., because the CL was +running out of space at runtime. We would go to the CL directory, edit +the file CONFIG.H, change the value of STACKSIZ to 8000, and then run +\fBmkpkg\fR: + +.ks +.nf + cl> cd cl + cl> ed config.h + cl> mkpkg update +.fi +.ke + +Since CONFIG.H is included by nearly all the CL source files, the entire +package would be recompiled unnecessarily, but it is safer that way. + +.nh 2 +Autogeneration of the System (SYSGEN) + + A full system sysgen is necessary when installing a source only version +of the system. The system must first have been bootstrapped; see section +2.4 if this has not yet been done. A full sysgen may also be necessary if +a binary distribution has been received but it is later discovered that it is +necessary or desirable to recompile the system. In this case the existing +libraries and objects must be deleted before the sysgen, else the sysgen +will be nothing more than a relink. The \fBrmbin\fR utility is used to +descend a directory tree, deleting all binary files therein. Note that +the ONLY case in which it is necessary to use \fBrmbin\fR is when we wish +to force the entire system to be recompiled. The \fBrmbin\fR task is yet +another bootstrap utility, and is documented in the manual pages for the +\fBsoftools\fR package. + +.ks +.nf + % cd $iraf + % rmbin -vi bin lib pkg sys +.fi +.ke + +This will delete all binaries in the portable part of the system, excluding +the HOST or UNIX directories (if you run \fBrmbin\fR on UNIX, you will have +to bootstrap the system as well). + +Before starting the full system sysgen it may be desirable to review the +switches in the file MKPKG.INC in the HLIB directory. +This is the global include file for the \fBmkpkg\fR utility, +and contains various switches controlling \fBmkpkg\fR, e.g., which packages +will be compiled, and the default compiler and linker flags. + +Since a full sysgen takes a long time and generates a lot of output which +later has to be reviewed, they are always run in batch with the output +redirected, e.g.: + +.ks +.nf + % cd $iraf + % mkpkg >& spool & +.fi +.ke + +To watch what is going on after this command has been submitted and while +it is running, try + + % tail -f spool + +Sysgens are restartable, so if the sysgen aborts for any reason, simply +fix the problem and start it up again. + +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). + + % mkpkg summary + +It is normal for a number of compiler messages warning about assigning +character data to an integer variable to appear in the spooled output. +These are harmless on most (but not all) machines, and are due to questionable +coding practices in the old (pre-F77) NCAR graphics utilities. Hopefully the +problem will be fixed in an upcoming release by NCAR. + +The discussion up to now has centered on the full system sysgen. +Partial sysgens are actually much more common. For example, if an important +bug is fixed in the VOS or in the IRAF kernel, a (partial) sysgen should be +conducted to recompile the affected modules and relink the system. +An example of this occurs when the \fBtermcap\fR or \fBgraphcap\fR entries +for important local devices are cached by running the \fBttycompile\fR +task (another \fBsoftools\fR utility). A sysgen is required after regenerating +the cache tables, since these must be compiled and linked into the affected +programs to have any effect. + +.nh 2 +Bootstrapping the System + + A bootstrap is like a full system sysgen, except that it is the host +system interface (kernel and bootstrap utilities) which are compiled and +linked, rather than IRAF itself. The system must be bootstrapped before +a sysgen is possible, since the bootstrap utilities are required to do a +sysgen. The two operations are distinct because only the bootstrap is +machine dependent; everything else works the same on all IRAF systems. + +The bootstrap operation is necessary when installing the system from a +source only distribution tape. We assume that the files in the host system +interface have already been configured for the host system. If this is +not the case, then we are doing a port, which is a lot more ambitious than +a simple bootstrap. + +To bootstrap UNIX/IRAF, go to the UNIX directory and interpret the shell +script MKPKG.CSH. This takes about 45 minutes, so the output should be +spooled in a file. Note that (for no good reason) the files have a .CSH +extension even though we have chosen to use the Bourne shell to execute +the commands therein. + +.ks +.nf + % cd $iraf/unix + % sh -x mkpkg.csh >& spool & +.fi +.ke + +A bootstrap recompiles everything whether it needs to or not, so it is +usually not necessary to delete the binaries before doing a full bootstrap. + +.nh 2 +Configuring the IRAF Device Tables + + The following files should now be edited to define the default terminal, +printer, editor, and so on for your system. Any part of this can be left +until later if desired. + +.ls 4 \fB$hlib/zzsetenv.def\fR +This file contains the name of the default editor, the default names of all +the standard devices, and a number of other definitions which are not site +dependent and which can therefore be ignored. To be accessible by the IRAF +system, each local device named must also have an entry in the TERMCAP file +(terminals and printers) or GRAPHCAP file (graphics terminals and image +displays) in DEV. There must also be an "editor.ED" file in DEV +for the named editor; EDT, EMACS, and VI are currently supported. +Edit the string to the right of the equals sign for the following entries. +Sample values are shown. + +.ks +.nf + set editor = "vi" + set printer = "imagen" + set stdgraph = "vt640" + set stdimage = "iism70l" + set stdplot = "versatec" + set terminal = "vt640" +.fi +.ke + +For example, you may wish to change the default editor to "emacs" (heaven +forbid), the default printer to "versatec", the default image display to +"iism75", and the default terminal to "vt100". Note that only the IIS model +70 and 75 image displays are directly supported by the current system. +Display code is also available for the DeAnza displays from STScI for VMS +hosts, but nothing is currently available for UNIX hosts (NOAO will directly +support the DeAnza sometime in 1986). The complex issues of the graphics +and display interfaces are discussed more fully in a later section. +.le + +.ls 4 \fB$iraf/dev/devices\fR +This file contains a list of the allocatable devices (primarily tape drives) +for the local system. It should be obvious how to change it by reading the +comments in the file and studying the current values, which are for our system. +.le + +.ls 4 \fB$iraf/dev/termcap\fR +There must be entries in this file for all local terminal and printer +devices you wish to access from IRAF (there is no \fBprintcap\fR file in IRAF). +The entry for a printer contains one special (non-\fBtermcap\fR) entry, +called DD. This consists of three fields: node!device, the template for the +temporary spoolfile, and the UNIX command to be used to dispose of the file to +the printer. On Berkeley UNIX it is rarely necessary to make use of the node +name capability, since the UNIX \fBlpr\fR already provides this capability. + +If you have a new terminal which has no entry in the termcap file provided, +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. +.le + +.ls 4 \fB$iraf/dev/graphcap\fR +There must be entries in this file for all graphics terminals, batch plotters, +and image displays accessed by IRAF programs. Weird graphics terminals will +need a new entry. The IRAF file "sys$gio/doc/gio.hlp" contains docs for +graphcap. A printed copy of this document is available upon request, however +once IRAF is up you may find it easier to generate your own copy using HELP, +as follows: + +.nf + cl> cd sys$gio/doc + cl> help gio.hlp fi+ | lprint +.fi + +The manual page for the \fBshowcap\fR task should also be printed since this +utility is useful for generating new graphcap entries. More focused +documentation will be available eventually. Telephone consultation is +available for those who need it. We ask that new graphcap entries be sent +back to us so that we may include them in the master graphcap file for other +sites to use. +.le + +.ls +The DEV directory also contains a number of files (HOSTS, HOSTLOGIN, and UHOSTS) +used by the IRAF network software. We depend upon the networking capabilities +of IRAF heavily at NOAO to access image displays, printers, files, etc. resident +upon remote nodes (the IRAF network interface is also capable of spawning +subprocess and background jobs on remote nodes, and works even when the nodes +run different host operating systems, e.g., both UNIX and VMS). + +We expect that most sites will not need this capability initially, hence +documentation of the networking software will be left for later. For sites +that want to try it out, all that is necessary to enable networking is to +edit the three networking files in the DEV directory, and install IRAF on +the other nodes. It does not matter what native operating system runs on the +remote nodes, so long as it runs IRAF as well. The source for the network +interface is in the sys$ki directory, and a discussion of the conceptual +design of the interface is given in the README file in that directory. +.le + +.nh 2 +Login to IRAF and Run the Test Procedure + + Congratulations! You should now have a fully functional IRAF system. +At this point it would probably be wise to read the CL User's Guide, +if you have not already done so. Once the IRAF environment is configured +with \fBmkiraf\fR (discussed earlier) one need only enter the CL command +to start up the CL. After a bit IRAF should print the message of the day +and the root menu, and issue the "cl> " prompt. + + % cl + +Once in the CL, you will probably have magtape and printer access, are likely +to have graphics terminal access, and very possibly will not have either +image display access or graphics plotter access. If the graphics terminal +capability is ready the next step is to run the IRAF test procedure to +verify that all is working well, as well as try out a few of the many tasks +in the system. If the graphics terminal is not up yet, there is probably +no point in running the test procedure. To run the test procedure, read +the documentation in volume 1A of the IRAF User's Guide and follow the +instructions therein. + +.nh +Tuning Considerations + + There are two things that are commonly done to tune UNIX/IRAF for a +particular host system: + +.nf + o Precompile selected TERMCAP and GRAPHCAP entries + o Strip the system to reduce disk consumption +.fi + +.nh 2 +Precompiling TERMCAP and GRAPHCAP Entries + + Precompilation of a termcap or graphcap entry is a technique used to +speed runtime access of the entry for that device. If the entry is not +precompiled the termcap or graphcap file must be physically opened and +scanned at runtime to read the desired entry. This causes a noticeable +delay of as much as a second when clearing the terminal screen or plotting +a graph, hence it is usually worthwhile to cache the entries for commonly +used video and graphics terminals. It is not worthwhile for printers, +plotters, and image displays. + +The system comes with selected termcap and graphcap entries already +precompiled. To see which devices are precompiled, page the cache data +files, dev$cachet.dat (for termcap) and dev$cacheg.dat (for graphcap). +To cache a different set of entries one must regenerate these files with the +\fBmkttydata\fR task in the \fBsoftools\fR package, and then do a full +sysgen with the \fBmkpkg\fR utility. Detailed instructions are given in +the manual page for \fBmkttydata\fR. + +.nh 2 +Stripping the System to Reduce Disk Consumption + + 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 \fBrmfiles\fR (in the \fBsoftools\fR package, of course) is provided +for this purpose. It is not necessary to run \fBrmfiles\fR directly to strip +the system. The preferred technique is to enter the commands given below. +The example is for the cshell for consistency with the rest of this document, +but this could be done from within the CL as well. + +.nf + % cd $iraf + % mkpkg strip +.fi + +This will preserve all runtime files, permitting use of the standard system +as well as user software development. The size of the system is reduced +from about 41 Mb (megabytes) to around 19 Mb. One can optionally enter the +command "mkpkg stripall" to delete the system libraries as well, but this +saves only another couple of Mb and a full sysgen or a tape reload will be +required to regain the capability to link user programs with the IRAF +libraries, or relink the IRAF executables. + +.nh +Interfacing to New Graphics Devices + + There are three types of graphics devices that concern us here. +These are the graphics terminals, graphics plotters, and image displays. +The topic of interfacing to these devices has already been discussed in +the letter which was sent out with the IRAF questionnaire, hence the +discussion given here will be brief. + +.nh 2 +Graphics Terminals + + The IRAF system as distributed is capable of talking to just about any +conventional graphics terminal, using the \fBstdgraph\fR graphics kernel +supplied with the system. All one need do to interface to a new graphics +terminal is add a new graphcap entry for the device. This can take anywhere +from a few hours to a few days, depending on one's level of expertise, and the +perversity of the device in question. + +The fancy bit mapped, high resolution graphics displays common on "workstations" +like the MicroVax and the SUN cannot be driven (very well) by the existing +\fBstdgraph\fR graphics kernel. We are actively developing new graphics kernels +for these devices, and they should be available later this year. These systems +often come with some graphics software, e.g., CORE, GKS, or CGI, but a good +interface requires interaction with the window management software as well, +hence each workstation will probably require a customized graphics kernel. + +.nh 2 +Graphics Plotters + + The current IRAF system comes with three graphics kernels usable to drive +graphics plotters. Additional kernels are under development to interface the +IRAF graphics subsystem to GKS, CGI, and CORE. + +The \fBstdgraph\fR kernel can in principle be used to make +plots on many devices by using a Tek graphcap entry, redirecting the Tek +drawing instructions into a file, and using the Tek emulation software that +comes with most plotters to generate the plot. A more streamlined interface +is possible but is not yet available. + +The supplied \fBstdplot\fR kernel is used to generate NCAR metacode and can be +interfaced to an NCAR metacode translator at the host system level to get +excellent plots on the Versatec, Imagen, and other similar devices if NCAR +metacode translators are available. This is the kernel we currently depend +upon most heavily at NOAO for plotter output. + +Unfortunately, the host level NCAR metacode translators are not included in +the standard IRAF distribution but are required for a plot. The necessary +software is however in the public domain and is in use at NOAO, hence is +available upon special request. + +The remaining possibility with the current system is the \fBcalcomp\fR kernel. +Many sites will have a Calcomp or Versaplot library (or Calcomp compatible +library) already available locally. It should be possible to edit the name +of the library in the hlib$mkpkg.inc file and relink the Calcomp graphics +kernel to get output on any devices supported by the library. +The following commands should suffice to relink and install the Calcomp +graphics kernel, assuming a Calcomp library is available locally: + +.nf + % cd $iraf/sys/gio/calcomp + % mkpkg update +.fi + +A graphcap entry may also be required. + +.nh 2 +Image Displays + + The IRAF system as currently supported directly supports only the +IIS model 70 and 75 image displays (a Peritek interface of sorts is +also available for VAX/UNIX hosts). The 8 bit color display for the SUN-3 +is on order and we expect to use it for image display. We are expecting +to take delivery of a MicroVax with bit mapped graphics display and DeAnza +image display later this year. + +We cannot do much to help sites with other image displays until the new +IRAF display interface (which will be based on the IDI standard) is completed. +Work is scheduled to begin on this in the spring, hence the software should +become available this summer or fall. The new interface and associated TV +package software will be a great improvement over what is currently available; +the current interface is a prototype and is quite minimal, e.g., it does +not support image cursor readback, although it is fine for image display. + +In the meantime, the simplest approach is to use the new IMFORT interface +and whatever non-IRAF display software you currently have to construct +an interim display program. The IMFORT library provides host system Fortran +or C programs with access to IRAF images. The only documentation +currently available for IMFORT is the README file in the directory +$iraf/sys/imio/imfort. Sample Fortran programs and a UNIX make script +showing how to link are given in the same directory. + +.nh +The IRAF Directory Structure + + The current IRAF directory structure (new directories are constantly +being added) is documented in the Appendix. The main branches of the tree +are the following. + +.nf + bin - installed executables + dev - device tables (termcap, graphcap, etc.) + doc - assorted IRAF manuals + lib - the system library; object libraries, global files + local - your login directory + math - sources for the mathematical libraries + pkg - the IRAF applications packages + sys - the virtual operating system (VOS) + unix - the UNIX system interface (kernel + bootstrap utilities) + vms - the VMS system interface (kernel + bootstrap utilities) +.fi + +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. +.endhelp |