UNIX/IRAF Site Manager's Guide

UNIX/IRAF Site Manager's Guide

3.5. Modifying and updating a package

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 package directory containing all the files specific to a given package.

The mkpkg file for a package can be written to do anything, but by convention the following commands are usually provided.

The mkpkg command with no arguments does the default mkpkg operation; for a subpackage this is usually the same as mkpkg relink below. For the root mkpkg in a layered package it udpates the entire layered package.
mkpkg libpkg.a
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.
mkpkg relink
Rebuilds the package executable, i.e., updates the package library and relinks the package executable. By convention, this is the file xx_pkgname.e in the package directory, where pkgname is the package name.
mkpkg install
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 foo belongs.
mkpkg update
Does everything, i.e., a relink followed by an install.

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 giving its name to 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 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 task 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.

When updating a package other than in the core IRAF system, the -p flag, or the equivalent PKGENV 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 other layered packages, those packages must be indicated with a "-p pkgname" flag as well, to cause the external package to be searched.

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.

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 -w 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 -z flag will prevent use of the shared image entirely.

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

cl> mkpkg
cl> mkpkg update
to update the package.