Installing Gri

1: Introduction
2: Simple example
3: Fancy example
4: Running Gri
5: Programming Gri
6: General Issues
7: X-Y Plots
8: Contour Plots
9: Image Plots
10: Examples
11: Handling Data
12: Gri Commands
13: Gri Extras
14: Evolution of Gri
15: Installing Gri
16: Gri Bugs
17: System Tools
18: Acknowledgments
19: License
20: Newsgroup

21: Concept Index

15: Accessing and Installing Gri

15.1: Accessing

No special setup is required, except for optionally creating a resource file see Resource File, or defining the `GRIINPUTS' environment variable see Options On Command Line.

15.2: Installation

Most users get Gri from the anonymous ftp site `ftp.phys.ocean.dal.ca/pub/users/kelley/gri' <P>

15.2.1: Unix Installation

The directory structure for Gri is as follows, where in this example the most up-to-date version is 2.4.2, and `OLD' is meant to represent an older numbered version. 

                          /opt/gri/
                             |
                             |
                             |
src/   lib/   bin/         2.4.2/              OLD/
 |      |      |             |                   |
 |      |      |             |                   |
 |      |      |             |                   |
...  gri.cmd  gri    src/   lib/  bin/     src/  lib/  bin/
                      |      |     |        |     |     |
                      |      |     |        |     |     |
                      |      |     |        |     |     |
                     ...  gri.cmd gri      ... gri.cmd gri

On some systems, the base directory is `/usr/local/lib/' or something similar, instead of `/opt/gri/'; this can be set during the compilation of Gri; see Uncompiled Unix.

The subdirectory with the highest number holds the current version of Gri. During installation, this is linked in two stages, all the way back to a file installed in the PATH of all users.

First, the relevant numbered executable and library files are linked back to unnumbered directories. For example, `/opt/gri/2.4.2/bin/gri' is linked to `/opt/gri/bin/gri' and `gri.cmd' is handled similarly. Thus the unnumbered directories always contain the most up-to-date versions of Gri, while various numbered directories may contain old copies, if the system manager has elected to not delete them.

Second, `/opt/gri/bin/gri' is in turn linked to a file in the system path, normally `/usr/local/bin/gri'. At the same time, a duplicate link is made, to a numbered executable (e.g. `/usr/local/bin/gri-NNNN', where `NNNN' is the version number) inserted in the system path. Thus the current version of Gri can be accessed by users by typing either `gri' or e.g. `gri-NNNN' where `NNNN' is the version number. Any older versions of Gri which were not removed by the person doing the installation will also be available, e.g. by typing `gri-2.039'. Each of these numbered versions knows to look for it's library file in the appropriately named library file, e.g. `gri-2.039' will use `/opt/gri/2.039/lib/gri.cmd'. Therefore, older library files should be kept if older executables are kept. The default installation is to keep all old executables and library files.

Note: The library file `/opt/gri/lib/gri.cmd' is not actually used by Gri. It uses numbered files like `/opt/gri/2.4.2/lib/gri.cmd'. The unnumbered library files are provided for use by the Emacs gri-mode, when it tries to ``complete'' partially typed commands see Emacs Editing Mode.

Here are details for installation on unix computers:

15.2.2: Pre-compiled unix versions

Pre-compiled versions of Gri exist for various computers, e.g. SPARC (both sunOS and solaris), IBM-RS, Sequent, and Linux. The following instructions, which assume a version number 2.4.2, and a SPARC solaris machine, show how to install these.

The compressed tar file, with a name like `gri-binary-SunOS5-2.4.2.tar.gz' (in this example a Sun OS 5 binary is assumed, with gri version number 2.4.2) contains a directory which holds the executable Gri file, `gri', the library file `gri.cmd', an instructions file, `README', and a Makefile to install Gri.

Here's how to install Gri, starting with this tar file:

  1. First, uncompress (unzip) the file, and un-tar it, by doing 
    gunzip -c gri-binary-SunOS5-2.4.2.tar.gz | tar xvf -

    or 
    zcat gri-binary-SunOS5-2.4.2.tar.gz | tar xvf -

    This will yield a new directory, with a name like `gri-binary-SunOS5-2.4.2', which contains the indicated files.

  2. Follow the instructions in the `README' file to install Gri.

15.2.3: Installation on Linux computers

Installation is easy on RedHat and Debian flavors of linux. Versions are available from the official distributions and also at 

ftp://ftp.phys.ocean.dal.ca/users/kelley/gri

The RedHat version supports intel platforms only, while the Debian version supports intel, alpha, 68K and powerpc. Installation follows the normal method for these distributions ... if you have the distribution, you surely know what to do!

For other linux distributions, follow the compile/install procedure for other flavors of unix see Uncompiled Unix.

15.2.4: Compilation on Unix computers

To compile Gri on unix computers, do the following, starting with the tarred, compressed distribution file, with a name like `gri-source-2.4.2.tar.gz' (the number in the filename is the version number).

Choice of compilers you will have best success with the FSF C++ compiler called `g++', version 2.7.x or later (see any Free Software Foundation site, e.g. `prep.ai.mit.edu'), although any C++ compiler which handles "templates" properly should work.

