Download and Installation Guide

Contents:

Requirements

This document describes how to install GIPSY Release 4.0 on one or more of the machines mentioned below. Only on these systems GIPSY is fully supported. They are: 
   GIPSY          operating            hardware
architecture       system    release    class         platform   processor type    

sol4                SunOS    5.6        sun4u          sparc     SUNW,UltraSPARC-IIi-Engine 
sol4                SunOS    5.7        sun4c          sparc     SUNW,Sun_4_65 
sun386i             SunOS    5.7        i86pc          i386      i86pc
sun4                SunOS    4.1.3      ....           ....
linux               linux    2.2.5      i86pc          ....      i86pc
hp9000s300          HP-UX    B.09.00    9000/300       ....      ....
hp9000s700_A.09.01  HP-UX    A.09.01    ....           ....      .... 
hp9000s700_B.10.01  HP-UX    B.10.01    ....           ....      .... 
hp9000s700_B.10.20  HP-UX    B.10.20    9000/780       ....      ....
aix                 AIX      3.2        IBM/RS6000     ....      .... 
sgi                 IRIX     4.0.5      ....           ....      .... 
convex              ConvexOS 10.0       ....           ....      .... 
alpha               OSF1     2.0        ....           ....      ....
The requirements to run GIPSY on one of the above systems are:

Download the source

First create a directory gipsy in the tree where you want to keep the GIPSY source files. It is advisable to ask your system manager to create a user gipsy, but 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`

You can now decide how to install GIPSY. You can either (1) obtain the source (gipsy-src.tar.gz) from anonymous ftp or install via the sysgen.csh script (2) which uses the gftp program (for your architecture). We usually follow procedure (1) to obtain and install the sources.

1) If you want to download tarred/gzipped GIPSY sources:

2) If you want to use the sysgen.csh script:
In either case (sysgen or tar file) you 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
The <number>should be 199, 231 or 487 if you used the sysgen.csh script.
It should be 71 or 103 if you obtained the sources from anonymous ftp or tape and you want to compile them or 65 if you also obtained the executables from anonymous ftp or tape and don't want to compile them yourself.
If you are going to compile the GIPSY sources you might want to add 32 to <number> if you don't want old executables 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 have to add 8 to the GIPSY client code. If your system supports symbolic links, you want to add 256 to save some space.

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.

Requirement: Note that these directories, exe, lib and tmp must be on the same disk partition.

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. You should also edit the .cshrc (or the .tcshrc) file to contain the following lines: 
        setenv gip_root 
        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.

This will ensure that the GIPSY environment is setup automatically each time you logon as GIPSY manager. You should try this by logging off and logging in again and check whether the GIPSY environment variables gip_root and gip_sys are correctly defined.

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. Copy the file to $gip_loc/setup and delete all the lines that are not relevant. Do NOT delete the last line! (see also $gip_doc/setup.doc). You also should create a manager file. A description can be found in $gip_doc/manager.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.

If you used the sysgen.csh script, or you want to obtain regular updates of GIPSY sources, you have to read $gip_doc/server.doc and check whether your machine can resolve the address of the GIPSY source server. If not, you must create a file 'server' in $gip_loc with the correct address of the GIPSY source server.


Installation step 3: Building the sources

Now you have to build the GIPSY library and the GIPSY applications. If you used the sysgen.csh script, you type 
        p -sysgen > & p.log &
This command will retrieve the GIPSY sources from the GIPSY source server and compile them (Note that you must have the ftp bit on in $gip_loc/clients, i.e. you must have typed mkclient.csh 199 or 231 in Installation step 1). If you obtained the GIPSY sources via anonymous ftp or tape type: 
        cd $gip_sys
        ./archreset.csh $gip_arch
        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. You can now turn on the ftp bit again (if you want it). 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 (grep -i error p.log). If there are any, try to find out what caused them. If you can't solve the problem by playing around with compiler switches, contact the GIPSY manager at Groningen (gipsy@astro.rug.nl). If somehow a GIPSY source did not compile correctly because the standard switches in $gip_loc/setup are not suitable (probably because of compiler bugs), create a file 'options' in $gip_loc (see $gip_sys/options.mgr for a list of known problems with compilers).

If you want to obtain regular updates of sources via gftp you should turn on the ftp bit (bit 8) in the $gip_loc/clients file (e.g. put number 199 in the clients file). 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 MUST have 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.


Installation step 4: Local system setup

In order to get the system running properly, you have to edit/create 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
Examples of files that we use in Groningen can be found in: $gip_loc/grdevices,   $gip_loc/lpdevices,   $gip_loc/mtdevices and $gip_loc/tvdevices.


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 
        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: 
      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 once a week.


Post installation: Regular updates

If you want regular updates of modifications to GIPSY sources or new GIPSY applications, and you can compile GIPSY sources, you must do the following:

Turn on the ftp bit in the $gip_loc/clients file.

With $gip_sys/atqueue.csh you can queue the update job to run at a specified time and update the gipsy sources. Preferably this is done once a week. You can also use cron for regular updates. A cron command which updates every tuesday would look like: 

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


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_sys/setup to enable correct compiling. These modifications must remain local, so your modifications should end up in $gip_loc/setup.
  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. Check whether you can start a remote shell on all the machines you want to run GIPSY (also if you have only one machine). If the remote shell does not want to run, check your .rhosts file in your home directory.
  6. 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
  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
Kapteyn Institute, University of Groningen, The Netherlands
All Rights Reserved.

GIPSY