This file is an nroff'ed copy of sec. #7 of "An Introductory User's Guide to IRAF SPP Programming" -- also available from the archive in the iraf/docs directory. See the README file in that directory for instructions for downloading that file. -------------------------- 7. Making an IRAF Package An IRAF package is a collection of tasks that are in some way related. For instance, an IRAF core system pack- age, such as the images, dataio, or plot packages, typically contains tasks that serve as generic tools for handling such things as IRAF images, tapes and outside data formats, or hardcopy and terminal graphics. On the other hand, a typi- cal package from the noao umbrella of packages collects together tasks that address a more specific data reduction need, e.g., the ccdred or apphot packages that provide sup- port for pipeline CCD reductions or for numerical aperture photometry, respectively. You may need such a cohesive package, or you may just have a number of homegrown tasks that you would like to add to IRAF. In either case, assembling an IRAF package is a good way to proceed, both for easy access by your users (perhaps only yourself), and also for easy maintenence by your programmers (perhaps only yourself). To make creating a package easier, a tar file of the examples package that contains all of the examples from this document is available by anonymous ftp from the IRAF network archive. You may find the canned examples package useful both to provide example programs to refer to while reading this document, and also as a straightforward platform to which to add your own tasks. The particular examples were written to provide hooks to support the more frequent sorts of things that users are likely to want to do within IRAF. Moreover, a small library of useful plotting and astronomi- cal algorithms has been included that may be referenced from within your own tasks. 7.1. Installing the examples Package The instructions for retrieving the examples package archive over the network and for unpacking this archive into your own work directory are of necessity host machine depen- dent. Rather than attempting to describe all possible host specific scenarios in adequate detail, the particular instructions given below are for SunOS v4.N. These should apply to most varieties of Unix, particularly Berkeley dialects. You should be able to extrapolate to your situa- tion. The following is a typical anonymous ftp session to retrieve the examples package archive file. The short retrieval instructions for the experienced Internet user are that the archive is contained in the compressed tar file spp_examples.tar.Z in the directory iraf/docs accessable by binary anonymous ftp on the host iraf.noao.edu (which has the Internet address 140.252.1.1). Note that a compressed PostScript version of the document you are reading is located in the iraf/docs directory in the file sppguide.ps.Z. The first step should be to create an empty directory on your own machine in which to place the package files: % cd someplace_convenient % mkdir examples % ftp iraf.noao.edu Connected to tucana.noao.edu. 220 tucana FTP server (SunOS, SAG's 28Mar89 version) ready. Name (iraf.noao.edu:seaman): anonymous 331 Guest login ok, send ident as password. Password: 230 Guest login ok, access restrictions apply. ftp> verbose Verbose mode off. ftp> cd iraf/docs ftp> get spp_examples.readme ftp> binary ftp> get spp_examples.tar.Z ftp> quit The angle brackets (<>) in the reply to the password prompt are meant to imply that the identifying password will not be echoed on your screen. The file spp_examples.readme contains a variation of the instructions that you are currently reading. If your local machine does not support anonymous ftp, alternate arrangements can be made. Please contact IRAF site support for help. The email addresses are iraf@noao.edu on the Internet and also (via a gateway) on Bitnet, 5355::IRAF on SPAN , and uunet!noao.edu!iraf via UUCP. The phone number for the IRAF hotline is 602-323- 4160. Assuming that you now have the distribution archive of the examples package, spp_examples.tar.Z, on your local machine, the files can be unpacked with commands such as: % cd examples % zcat ../spp_examples.tar.Z | tar -xpf - You might also have decided to download the archive file directly into the examples directory (or conversely, into /tmp), but placing it in the parent directory avoids having the file clutter up the directory listings illus- trated below and also makes recreating the package simpler if you want to start over. In any case, unpacking the archive should only take a few moments. Since the examples package is small, you can specify -v to the tar command if you want to see how the unpacking progresses. The examples package was archived without any binary executable or object files. IRAF external packages from programming groups both inside and outside of NOAO are typi- cally not distributed with binary files for any computer architecture. This is in contrast to the IRAF core system and noao packages which are supported directly by the IRAF group and which are distributed with pretested binaries for various host systems. In any case, if your computer is not configured for IRAF (or host) software development, it is best that you find out now while trying to build examples. A single copy of IRAF can support multiple host system architectures, for instance, a Sun 4 fileserver may support a number of Sun 3 diskless nodes with an NFS mounted copy of IRAF. This applies to IRAF external packages as well as to the core system of IRAF. The examples package is distri- buted with hooks for supporting the various types of Sun computer architectures and floating point options, specifi- cally Sparc, i386, f68881, and ffpa (the last two are float- ing point options for the Sun 3 mc68020 architecture). The following instructions will assume a Sparc host system, but the steps would be similar for any of the other architec- tures. At this point, a directory listing should show these files and subdirectories: % ls bin bin.sparc examples.hd lib bin.f68881 doc examples.men mkpkg bin.generic examples.cl examples.par src If your directory does not look like this, you will have to determine whether the ftp download or the zcat unpacking are at fault before continuing. To standardize the remainder of the commands for this section and to avoid any distracting host dependent com- mands, we will get into the IRAF CL before continuing. First you will need to utter a few magic incantations to get the subsequent commands to work properly: % setenv iraf iraf_path/ % source $iraf/unix/hlib/irafuser.csh Where iraf_path should be substituted with the full Unix pathname of the root directory of the IRAF directory tree. Do not forget the trailing slash, /, on the definition of iraf. IRAF, itself, is smart enough to figure out such site specific information as where it lives on your computer's filesystem. Recall, however, that the IRAF compiler and other programming tools are host level programs. On a typi- cal Unix system, the two commands above serve to supply suf- ficient information to the programming tools to let them do their job. The C-shell script irafuser.csh contains a number of site specific environment variable declarations. Con- versely, on a VMS system this information was made globally available as part of the IRAF system installation by your system manager. In either case, this detailed information is only needed for IRAF software development, not for simply running IRAF. It is most convenient to put the two commands above into your .login file so that they will be automati- cally executed the next time you log onto the computer. Folks who aren't running the C-shell will need to make alternate arrangements. One final bit of magic specific to the examples package is: % setenv examples examples_path/ Where examples_path should be substituted with the Unix pathname of the directory into which the package was unpacked. Again, do not forget the trailing /. The reason- ing behind this magic will be revealed a little later. At this point you should get into IRAF in whatever way you usu- ally do so. The rest of us will wait for you... ...ok, are you now waiting with bated breath at a cl> prompt? Let's continue. One side affect of the magic setenv command is to provide an IRAF logical directory to which you can now cd: cl> cd examples The IRAF mkpkg facility is used to maintain all but the simplest of SPP programs as described in s4. We will make use of some of the standard capabilities of mkpkg. First, we should verify for which of the available software development architectures the package happens to be config- ured: cl> mkpkg arch system is configured for generic The generic architecture is correct for any external package that is not currently being worked on, and certainly for any external package fresh from an archive. We are building the package under the Sparc architecture. The com- mand to configure the package for this is: cl> mkpkg sparc delete any dreg .e files left lying about in the source directories archive and delete generic objects restore archived sparc objects no object archive found; full sysgen will be needed The meaning of these messages will be discussed below, but if you see a message such as: Warning: IRAFARCH is still set in your environment to f68881 you are running IRAF on a non-Sparc computer (in this case, a Sun 3) and will either have to log off and find a dif- ferent computer, or will have to substitute f68881 (or what- ever) for sparc wherever necessary. A few additional hints for building the package on a non-Sun computer are included at the end of this section (s7.1). You should now be ready to rebuild the entire package by simply typing: cl> mkpkg -p examples >& SPOOL & [1] The output and error messages are redirected into the file SPOOL for later review. Even a small IRAF package such as examples may generate hundreds of lines of messages as it is being compiled, linked, and installed. We put the command into the background so that you can go about your business for the few moments that the package will take to compile and link. A handy Unix trick that you may want to use to monitor the progress of the mkpkg is to tail the spool file as it grows: cl> !tail -f SPOOL This trick will grow in utility as your package grows. You can escape from the tail command at any point by typing ^C (control-C). When mkpkg is finished you should see a message similar to: [1] done 60.2 2:20 42%. At this point you should review the summary of the spooled mkpkg and compiler mes- sages: cl> mkpkg summary spool=SPOOL warning: library `libpkg.a' not found ranlib libpkg.a Updated 20 files in libpkg.a move `xx_examples.e' to `examplesbin$x_examples.e' This is a rather Spartan summary in which messages matching a variety of character templates are simply discarded as uninteresting. In this case, the warning message merely indicates that you are rebuilding the package from a version that has been stripped of binaries and so there is no previ- ous copy of the package library file, libpkg.a, to search for outdated compiled object files. The ranlib message is a bit of host dependent magic that you should never have to think about. We are next told that 20 files have been updated (or simply added) in the package library file. These files were scrounged from the src directory and from its asttools and airmass subdirectories. The final message tells us that the package executable has been installed in a package bin directory, specifically bin.sparc since we ear- lier executed a mkpkg sparc. If any of these steps malfunctioned for whatever rea- son, you would see an error message (not just a warning). If any error messages appear that you don't understand, you should first review the full spool file to see if that sheds any light on the problem: cl> page SPOOL The next step in tracking down problems in building the package would be to run through the directions in this sec- tion from the top, carefully verifying each. If that does not help then you (or your system manager) need to consider whether there is some problem with the host system compilers or libraries on the computer. For instance, does the computer even have Fortran and/or C compilers? Assuming you made it past the mkpkg, you are almost done. All that remains is to grant yourself access to the newly retrieved, unpacked, and compiled package. This only requires that you define the package script as an IRAF task: cl> task examples = examples$examples.cl At this point, you can now load the examples package: cl> examples fibonnaci hello impix imreplace1 imreplace2 pairmass and execute a task: ex> hello Hello, world! and do anything with the package (almost) that you can do with other packages and tasks: ex> lpar imreplace2 input = List of input images output = List of output images (value = 0.) Constant for the replacement operation (lower = INDEF) Lower limit of the replacement window (upper = INDEF) Upper limit of the replacement window (mode = "ql") At this point you are all set to run the examples pack- age, at least until you log out and back in again. You still need to define the package in such a way that it is automatically available when you log into IRAF. There are two ways to do this. The first way is to edit the task statement for the package into your login.cl, or better yet, your loginuser.cl file. The other requirement for this to work is to define examples in the IRAF environment, not in the Unix environment as you did in the bit of magic above: set examples = examples_path/ task examples = examples$examples.cl Note that examples_path can now be specified as an IRAF vir- tual pathname. The two commands should be placed before the keep statement in either IRAF login file. When you next log into IRAF, the examples package should be available to you. It was indicated above that examples was almost ready to be used in all normal IRAF ways. The one missing piece is access to the package's help pages. This brings us to the second, politically correct, way to install an external package into IRAF. The connection between the main IRAF system and each of a particular site's external packages is contained in the file hlib$extern.pkg. All knowledge neces- sary to access the external packages is limited to that file. This consists of the two items that you were told to add to your loginuser.cl file (the examples environment variable and the task statement), but also the hook that allows the IRAF help command to find your new package's help pages. A more fundamental reason to install your package this way is that it allows other folks to use the package, too. The template extern.pkg from the hlib$ directory of a fresh IRAF installation looks like: # External (non core-system) packages. To install a new package, add the # two statements to define the package root directory and package task, # then add the package helpdb to the `helpdb' list. reset noao = iraf$noao/ task noao.pkg = noao$noao.cl #reset local = iraf$local/ #task local.pkg = local$local.cl reset helpdb = "lib$helpdb.mip\ ,noao$lib/helpdb.mip\ # ,local$lib/helpdb.mip\ " keep The commented out statements for the local package are meant to serve as an example when adding hooks for a new external package. Your site's IRAF system manager can simply copy and edit the lines to fully install the examples package for all users: # External (non core-system) packages. To install a new package, add the # two statements to define the package root directory and package task, # then add the package helpdb to the `helpdb' list. reset noao = iraf$noao/ task noao.pkg = noao$noao.cl reset examples = examples_path task examples.pkg = examples$examples.cl #reset local = iraf$local/ #task local.pkg = local$local.cl reset helpdb = "lib$helpdb.mip\ ,noao$lib/helpdb.mip\ ,examples$lib/helpdb.mip\ # ,local$lib/helpdb.mip\ " keep This then is the explanation for the setenv examples magic with which we conjured above. We needed to enter the examples variable into the Unix environment, not just into the IRAF environment, to define it for mkpkg, not for run- ning the package. However, by defining the variable in extern.pkg, we have solved both problems at the same time. One last bit of business will conclude building the Sparc version of the package's binaries: cl> mkpkg generic delete any dreg .e files left lying about in the source directories archive and delete sparc objects compress bin.sparc/OBJS.arc [1] 12697 restore archived generic objects no object archive found; full sysgen will be needed Warning: IRAFARCH is still set in your environment to sparc The basic result of all this is to confine all the architec- ture dependent files from the Sparc software development to the bin.sparc directory. The initial delete any dreg .e message tells you that if a previous attempt to link the package failed for some reason, any resulting garbage exe- cutable files will be cleaned up. Another way to leave an executable laying about is to execute mkpkg from other than the root directory of an external package, for instance typ- ing mkpkg -p examples in the examples$src subdirectory will compile any out-of-date source files and relink the package, but will not install the executable in the appropriate bin directory, but rather leave it in the src directory under the name xx_examples.e. The archive and delete and compress messages indicate that all of the Sparc architecture libraries and individual object files will be archived into a compressed tar format file names OBJS.arc.Z in the bin.sparc directory. This will be unpacked by mkpkg the next time you need to update the package for your Sparc machines. The restore archived generic objects and no object archive found messages just represent the whole point of the generic pseudo-architecture to provide a neutral configura- tion for external packages. The final Warning message is meant to alert you that the IRAF and the host system are not currently configured to build the newly selected architec- ture. This does not mean anything for the generic case, but is a very important issue if you are building multiple ver- sions of the package on the same computer. Finally, you were promised some hints for installing the package on computers other than Suns. Most of the host system dependencies on software development are hidden within IRAF, which is after all one of the reasons you are likely to be interested in programming in SPP. Details such as the libraries that are required by the host compilers and the host's particular floating point format are largely hid- den from you, and those that aren't are parametrized in a machine dependent header file such as hlib$mach.h just in case you need to know. You will, however, need to keep track of the specific architectures of the machines on your local network. If you have a fileserver that supports IRAF on client machines with varying architectures, you will need to have an appropriately named bin subdirectory for each architecture. You will also need to modify the file examples$mkpkg to include a module for each architecture. Entries supporting software development on an Ultrix DECsta- tion and a Mips might be: dsux: # DECstation/Ultrix binaries $verbose off $set DIRS = "lib src" !$(hlib)/mkfloat.csh dsux -d $(DIRS) ; mips: # install mips binaries $verbose off $set DIRS = "lib src" !$(hlib)/mkfloat.csh mips -d $(DIRS) ; The corresponding bin directories would be bin.dsux and bin.mips. It is your responsibility to guarantee that the host compiler knows for which architecture you are compiling the package. On a Sun 3, for instance, you may need to set FLOAT_OPTION in your environment to distinguish between the 68881 and FPA floating point options. 7.2. Adding a Task to the Package Now that you have acquired your own copy of the exam- ples package, we will discuss how to add your own tasks to the package. Let's say that you want to add the task howdy to the package. The SPP source code for the task is con- tained in the file, t_howdy.x, and consists of the following variation on the "Hello, world!" theme: # HOWDY -- Variation on HELLO. procedure t_howdy () pointer howdy, sp begin call smark (sp) call salloc (howdy, SZ_LINE, TY_CHAR) call clgstr ("howdy", Memc[howdy], SZ_LINE) call printf ("%s\n") call pargstr (Memc[howdy]) call sfree (sp) end Howdy will prompt the user for the string value of the howdy parameter (unless it is specified on the command line) and will then print that string out. The task has a corresponding one line parameter file, howdy.par: howdy,s,a,,,,Text string to be echoed The first step is to copy these two files into the examples$src/ directory. Next a few files must be edited to fully install the task. Let's finish with the src/ directory before moving on. First the SPP task statement must be edited into the file x_examples.x and the mkpkg file must be modified to compile and link the object code for t_howdy.x. Determining the precise changes that are needed is left as an exercise for the reader. These two changes take care of actually linking the new SPP task into the package executable. There are potentially four files that you may need to change in the examples$ directory itself. These are examples.cl to add the CL task statement declaring the task for the user, examples.par to update the version timestamp for the package, examples.hd and examples.men to add a help file for the task. Writing a help page is always a good idea. The mkmanpage task in the softools package will pro- vide a blank help page for you to edit. The mkhelpdb task compiles the information in the helpdb.hd file into the machine independent binary file, helpdb.mip: cl> cd examples cl> edit helpdb.hd cl> edit helpdb.men cl> softools so> cd doc so> mkmanpage softools so> cd ../lib so> mkhelpdb root.hd helpdb.mip To actually update the package's binary executable, a sequence of commands such as the following will be needed. This assumes that the package has been installed in the file hlib$extern.pkg. cl> cd examples cl> mkpkg sparc cl> mkpkg -p examples cl> mkpkg generic More complicated tasks may, of course, have many more files associated with them such .h header files, cursor keystroke help files, and multiple source code files. As general advice, if a task requires more than a couple of such files then you should create a subdirectory to contain the selection of files for the task. Consult the instruc- tions in s5 and in s7.1 for more hints.