Download and Installation Guide


Contents:

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 and Apple MacOS X systems. The latter implementation is rather new, so it is possible that not everything will work as expected.

Below is a list of requirements to install and run GIPSY on one of the above systems. Please note that depending on the operating system distribution, some software may already be provided and other software can be installed from repositories belonging to that distribution. In those cases there is no need to download and install it manually. Separate pages with preparation instructions are available for Ubuntu, Fedora and Mac OS X.

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 (i.e., the complete standard installation) can be performed automatically by the script gipsy_install.csh. 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. In this directory the procedure also creates a file "install.log" which can be consulted in case of problems. Hint: use the following command for a quick look:
grep "compile --" install.log | more
(warnings about bookkeeper insertions can be ignored)

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.

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

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 header 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:
  1. 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.
  2. 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.
  3. 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
    
  4. 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.
  5. 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.
  1. 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.
  2. 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.
  3. Then check whether you have made the necessary modifications to the setup files.
  4. Check whether you have the lock daemon running on your system. If not, ask your system manager to start it.
  5. 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
  6. Scisoft OSX is known to interfere with the installation of GIPSY's Python binding and the Kapteyn Package. Before installation, you may have to disable the setup of Scisoft in your startup file (e.g. ~/.cshrc, .profile) by commenting it out.
  7. 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


COPYRIGHT © 1999-2011
Kapteyn Institute, University of Groningen, The Netherlands
All Rights Reserved.


GIPSY