If compilation fails If the procedure below fails, look in the `PORTS' directory for a file or directory with a name indicating your computer type, or look in the `various_machines' file.

  1. Type 
    gunzip -c gri-source-2.4.2.tar.gz | tar xvf -
    or 
    zcat gri-source-2.4.2.tar.gz | tar xvf -
    to uncompress and untar the contents. You should get a new directory, with a name like `gri-source-2.4.2', which contains many files.

  2. Move to this new directory, and type 
    ./configure
    to create a `Makefile' for use by the compiler. The configure script determines properties of your compiler and operating system, and adjusts the compilation procedure appropriately. It determines some of these properties itself, and asks for advice from you on others (see below). If the permission of the `configure' file is wrong, you'll get an error like `Permission denied'; if so, try typing `sh ./configure'. If that fails, you will have to use the generic Makefile called `Makefile.generic', and hope for the best. Before doing anything, though, you should read the file `PORT-HIST' for a history of porting problems; you might get some good hints here.

    Notes:

    1. The `configure' script needs to know where to install the Gri executable file and library files. Normally, it will print out a message explaining the issue, and asking where to put these things. (A reasonable default is provided, if you just answer with carriage-return.) If you know about this in advance, you can run the configure script as e.g. 
      ./configure --prefix=/opt/gri
      This says that you want Gri to exist in a directory called `/opt/gri', which will have subdirectories such as `/opt/gri/bin' and `/opt/gri/lib'.

    2. Gri uses a C++ feature called 'templates'. Unfortunately, templates are handled in different ways by different compilers. At least as of Spring 1997, the GNU compiler, vsn 2.7.x (used by many Gri folks) has problems with templates. Therefore the configure script will check to see if you are using the GNU c++ compiler, and if you are it will check whether the ("template repository") compiler flag `-frepo' is known on your machine. If it is not, an alternative method of templates will be used. But if it is, you'll be asked, for confirmation, whether you wish to use the `-frepo' flag. On many machines (e.g. Solaris) you should answer `n' to this question. The prompt will explain. Also, note that you can avoid the prompt by running configure as either of the two below: 
      ./configure --enable-frepo
./configure --disable-frepo
      (Such switches will be ignored unless you're using the GNU compiler.)

    3. If optional system libraries like the netCDF library, if it exists, are installed in nonstandard places, you might have to change the unix environment variable `LD_LIBRARY_PATH'. For example, on my machine the `netcdf' library is not installed in `/usr/lib', as the `configure' script assumes, but rather in `/opt/netcdf/lib'. Therefore I have the following line in one of my startup files: 
      export LD_LIBRARY_PATH=/usr/lib:/opt/netcdf/lib

  3. Developers only: if you wish, you can compile Gri with a debugging version of the malloc/string libraries. To do this, edit the `Makefile', searching for the item that starts with the following comment fragment: 
    # <<<--- DEVELOPERS:
    Make the changes as appropriate.

  4. Now compile Gri by typing 
    make

    (or, if the previous step failed, type `make -f Makefile.generic').

  5. Assuming compilation succeeds, install `gri' and the ancillary file `gri.cmd', by typing 
    make install

    This will try to install them in the installation directories `/opt/gri/bin' and `/opt/gri/lib', with a link for the executable to a directory in the system path, normally `/usr/local/bin'.

  6. If you wish to install numbered versions of Gri, you should now type 
    make install-numbered

  7. Once these things are done, you may type 
    make clean

    to clean up some files.

15.2.5: Compilation on x86 (PC-style) Computers

Versions exist for MSDOS, windows, and Linux operating systems. (Actually, the windows version is just the MSDOS version, which can be run inside an msdos window within windows-95, windows-NT, etc.)

15.2.5.1: MSDOS Operating System

To compile and install Gri under MSDOS, do this:
  1. To begin, install `DJGPP V2', if it's not on your system already. I can be found at http://www.delorie.com/djgpp/)
  2. Uncompress and extract from gri source package; see Uncompiled Unix.
  3. Type `make -f Makefile.dj2' to compile. If it fails, you might have to edit the file `Makefile.dj2' to match the characteristics of your system. Please inform the author, Dan Kelley at Dan.Kelley@Dal.CA, if you think your modifications might be useful to others.
  4. Type `make -f Makefile.dj2 install' to install it (normally on the `C:' drive).

If you encounter problems, read the first few lines of the Makefile (i.e. the file `Makefile.dj2') for hints on things to try. For example, in the present version of `Makefile.dj2' these hints are given:

  1. There is a good chance that this Makefile will work as is, so try that first.
  2. If you have the `netcdf' library (used for certain types of atmospheric and oceanographic datasets), then un-comment and possibly edit the appropriate `NETCDF_...' lines below, as instructed by the comments preceding these lines.
  3. If you don't want Gri inserted in the directory `c:/gri', edit the `instdir = ...' line below.
  4. If you get error messages about the `stdcxx' library, edit the `LIBS' line below, rewriting `-lstdcxx' as `-lstdcx'.
  5. If you get compilation errors relating to `time' or to `ftime', try putting the token `-DHAVE_FTIME=1' in the list of similar token in the `DEFS = ...' line. For consistency (basically, so the author can help you if you do this), put it right after the `-D_GRI_=1' token.

To view the output, use a PostScript viewer such as GSview.

15.2.5.2: LINUX Operating System

Linux is a good emulation of unix, and it's free. Gri for linux is compiled and installed according to the normal unix instructions. The compiled version is with a name like `gri-binary-solaris-2.1.10.tar.gz'; treat it as in other unix systems see Uncompiled Unix.

15.2.6: Compilation under OS/2

Gri compiles, using the gcc compiler under OS/2, provided that the included `Makefile.os2' is used. Be sure to edit the first few lines to change filenames as required, especially taking care too account for whether the netCDF library is installed, etc.

15.2.7: Compilation under Macintosh Unix

The MachTen version of unix for Macintosh acts like a normal unix. Provided that the associated `gcc' compiler is sufficiently up-to-date, Gri can be compiled following the normal unix instructions.