Download and Installation Guide

Requirements
Download the source
Installation step 1: Clients file
Installation step 2: Compiler setup
Installation step 3: Building the sources
Installation step 4: Local system setup
Installation step 5: Set the environment
Post Installation: GIPSY html documentation
Post Installation: Regular updates
Post Installation: Troubleshooting
GIPSY documentation (.doc) files
GIPSY references

Requirements

This document describes how to install GIPSY on one or more machines. Currently GIPSY is only fully supported on reasonably up to date Linux systems and on Apple MacOS X systems. The latter implementation is rather new, so it is possible that not everything will work as expected. In case of problems, it may be useful to consult this contributed document.

Some requirements to install and run GIPSY on one of the above systems are:

An ANSI C- and Fortran compiler and development libraries. Setups are currently available for gfortran and for g77. See:http://gcc.gnu.org/fortran/.
The X11, Xt and Xaw3d libraries with include files. Instead of Xaw3d, the "flat" Xaw widget set can also be used. Then "Xaw3d" has to be changed into "Xaw" in the setup file (see below).
The availability of one of the shells csh or tcsh is required. The login shell of the account where the GIPSY sources and executables reside, is preferably one of those shells.
The curses library with include files.
Python 2.4 or higher and NumPy, both with include files. Without these, installation will succeed but tasks written in Python cannot be run. Most supported distributions contain Python. Otherwise look here: http://www.python.org/. For NumPy: http://numpy.scipy.org/
VTK and VTK-Python with include files. Without these, installation will succeed but tasks depending on VTK (currently only VTKVOLUME) cannot be run. See: http://www.vtk.org/.
The Python package "kapteyn". This package is not part of the GIPSY distribution but must be downloaded and installed separately. Without it, installation will succeed but tasks which depend on it (SKYCALC, MAPMAKER) cannot be run. See: http://www.astro.rug.nl/software/kapteyn/. The package may be installed afterwards, just like the following Python packages and modules.
The Python package "PyFITS" from the Space Telescope Science Institute. Without it, installation will succeed but tasks which depend on it (FITSREAD, MAPMAKER) cannot be run. See: http://www.stsci.edu/resources/software_hardware/pyfits.
The Python package "matplotlib". Without it, installation will succeed but tasks which depend on it (currently only MAPMAKER) cannot be run. See: http://matplotlib.sourceforge.net/.
To use GIPSY's old display server GIDS, an 8 bit PseudoColor default visual is required. Linux users with a different default colour depth can start their X-server with: startx -- -bpp 8 (More information here.) It is also recommended that the X-server's backing store is switched on. (For XFree86: Option "BackingStore" in Section "Device") If both vncserver and vncviewer are available, another possibility would be setting up a virtual 8-bit X server and use that for GIDS. How this can be done is explained in a separate page.

GIPSY is also known to work (or have worked) on the systems of which setup sections can be found in the file sys/legacy-setup.mgr in GIPSY's distribution. Because our institute doesn't have access to any of these systems anymore, nothing can be guaranteed, but in case of problems we are always willing to help.

Step 0: Download the source

(NOTE: This step and the following installation steps 1-3 can automatically be performed by the script gipsy_install.csh. This simple experimental script has been tested on both 32-bit and 64-bit Linux but may also work for MacOS. It uses wget for downloading the source. To use it, first make it executable with "chmod +x gipsy_install.csh" and then run it with "./gipsy_install.csh". It asks for the directory where to install GIPSY.)

First create a directory gipsy in the tree where you want to keep the GIPSY source files. It is advisable to create a user gipsy, but this is not really necessary. When you have a user gipsy on your system, the GIPSY root directory should be the HOME directory. Do not install GIPSY as root to avoid problems with ownership of downloaded files.

Go to the GIPSY root directory and type:
```
        setenv gip_root `\pwd`
```

Prepare to download the (daily updated) tar file:

        cd $gip_root
        mkdir import
        cd import
        mkdir src
        cd src

Download gipsy_src.tar.gz with your browser or use the download alternative below:

Download alternative:

        ftp ftp.astro.rug.nl
        Name: anonymous
        Password: your email address
        ftp> cd gipsy
        ftp> cd src
        ftp> bin
        ftp> get gipsy_src.tar.gz
        ftp> quit

Unpack the sources in the gipsy root directory with commands:

        cd ../..
        gunzip < import/src/gipsy_src.tar.gz | tar xvf -

You will end up with a GIPSY directory tree with the following subdirectories:

dat Data for colour look up tables etc.
mis Storage of (bug) reports and news items.
sys Shell scripts for installing and running GIPSY.
doc Description of scripts and other basic documentation.
inc Source code: include files.
sub Source code: subroutines.
tsk Source code: tasks.

