| Installing Ferret | Updating Ferret | 
If you install this software we ask you to please notify oar.pmel.contact_ferret@noaa.gov and indicate what type of computer system you are using. We've also formed a Ferret Users Group so that
    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:
    info ferret_users
Downloading the tar files
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:
/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).
      
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/
      
      
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.
      
      % 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/
      
      
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)
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:
$FER_DIR).  Enter the complete path to that directory. 
	$GET_LOCATION).  Enter the complete path 
	    to that directory.
	$FER_DIR/bin'.
      
ferret_paths':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 theTo customize `$FER_DIRdirectory tree. Modifications inside of$FER_DIRmay 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').
ferret_paths':
      $FER_DIR.  Enter the complete path to that directory.
	$FER_DSETS).  Enter the complete path to that directory.
	ferret_paths file in $SET_FER.  Enter the complete path to that 
	    directory.
	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
$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
    % 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!)
To install `Ferret_4.40_xdefaults':
su' command to become super-user. (Get help 
      from your system manager if this command is unfamiliar.)
  $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/FerretOn Sun systems running OpenWindows use, instead, the command:
ln -s $FER_DIR/doc/Ferret_4.40_xdefaults /usr/openwin/lib/X11/app-defaults/Ferret
anorak.
    % setenv DISPLAY anorak:0.0
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.
$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 the Ferret Documentation pages 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)
setenv' command in the user's `.login' file, for example:
    % setenv DISPLAY anorak:0.0
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~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:
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 
    patch_DATE.tar.Z        where "DATE" is a date, for example "28aug95"
The file name has the date we created the latest update.  If you have gotten
updates before, check the patch README file in your directory $FER_DIR; 
if it was created before that date, you will benefit from picking up
the latest update.  If you've not gotten updates previously and the patch file
is more recent than your Ferret installation, the update will have something
new.
The update procedure uses the shell script "Fpatch". The update (the patch) should be added only after you have installed FERRET on your system. Follow these steps to install the patch file:
    % chmod +x Fpatch
    % Fpatch
Get and examine the file in the distribution directory named 'FERRET_VERSION_HERE_IS_...'. It lists the version of ferret and gksm2ps available. If the version of either is higher than what you have, you will benefit from picking up the update and installing it. To find the version of Ferret you have installed, run
    % ferret
When ferret 
starts up it will list the version number, e.g., "Version 4.10 - 08/25/95". 
You can determine the version of gksm2ps you have by running 
    % gksm2ps -v
The application will respond with, e.g., "Version number of gksm2ps: Mod 1.03".
To update these files:
    % Finstall (it is in your directory $FER_DIR/bin)
Comments: oar.pmel.contact_ferret@noaa.gov
 
Last modified: Fri Jan  7 11:28:52 PST 2000