Dept of Commerce / NOAA / OAR / ERL / PMEL / TMAP

Ferret Home Page
----------------------------------------------------------------------------

                          Ferret Installation Guide

                          Version 4.40 -- UNIX/XGKS

                                 August 1996

----------------------------------------------------------------------------

   * Installing Ferret on UNIX Systems.
   * Installing the Ferret executables and customizing the setup file.
   * Running Ferret with the GUI.
   * Setting up your GKS environment.
   * Documentation.
   * Reducing Disk Space Required.
   * Setting up an account to run Ferret.
   * Special environment variables and files.
   * Setting up the Hard Copy Environment.

----------------------------------------------------------------------------

Installing Ferret on UNIX Systems

This installation guide assumes the installer is familiar with the UNIX
system. He or she must be familiar with the file system of the target
computer, and may need system privileges if installing Ferret in a root-
owned directory.

If you install this software please notify ferret@pmel.noaa.gov and please
indicate what type of computer system you are using. We've formed a Ferret
Users Group so that

  1. we can let you know of significant new developments.
     (occasional messages -- e.g. availability of point-and_click Ferret)
  2. Ferret users can share questions and solutions.

To join simply email to Majordomo@ferret.wrc.noaa.gov and include a message
which says:

    subscribe ferret_users

     (Note this must be in the message BODY -- not in the subject
     line.)

To learn about the users list without joining send this message instead to
the same address:

    subscribe ferret_users

You will require approximately 30 Mbytes of disk space to install Ferret,
preferably on your `/usr/local' file system. Another 30 Mbytes are needed on
a disk device to install the demonstration data sets. If disk space is a
problem, the section Reducing Disk Space Required in this installation guide
provides assistance with which files are safe to delete.

The Ferret distribution is made up of three compressed tar files:

   * a tar file of the Ferret software support directories
   * a tar file of the sample data set directories
   * a tar file of the Ferret executables

All three of these files need to be placed on your system. To begin the
Ferret installation, the following or equivalent steps should be followed:

  1. Determine a suitable location on your file system to install the Ferret
     program and its support files. The location we recommend is
     `/usr/local'. You will need 30 Mb available there. From there, create
     the directory `ferret', and change directory to it.

          % cd /usr/local (our recommendation, but it's your choice)
          % mkdir ferret
          % cd ferret

     This guide will use the name $FER_DIR to refer to this directory
     (`/usr/local/ferret' -- or your choice, if different).

  2. The file `fer_environment.tar.Z' holds the Ferret support directories
     and associated files. To install the file

           % zcat $GET_LOCATION/fer_environment.tar.Z | tar xvf -

     where $GET_LOCATION is the directory you put the compressed tar file in
     when getting it via ftp. Be sure you're in the $FER_DIR directory when
     you run this command. When that's done, running `ls' in that directory
     should give the following listing:


           % ls -1F
           bin/
           contrib/
           doc/
           examples/
           go/
           ppl/


  3. Now determine a location on your file system suitable for Ferret's
     sample data files. You'll need 30 Mb available. From there create a
     directory `fer_dsets', and change directory to there.

          % cd ... (for example, `/home/data_disk')
          % mkdir fer_dsets
          % cd fer_dsets

     This guide will refer to this directory by the name $FER_DSETS.

  4. Extract the sample data set directories from their compressed format:

           % zcat $GET_LOCATION/fer_dsets.tar.Z | tar xvf -

     Again, $GET_LOCATION is the directory where the tar file resides. Be
     sure to be in $FER_DSETS when running this command. Executing `ls' from
     that directory should give the following listing:

           % ls -1F
           data/
           descr/
           grids/


Installing the Ferret executables and customizing the setup file

After these directories are created, two steps complete the installation of
Ferret, and you can begin using it. There is a shell script called
`Finstall' to help you with these two tasks. (One other step documented in
the section Setting Up the Hard Copy Environment sets up easy printing of
hard copy from Ferret plots.)