Installation step 1: Clients file

Go to the GIPSY system directory with:

        cd $gip_root/sys

You are now in the directory which contains all the GIPSY system files. Make the current host a GIPSY client with:

        ./mkclient.csh  <number>

<number> denotes the GIPSY client mode and should be one of the following:

<number>            What GIPSY client may/can do
              RUN COMPILE INSTALL SUID GLOCK NOOLD REMOTE GFTP LINK
    65         +1                                     +64           =  65
    71         +1     +2      +4                      +64           =  71
   103         +1     +2      +4               +32    +64           = 103
   199         +1     +2      +4                      +64 +128      = 199
   231         +1     +2      +4               +32    +64 +128      = 231
   487         +1     +2      +4               +32    +64 +128 +256 = 487

It should be 71 or 103 if you obtained the sources and you want to compile them or 65 if you also obtained the executables and don't want to compile them yourself.
If you are going to compile the GIPSY sources, including the number 32 (NOOLD, number=103) prevents any old executables to be saved for at least a week.
If your machine does not allow set owner and set group ID on the disk where the GIPSY sources are stored, you may have to add 8 to the GIPSY client code.

The mkclient.csh script creates an entry in the clients file, which resides in $gip_root/loc. The modified file is in the current directory and is called clients.new. You should check this file and if necessary, modify it. Usually the fields which are modified are the paths to the GIPSY exe, lib and tmp directories.

A description of the clients file and the mkclient.csh script can be found in $gip_root/doc/clients.doc and $gip_root/doc/mkclient.doc resp. After inspecting and/or modifying the file client.new type:

        mv clients.new $gip_root/loc/clients

Next type:

        source cshrc.csh

This should define the necessary environment variables. A description can be found in $gip_root/doc/cshrc.doc.

Installation step 2: Compiler setup

The next step is to create the setup file for the compilers in the $gip_loc directory ($gip_loc is defined as $gip_root/loc by the gipenv.csh script). You can check the $gip_sys/setup.mgr file for entries which match your local situation. Now copy the file with:

        cd $gip_loc
        cp $gip_sys/setup.mgr setup

For standard installations, usually no editing is necessary. Otherwise, delete all the lines that are not relevant and do NOT delete the last (comment) line! (see also $gip_doc/setup.doc).

Next we have to compile the compile program, the file extractor, the Fortran to C interface program, the GIPSY lock server, the Sheltran compiler, the GIPSY file transporter and install the fonts for PGPLOT. This can be done with the install script. This script will check whether the necessary directories are present and create them if possible and necessary. In principle only the system dependent directories will be created. In order to run install type

        cd $gip_sys
        ./install.csh

If it complains, then probably some variables are not yet set, and running install again might provide the solution. See $gip_doc/install.doc for a description. Note that the install script tries to send a mail with registration information to the GIPSY server. If you don't want that, then comment out the calls to 'register.sh' in the scripts 'install.csh' and 'gipsy.csh' (both in $gip_sys).

Installation step 3: Building the sources

Now you have to build the GIPSY library and the GIPSY applications. Type:

        cd $gip_sys
        ./mkbookkeeper.csh
        mv bookkeeper.new bookkeeper

If you have the ftp bit on in $gip_loc/clients (bit 8), turn it off by subtracting 128 from field 3 in $gip_loc/clients. Next type:

        p -update > & p.log &

This will generate the GIPSY library and the GIPSY applications. It is the most time consuming part of the installation. Use command: tail p.log to check the compilation.

