FTOOLS Home

Sub-package Development

Software development using the underlying principles of FTOOLS may be integrated into the FTOOLS package as a new sub-package. As an example, consider the hypothetical sub-package named mytools to be added to the existing FTOOLS package and supported under the Host and IRAF environments. Begin by making a new directory under the ftools/ directory, at the same level as the subdirectories for the heasarc and futils sub-packages.

>cd ~ftools/ftools/
>mkdir mytools

Make the mytools/ subdirectory the current work directory.

>cd mytools

This directory will require the same subdirectory and IRAF files as the heasarc/ and futils subdirectories. They are the doc/, help/, host/, lib/ and src/. In addition, the IRAF specific files mytools.cl, mytools.hd, mytools.men and mytools.par must be placed in this directory. To help illustrate the contents of these directories and files consider the fdummyftool task developed in the earlier sections to be a task destined to exist in the mytools sub-package of FTOOLS. Then under the src/ subdirectory, one would make a subdirectory named fdummyftool/ containing all the files discussed previously. Also, the src subdirectory will contain the files for the sub-package main x_mytools.x and the build file mkpkg for the subpackage's libpkg.a file. Begin by making the subdirectories under mytools.

>mkdir doc help host lib src

Move into the src/ subdirectory and make the fdummyftool/ subdirectory.

>cd src
>mkdir fdummyftool

Place all the source files associated with the fdummyftool task in this fdummyftool/ subdirectory(see previous sections). It would be a very good idea to look at the equivalent files under either the asca, caltools, fimage, futils, gro, heasarc, rosat, time, vela5b, or xte packages while creating these files, paying careful attention to the the tabs and newlines. Now change to the mytools/doc/ subdirectory and place the IRAF help file fdummyftool.hlp this directory. Now move back to the src/ directory and create a file named x_mytools.x containing the following:

x_mytools.x

  # MyTools package
  task fdummyftool

Be sure that the the last line has a newline character at the end. The IRAF mkpkg file must also be created in this directory:

mkpkg

  # IRAF mkpkg for the MyTools package
  $call relink
  $exit
  update:
       $call relink
       $call install
       ;
  relink:
       $set     LIBS = "-lftools -lfitsio"
       $update  libpkg.a
       $omake   x_mytools.x
       $link    x_mytools.o libpkg.a $(LIBS) -o xx_mytools.e
       ;
  install:
       # Install executable in BIN directory for current architecture.
       $move xx_mytools.e ftoolsbin$x_mytools.e
       # Install pfile if master copy has changed.
       $ifolder (mytools$fdummyftool.par, fdummyftool/fdummyftool.par)
       $copy fdummyftool/fdummyftool.par mytools$fdummyftool.par $endif
       ;
  libpkg.a:
       @fdummyftool
       ;

Now make the current directory the mytools subpackage's directory, just one level up. An IRAF mkpkg file will also be needed at this level. Copy a mkpkg file from either the asca, caltools, fimage, futils, gro, heasarc, rosat, time or xte subpackage to use as a template for the mytools sub-package.

>cd ..
>cp ~ftools/ftools/heasarc/mkpkg .

Edit this copy of the mkpkg file in the mytools directory and replace all occurrences of heasarc with mytools then save the file.

At this point the lib/ subdirectory should be populated with all the IRAF related files. Begin by making the lib/ subdirectory the current directory:

>cd lib

Now copy all the files from either the ../../heasarc/lib/ or ../../futils/lib/ directory into this directory. I'll assume that you take the files from the heasarc subpackage in the following discussion.