The Finstall script is in the `bin' subdirectory of $FER_DIR (where you put
the Ferret support files) and can be invoked by referencing the complete
path to it:

     % /usr/local/ferret/bin/Finstall (for example)

Finstall will then ask you to select from two options, corresponding to the
remaining steps:

  1. Install executables:
     This option extracts files from the compressed tar file
     `fer_executables.tar.Z'. You'll want to run this option if you're
     installing Ferret for the first time, and also if you're updating a
     Ferret you already have.

     When these files are extracted by Finstall they're placed in
     `$FER_DIR/bin'; the two files extracted are the Ferret program itself
     (`ferret') and the program that translates Ferret's graphics metafiles
     to PostScript for hard copy (`gksm2ps').

     To install the executable:
       1. Select Option 1 after invoking Finstall.
       2. Finstall prompts you for the directory you installed the Ferret
          support files in ($FER_DIR). Enter the complete path to that
          directory.
       3. Finstall prompts you for the directory you currently have the
          fer_executables tar file in ($GET_LOCATION). Enter the complete
          path to that directory.
       4. Finstall then installs the executables in `$FER_DIR/bin'.

  2. Customize `ferret_paths':
     This option modifies the `ferret_paths_template' script to set
     environment variables FER_DIR and FER_DSETS to the directories at your
     site where the Ferret software and demonstration data were placed. The
     modified file is written out as `ferret_paths' and placed in a
     directory you will be asked to specify.

          We STRONGLY RECOMMEND that the new file NOT be placed
          anywhere inside of the $FER_DIR directory tree. Modifications
          inside of $FER_DIR may cause complications when future
          versions of Ferret are installed. Instead, we recommend that
          the new file be created in `/usr/local' or another directory
          that will be in the users' PATH variable. This guide will
          refer to that directory by the name $SET_FER. The
          `ferret_paths' file, after it's customized, may be used to
          set up the users' environment to run Ferret (For more detail,
          see the explanation in `$FER_DIR/bin/ferret_paths_template').

     To customize `ferret_paths':
       1. Select Option 2 after invoking Finstall.
       2. Finstall prompts you for the directory you installed the Ferret
          support files in $FER_DIR. Enter the complete path to that
          directory.
       3. Finstall prompts you for the directory you installed the Ferret
          sample data files in ($FER_DSETS). Enter the complete path to that
          directory.
       4. Finstall prompts you for the directory you wish to place the
          ferret_paths file in $SET_FER. Enter the complete path to that
          directory.
       5. Finstall then creates `ferret_paths' in the directory you
          specified.

     After the `ferret_paths' file customization is complete, execute the
     Ferret setup procedure with the command

           % source $SET_FER/ferret_paths

Access to Ferret and its supporting routines is through the addition of
`$FER_DIR/bin' to your PATH environment variable. This addition will be done
automatically when the command `source $SET_FER/ferret_paths' is issued.

Ferret can now be run by entering

    % ferret

Running Ferret with the GUI

Ferret can be run with the Graphical User Interface (GUI) by entering

    % ferret -gui

If you wish to customize the ferret GUI you must first install the file
`$FER_DIR/doc/Ferret_4.40_xdefaults' which contains parameter defaults used
by your X windows system to run the Ferret GUI. The GUI has fallback
resources in case no app-defaults file is found but these are ignored if the
app-defaults file exists. (regardless of what the app-defaults file
contains!)
Therefore: You should not delete any entries when modifying the app-defaults
file.

To install `Ferret_4.40_xdefaults':

  1. Use the Unix `su' command to become super-user. (Get help from your
     system manager if this command is unfamiliar.)
  2. Create a soft link in the X11 defaults directory to the
     `$FER_DIR/doc/Ferret_4.40_xdefaults' file The soft link should have the
     name `Ferret'. On systems based on Motif window managers (most Unix
     systems) this will be the command:

     ln -s $FER_DIR/doc/Ferret_4.40_xdefaults /usr/lib/X11/app-defaults/Ferret

     On Sun systems running OpenWindows use, instead, the command:

     ln -s $FER_DIR/doc/Ferret_4.40_xdefaults /usr/openwin/lib/X11/app-defaults/Ferret