Note that when you kill 'p' there might be some lock files which will not allow 'p' to be restarted. You will have to remove the lock files by typing:

        rm -f $gip_sys/.*lock $gip_sys/*.lock $gip_tmp/update.lock

You should inspect the log file p.log for any errors. If there are any, try to find out what caused them. If you can't solve the problem by adjusting setup parameters or installing missing software components, such as libraries or include files, you can contact the GIPSY manager at Groningen (gipsy@astro.rug.nl).

If you have VTK-Python, then as the last step the Ggi-VTK interface module needs to be rebuilt:

        p -rebuild ggivtk.src

This is necessary because the installation procedure usually generates an incomplete module. This is due to the fact that ggivtk depends on GIPSY's Python module which may not have been built yet at the time ggivtk was built for the first time.

Installation step 4: Local system setup

In order to get the system running properly, you may have to edit the following setup files in the $gip_loc directory:

        File                Purpose                              Documentation

        grdevices           Contains info about graphics devices $gip_doc/grdevices.doc
        lpdevices           Contains info about text printers    $gip_doc/lpdevices.doc
        mtdevices           Contains info about tape units       $gip_doc/mtdevices.doc
        tvdevices           Contains info about X11 servers      $gip_doc/tvdevices.doc

Installation step 5: Set the environment

Each user who wants to use gipsy has to put the following lines into his or her .cshrc file:

        setenv gip_root <PATH_TO_GIPSY_ROOT_DIRECTORY>
        source $gip_root/sys/gipenv.csh

Also inspect cshrc.csh to find out whether your system needs some special setings. If so, incorporate them into your .cshrc.

(Optional) Post Installation: GIPSY html documentation

GIPSY documentation is found on the home page of the Groningen Image Processing SYstem. This documentation can also be installed on your local system. The file GIPSY_HTML.tar.gz contains GIPSY's html documentation. To install it on your system, do the following:

Check whether $gip_htm is defined. If not, (e.g. you want to install the documentation on an older, existing, GIPSY installation), your GIPSY version is too old and you should get an update.
Check whether the directory $gip_root/htm exists. If not, change directory to $gip_sys and run the install script:
```
     cd $gip_sys
      ./install.csh
```
This should create the directory. Then (for the second time) type:
```
     ./install.csh
```
This creates some necessary links.

Obtain GIPSY_HTML.tar.gz with your browser or use anonymous ftp:

      cd $gip_root
      ftp ftp.astro.rug.nl
      Name: anonymous
      Password: your e-mail address
      ftp> cd gipsy
      ftp> binary
      ftp> get GIPSY_HTML.tar.gz
      ftp> quit

Unpack the html documentation archive in directory $gip_htm:
```
      cd $gip_root/htm
      gunzip < ../GIPSY_HTML.tar.gz | tar xvf - 
```
Now GIPSY should be able to access the local html documentation. The message "... Access via Internet" when starting a Web browser from Hermes (ESC-X) should not appear anymore.
When everyting is OK, GIPSY_HTML.tar.gz can be deleted:
```
      rm $gip_root/GIPSY_HTML.tar.gz
```

The html documentation is not yet automatically updated. To get the latest version, repeat steps 3 through 5. The file GIPSY_HTML.tar.gz on our server is currently refreshed daily.

Post installation: Regular updates

If you want to obtain regular updates of sources via gftp you should turn on the gftp bit (bit 8) in the $gip_loc/clients file. Just add 128 to the number supplied to mkclient.csh. (e.g. 71 becomes 199 and 103 becomes 231). Then you can run p -update or the update.csh script in $gip_sys whenever suitable. You can also run update.csh automatically at regular intervals (1 week, maybe 1 day) by using the atqueue.csh script or cron. You may need to get permission to use at or cron. See the document in $gip_doc/atqueue.doc. If you have permission to use cron, you should use cron. An example cron command would be:

        0 2 * * * /bin/csh /tha3/users/gipsy/sys/update.csh

for updating every day at 200 am, or

        0 22 * * 2 /bin/csh /zia/u/gipsy/gipsy/sys/update.csh

for updating every week at tuesday 2200 pm.

Post Installation: Troubleshooting

You may run into problems installing, running or compiling GIPSY. Here are some things to check first before contacting the GIPSY group in Groningen.

Check whether you have the correct version of the operating system and the compilers mentioned above. You may have to make small modifications to $gip_loc/setup to enable correct compiling.
Check whether you have initialized the gipsy environment in your .cshrc file. Each user must have the following statement in his/her .cshrc file:
```
      setenv gip_root 
      source $gip_root/sys/gipenv.csh
```
Also inspect $gip_sys/cshrc.csh for any other system specific settings.
Then check whether you have made the necessary modifications to the setup files.
Check whether you have the lock daemon running on your system. If not, ask your system manager to start it.
When you are running olwm, you might have to modify the .Xdefaults file in your HOME directory to enable keyboard focus on the GIDS window. Add the following line: OpenWindows.FocusLenience: True
If you still have problems, you can contact the GIPSY manager at Groningen: gipsy@astro.rug.nl.

GIPSY documentation (.doc) files

Additional documentation is stored in the GIPSY documents (doc) directory.

GIPSY references

The Groningen Image Processing SYstem GIPSY,
J.M. van der Hulst, J.P. Terlouw, K. Begeman and W. Zwitser, in Astronomical Data Analysis Software and Systems I, ed. D.M. Worall, C. Biemesderfer and J. Barnes, ASP Conf. series no. 25, p. 131.
The Evolution of GIPSY, or the Survival of an Image Processing System,
M.G.R. Vogelaar and J.P. Terlouw, in: Astronomical Data Analysis Software and Systems X, ed. F.A. Primini, F.R. Harnden, Jr., H.E. Payne, ASP Conf. series no. 25.
GIPSY manual (not up to date, 1992, but parts are still useable).

Download and Installation Guide

Contents: