VMS/IRAF provides a shared library facility to reduce disk and memory requirements. What the shared library facility does is take most of the IRAF system software (currently the contents of the EX, SYS, VOPS, and OS libraries) and link it together into a special shareable image, the file s_iraf.e in the core BIN directory. 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 directory. Link time is correspondingly reduced, speeding software development. For the shared library to be effective, it must be installed in system memory as described in installing .
An IRAF installation consists of the core 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 depends upon the core system for all of its functionality and is portable to any computer which already runs IRAF. Any number of layered products can be combined with the core system to produce the IRAF system used at a specific site. Due to disk space limitations it is likely that a given site will not wish to have all the available layered software products installed and on line at any one time.
The support provided for layered software is essentially the same as that provided for maintaining the core system itself. Each "external package" (in most cases this actually refers to a tree of packages) 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 happens to be located in the IRAF root directory, NOAO is equivalent to any other layered product, e.g., STSDAS, PROS, CTIOLOCAL, KPNOLOCAL, etc. Other layered products should be rooted somewhere outside the [IRAF] directory tree to simplify updates.
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.
The SOFTOOLS package contains other tasks of interest, e.g., a program mktags for making a tags file for the vi editor, a help database examine tool, and other tasks. Further information on these tasks is available in the online help pages.
IRAF applications development (including revisions to existing programs) is most conveniently performed from within the IRAF environment, since testing must be done from within the environment. The usual development cycle is as follows. This takes place within the package directory containing all the sources and mkpkg-files for the package.
The mkpkg file for a package can be written to do anything, but by convention the following commands are usually provided.
If one wishes to test the new program before installing it one should do a relink (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 typing its name into the standalone process interpreter. The CL task dparam is useful for dumping a task's parameters to a text file to avoid having to answer innumerable parameter queries during process execution. If the new program is to be tested under the CL before installation, a task statement can be interactively typed into the CL to cause the CL to run the "xx_" version of the package executable, rather than the old installed version.
When updating a package other than in the core system, the -p flag, or the equivalent PKGENV logical name, 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 packages forming the NOAO system of packages.
The CL process cache can complicate debugging and testing if one forgets that it is there. Recall that 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 flprcache command must be entered to force the CL to run the new executable. If 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 breakpoints under the debugger.
The shared library can also complicate debugging, although for most applications-level debugging the shared library is transparent. If it is necessary to debug IRAF system libraries, contact the IRAF Hotline for assistance.
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
plus maybe a flpr if the old executable is still sitting idle in the process cache.
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. 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.
In brief, the procedure to be followed should resemble the following:
As always, there are some little things to watch out for. When using mkpkg on a layered package, you must give the name of the package being updated, plus the names of any other external packages used to build the target package, e.g.,
where foo is the name of the package being update, e.g., "noao", "local", etc. The -p flag can be omitted by defining PKGENV as a VMS logical name.
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 in 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.
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 personal use, defining the necessary task statements, etc. to run the software in the personal login.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.
The procedures for configuring and maintaining a custom LOCAL package are similar to those outlined in ( installing ) 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 often contain non-portable or site specific software).
To set up a custom LOCAL, start by making a local copy of the template local package that comes with the distributed system and editing hlib$extern.pkg to make the location of the new package known. If you make a source only tar or backup archive of iraf$local and install it as outlined in ( modifying ), you will have a custom LOCAL. The purpose of the template LOCAL is to provide the framework necessary for an 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.
All current IRAF distributions come with the system already bootstrapped, i.e., the host system interface (HSI) comes with the HSI binary executables already built. A bootstrap should not be necessary unless one is doing something unusual, e.g., installing a bugfix or making some other revision to the HSI.
A bootstrap is like a full system sysgen, except that it is the host system interface (kernel and bootstrap utilities) which is 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 utilities are required for system maintenance of the main system and hence must be linked first. However, unless a bug fix or other revision is made to one of the main system libraries (particularly LIBOS), there should be no reason for a user site ever to need to bootstrap the system. The bootstrap utilities are linked with the option /NOSYSSHARE, hence they should run on most versions of VMS.
The bootstrap utilities are written in C, and the DEC C compiler is required to compile or link these utilities. The C compiler is not required to run the prelinked binaries distributed with the system. To recompile and link the bootstrap utilities, i.e., to "bootstrap" IRAF, enter the commands shown below. Note that the HSI is always recompiled during a bootstrap; there is no provision for merely relinking the entire HSI (some individual programs can however be relinked manually by doing a "mkpkg update" in the program source directory).
The bootstrap should take 30 to 45 minutes on an unloaded 11/780. Once the bootstrap utilities have been relinked and installed in hlib, the main system may be relinked.
Updating the system libraries, i.e., recompiling selected object modules and inserting them into the system object libraries, is necessary if any system source files are edited or otherwise modified.
The system libraries may be updated either from within the IRAF CL, or from DCL. For example, from within DCL:
The brackets around mathlibs just mean "optional"; do not actually include the brackets if you need to rebuild the math libraries. This command will run the mkpkg utility, which will update each system library in turn, descending into the tree of source directories and checking the date of each object module therein against the dates of the source files and dependency files used to produce the object module, and recompiling any object modules which are out of date. In the worst case, e.g., if the system libraries have been deleted, the entire VOS (virtual operating system) will be recompiled. If it is known that no changes have been made to the math library source files, the optional mathlibs argument may be omitted to save some time.
The IRAF shared library ([IRAF.BIN]S_IRAF.EXE) is constructed by linking the contents of the four main IRAF system libraries LIBEX, LIBSYS, LIBVOPS, and LIBOS. Hence, the system libraries must exist and be up to date before linking the shared library. The shared library must be installed in bin before it can be used to link any applications programs. At present, the shared library does not use transfer vectors, hence the full system must be relinked following any changes to the shared library. Note that since the shared library is normally installed in system memory, all installed IRAF images should be deinstalled and later reinstalled whenever the shared library is rebuilt. IRAF will not be runnable while this is taking place.
In the current release of IRAF the procedure for building the shared library has not yet been integrated into the automatic system generation procedure. Furthermore, utility tasks in the main IRAF system are currently used to build the shared library, so it is necessary to have at least part of the main system functioning before the shared library can be built. These problems (and the transfer vector problem) will be fixed in a future release of VMS/IRAF.
The shared library is rebuilt from within a running IRAF system that provides at a minimum the three executables CL.EXE, X_SYSTEM.EXE, and X_LISTS.EXE. If these executables do not yet exist or are not runnable, rebuild them as follows. Note the use of the "-z" link flag to link the new executables without the shared library.
Now startup the CL and change to the directory hlib$share, which contains the code used to build the shared library.
$ set default [iraf.local]
$ cl
(cl starts up...)
cl> cd hlib$share
The following commands will rebuild the shared library and install it in bin. This takes ten minutes or so.
cl> cl < makeshare_alpha.cl
(takes a while)
cl> mkpkg install
cl> purge
cl> logout
The system libraries can be updated ( updating ) and the shared library rebuilt while IRAF is in use by normal users, however as soon as the command mkpkg install is executed (moving the new S_IRAF.EXE to bin) execution of normal user programs is at risk and one should kick all IRAF users off the machine and deinstall any installed IRAF images. The system may now be relinked and the newly linked shared library and images reinstalled, after which the system is ready for normal use again. Note that makeshare creates a load map s_iraf.map for s_iraf.e that should be deleted when no longer needed (it is quite large).
The following DCL commands may be entered to relink the main IRAF system, installing the newly linked executables in bin. Note that any IRAF executables that have been installed in system memory must be deinstalled and reinstalled ( installing ) following the relink.
The command shown causes the full system to be relinked (or recompiled and relinked if any files have been modified) using the default compile and link switches defined in the global mkpkg include file hlib$mkpkg.inc. Any system wide changes in how the system is generated should be implemented by editing the contents of this file. For example, the default file supplied with the system includes the following line:
$set LFLAGS = "" # default XC link flags
This switch defines the switches to be passed to the HSI bootstrap utility program xc to link the IRAF executables (no switches are given, hence the default link action will be taken). The switch "-z" may be included in the xc command line to link an executable directly against the system object libraries, rather than using the shared library. Hence, to relink IRAF without using the IRAF shared library (as is necessary for all but one system when there are multiple versions of IRAF simultaneously installed on the same machine) we would change the definition of LFLAGS as follows:
$set LFLAGS = "-z" # default XC link flags
A full system relink takes approximately 30 minutes, or significantly less if the shared library is used. A full system compile and relink takes 9-24 hours depending upon the host system.
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 NOAO package:
Layered systems are completely independent of one another and hence must be updated separately.