Setting up your GKS environment

This version of Ferret (v 4.4) uses a public domain graphics library, XGKS.
There are no licensing fees. The graphics library is linked with Ferret and
no special action needs to be taken to implement its use. This version of
Ferret supports X Window graphical output, and PostScript is used to provide
hard copy of plots. Sequential screen images can also be saved as HDF
"raster8" files and animated; single images can be saved as "gif" files.

To get graphical output from Ferret at your workstation, you must have the X
Windows environment variable DISPLAY defined properly. Set the variable to
point to the workstation screen where you want Ferret graphical output
displayed. In the example below graphics output will be sent to the screen
of workstation anorak.

    % setenv DISPLAY anorak:0.0

Documentation

Examine the files located in `$FER_DIR/doc' for a number of online documents
about Ferret. Files ending in `.ps' are in PostScript format and are
intended for printing on PostScript printers. Other documents are not
intended for hard copy but are ASCII text versions of the PostScript
documents. They are suitable for on-line review.

The script `print_ferret_docs' when run will present a menu from which you
may choose documents to be printed.

For a productive and smooth start using Ferret, review the Demonstration
Files section of the Ferret User's Guide (Type `Fhelp "demonstration files"'
at the shell prompt for a list). Tutorial scripts demonstrating Ferret data
sets and usage are documented there. We recommend trying them out first.

In addition, the tutorial scripts (journal files) in `$FER_DIR/examples' are
excellent source material for your own scripts. Copy any or all to your own
area and print out, study and modify them to suit your needs.

Note that the interactive help available from the commands Fhelp, Fapropos,
and Ftoc require that the files `ferret_users_guide.txt' and
`ferret_ug_toc.txt' be online.

As of September 1996, a new Ferret User's Guide for Ferret V4.4 is under
development -- not yet distributed. The information contained in the Ferret
User's Guide with this release may refer to version 3.1 of Ferret. The
on-line release notes available at http://www.pmel.noaa.gov/ferret/home.html
should be referenced to augment this version of the user's guide.

Additional on-line documents, including this installation guide, are also
avalable at the URL above.

Reducing Disk Space Required

Various directories and files may be deleted if disk space is a concern.
Below is an outline of the considerations for deletable directories.

If you have no use for PostScript documentation files you may delete
`$FER_DIR/doc/*.ps' (`pplus_fonts.ps' is over 2 Mb). If you have no use for
online copies of the documentation in ASCII files then you may safely delete
from directory `$FER_DIR/ferret/doc' all files, `*.txt', except
`ferret_users_guide.txt' and `ferret_ug_toc.txt'. Up to 1 Mb may be
recovered.

You may selectively delete the data files in `$FER_DATA/data'. These files
are used by several of the GO examples located in `$FER_DIR/examples'.
Potential savings of up to 25 Mbytes are possible by deleting these data.

Setting up an account to run Ferret

To set up a user account to run Ferret (C-shell only) add the following line
to the `.login' file for that account:

     % source $SET_FER/ferret_paths (see Customize ferret_paths)

To properly set up the account to produce plots and other graphs, a user
must have set the environment variable DISPLAY, as explained above. This can
be done by using the `setenv' command in the user's `.login' file, for
example:

    % setenv DISPLAY anorak:0.0

Special Environment Variables and Files

The three environment variables FER_DATA, FER_DESCR, and FER_GRID have been
set up to point to the sample data sets included with Ferret. Each of these
defines a path to the files Ferret needs to properly access data sets. The
pathlist can be expanded to suit your needs. In particular, FER_DATA may be
a path to directories residing on several devices; thereby allowing data
sets to be large, quite possibly spanning more than one file system. (NetCDF
files are pointed to by FER_DATA.)

As you become more familiar with Ferret through use and reading
documentation, you may want to modify these pathlists from the way they are
now defined in the script `ferret_paths'. A file in directory `$FER_DIR/bin'
called `my_ferret_paths_template' will help with this. See the section in
the Ferret user's guide covering UNIX account set up for that optional
modification.

Ferret also uses an optional initialization file, `.ferret', located in the
user's $HOME (login) directory. This file, if it exists, will be executed
automatically each time Ferret is started up, permitting Ferret to be
tailored to individual needs and styles. The format of the file is like any
other Ferret "GO" file -- an ASCII file of Ferret commands, one command per
line.

Setting up the Hard Copy Environment

Hard copies can be made from Ferret plots very easily.

Plots must be saved on disk as "metafiles" before hard copy can be made; the
GKSM metafile format is used to record Ferret plots on disk. To create
metafiles, within a Ferret session, invoke the Ferret command `SET MODE
META'. Subsequent plots will be saved in metafiles. To cancel recording of
plots, specify `CANCEL MODE META'. The metafiles will by default be named
`metafile.plt' and sequential, emacs-style version numbers are used to
uniquely identify each plot file by appending a suffix of `.~nnn~', where
nnn is a unique version number.

There is a shell script supplied with Ferret (, in the `$FER_DIR/bin'
directory, that both translates the metafiles to PostScript and routes the
resulting files to a printer. You'll usually use the script -- modified
slightly to include the printers at your site -- to print Ferret plots. (For
consistency at Ferret installations, we ask that if you use the script you
retain the syntax outlined below for its use. Feel free to modify the syntax
and give it another name, or write new scripts; but please use a different
command name in that case.)

The example script is named `Fprint_template'. The modified file should be
called `Fprint' and placed in a directory that will be in a user's PATH (we
suggest `/usr/local'). As with the `ferret_paths' file (see section
Customize `ferret_paths') we strongly recommend the edited file not be
placed in the $FER_DIR directory tree. Please look in the `Fprint_template'
file for instructions to help you add your site's printers to the script.
There is an Fprint document in the `$FER_DIR/doc' directory suitable for
general use as a guide to Fprint's syntax.

The command Fprint has a syntax allowing specification of the printer to be
used and the metafiles to be processed. Invoking `Fprint -help' will give u
sage information. `Fprint' uses as default the printer named by the
environment variable PRINTER; or the destination printer can be named: Here
are a few examples:

     % Fprint metafile.plt*
     % Fprint -P printer_name metafile.plt*
     % Fprint -P printer_name metafile.plt.~3~ metafile.plt.~7~

The first example sends files `metafile.plt*' to the default printer
(determined by environmen t variable PRINTER), the second sends all
`metafile.plt*' files to `printer_name', and the last sends the indicated
plots to that same printer.

Fprint can be used to translate a metafile and output the result to a disk
file in PostScript format; Fprint also renders metafiles on a X Window
workstation for review.

Hard copy of a plot is generated by Fprint in two steps:

  1. conversion of the device independent GKS metafile to PostScript, the
     well-known page description language

  2. routing the PostScript file to a particular device.

The conversion is done by the command `gksm2ps', which is supplied with
Ferret. Both its syntax and examples of use are given in the Ferret User's
Guide. An example of its use to convert one plot file (`metafile.plt') to a
PostScript file (`gksm2ps_output.ps') is:

    % gksm2ps -o gksm2ps_output.ps metafile.plt

Routing that file to a printer could be done manually with:

    % lpr -s gksm2ps_output.ps

----------------------------------------------------------------------------
Dept of Commerce / NOAA / OAR / ERL / PMEL / TMAP

Comments: ferret@pmel.noaa.gov

Last modified: Fri Sep 13 12:02:37 PDT 1996
URL: http://www.pmel.noaa.gov/ferret/installation_guide.html