>cp ../../heasarc/lib/* .

Rename the rootheasarc.hd and the strip.heasarc files to rootmytools.hd and strip.mytools. Now edit the following list of files and change all occurrences of heasarc to mytools:

• rootmytools.hd
• strip.mytools
• root.hd
• zzsetenv.def

Many of the files found in this directory are not needed by a subpackage but are needed by a independent package. The implementation of a package will not be covered here but I recommend leaving the files just in case. From here I would suggest finishing up the IRAF file found in this subpackage by first moving up a directory and then creating the mytools.cl, mytools.hd, mytools.men and mytools.par files. Once again I recommend a close look at the sister files found in one of the other subpackages while creating these files.

>cd ../

Begin with the mytools.cl file:

mytools.cl

  # Package script task for the MyTools package.
  print("")
  print("Welcome to the MyTools Sub-Package")
  print("")
  cl < "mytools$lib/zzsetenv.def"
  package mytools, bin = ftoolsbin$
  task mytools = "mytools$x_mytools.e"
  clbye()

Next create the mytools.hd file:

mytools.hd

  # Help directory for the Heasarc package.
  $doc = "./doc/"
  fdummyftool hlp=doc$fdummyftool.hlp, src=mytools$src/fdummyftool/fdummyftool.f

Now for the mytools.men file:

mytools.men

  fdummyftool - Simple demonstration task

Finally, the mytools.par file:

mytools.par

  # MyTools parameter
  version,s,h,"24Feb93"

This completes the IRAF related subpackage structure that is local to the subpackage. The next step is to create the Host related make files that are located in the host subdirectory:

>cd host

Here you will create two files, Makefile for Unix and make.com for VMS. Start with the Unix Makefile.

Makefile

  # This Makefile is for building the Host Interface tasks
  # SYSTEM DEPENDENT FORTRAN LIBRARY LINKS
  # SUN with the version SC1.0 FORTRAN
  #LIBSYS=-L/usr/lang/SC1.0 -lF77 -lm
  # SUN with the version SC0.0 FORTRAN
  #LIBSYS=-L/usr/lang/SC0.0 -lF77 -lm
  # DEC with the new DEC FORTRAN
  LIBSYS=-L/usr/lib -lUfor -lfor -lutil -li -lots -lm
  # DEC with the MIPS RISC FORTRAN
  #LIBSYS=-L/usr/lib/cmplrs/f77 -lI77 -lF77 -lm
  # For Alphas running OSF
  #LIBSYS=-L/usr/lib -ldnet_stub -lUfor -lfor -lFutil -lm -lots -lc
  TASKS = fdummyftool
  all : ${TASKS} help
  ${TASKS} :
       cd ../src/$@; make install "LIB_FTOOLS=$(LIBSYS)"
  help :
       cp ../help/*.txt ../../help/.
  perl :
       cd ../perl.scripts; make install

One note about the Makefile above. It assumes a DECstation using the new DEC FORTRAN compiler. You should be sure that the libraries associated with your system are used by only uncommenting the macro LIBSYS for you machine and compiler. In addition you may need to add your own if the machine you are developing on is not shown. The make.com file is for VMS builds.

make.com

  $! Command file is for building the Host Interface tasks
  $!
  $set def ftools:[mytools.src.fdummyftool]
  $@make
  $!
  $copy ftools:[mytools.help]*.txt ftools:[help]*.*
  $!
  $ exit

Except for generating the Host help file(s) for the subpackage task(s) found in the help/ directory, this completes the changes to the mytools subpackage. The remaining changes are to the top level ftools package. These changes are to inform the ftools package about the new mytools subpackage. Change to the top level directory ~ftools/ftools/:

cd ~ftools/ftools

The following files must be edited to provide information on the new mytools subpackage:

• ftools.cl
• ftools.hd
• ftools.men
• mkpkg

In the ftools.cl file, add the following line just above the line containing clbye():

task mytools = "mytools$mytools.cl"

In the ftools.hd file, add the following line to the first section of the file:

$mytools = "./mytools/"

and the following lines at the bottom of the file:

mytools         men = mytools$mytools.men,
                hlp = ..,
                sys = mytools$mytools.hlp,
                pkg = mytools$mytools.hd,
                src = mytools$mytools.cl

Next, in the ftools.men file, add a line in the file like this:

mytools - My own ftools package

Finally, make the following changes to the mkpkg file found at this level in the ftools package. Begin by adding the following line to the relink: dependency near the top of the file:

$call mytools

Next add the following line to the update: dependency a few lines down in the file:

$call mytools

Then underneath the heasarc: dependency, add a dependency for mytools: as follows:

  mytools:
         $echo "========== MYTOOLS =========="
         $echo "+" $echo "+"
         $call update@mytools
         $echo "+" $echo "+"
         ;

These files will need to be edited under the lib/ subdirectory:

• strip.ftools
• zzsetenv.def

In the strip.ftools file add the following line under the assignments for the other subpackages:

mytools -allbut .hlp .hd .men .cl .par .key .dat .mip .fits

And in the zzsetenv.def file add the line just above the last line:

set mytools = "ftools$mytools/"

In addition these files will need to be edited under the host/ subdirectory:

• make.packages
• makepackages.com

In the make.packages file, simply append mytools to the WHICHPKG macro definition. Then add the following lines to the makepackages.com file just above the $exit:

  $!mytools :
     $set def ftools:[mytools.host]
     $@make

The new subpackage is now ready to be integrated into the ftools package. Proceed by building the IRAF version of the new subpackage first. Move to the top level directory in the FTOOLS package and run the mkpkg utility:

>cd ~ftools/ftools/
>mkpkg -p ftools

Assuming all goes well, the next step is to rebuild the IRAF help database and the Host help files. Start up an IRAF session from an account with read/write access to the FTOOLS software. (See the " Installation Guide" for details).

>cd ~ftools/iraf/
>cl

Move to the ~ftools/ftools/lib/ subdirectory and load the IRAF softools package:

cl>cd ~ftools/ftools/lib/
cl>softools

Now rebuild the IRAF help database:

so>mkhelpdb root.hd helpdb.mip

You will need to restart this IRAF session by logging out and then back in. Do so at this time. Now move to the new subpackage's help subdirectory and load the FTOOLS package and then the mytools subpackage:

cl>cd ~ftools/ftools/mytools/help/
cl>ftools
ft>mytools

Finally, generate the fdummyftool.txt file for the Host help facility:

my>help fdummyftool > fdummyftool.txt

Now end the IRAF session and prepare to build the Host version of the mytools subpackage. Move to the ~ftools/ftools/host/ subdirectory:

>cd ~ftools/ftools/host/

Edit the make.packages file found here. Add mytools to the WHICHPKG make variable found at the top. Now you can build just the FTOOLS distribution by

>make arch=machine

where machine is the appropriate machine platform you are developing on. The current list of supported machines is listed in the top comments of the Makefile found in this directory.

If all has gone well this completes the development of the mytools subpackage containing the single task fdummyftool under the FTOOLS software package development paradigm!

FTOOLS Home