Downloading the tar files

You will require approximately 150 Mbytes of disk space (depending on O.S.
type) to install Ferret, preferably on your `/usr/local' file system. Another 85
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 gzipped tar files:
fer_executables.tar.gz (Ferret and utilities)
fer_environment.tar.gz (support files)
fer_dsets.tar.gz (sample data sets)
All three of these files need to be placed on your system. After acquiring them,
follow the steps below to install the application.
Installing support files
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 150 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.gz' holds the Ferret support directories
and associated files. To install the file
% tar xzf $GET_LOCATION/fer_environment.tar.gz
where $GET_LOCATION is the directory you put the gzipped 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/
examples/
ext_func/
go/
ppl/
3. Now determine a location on your file system suitable for Ferret's sample
data files. You'll need 85 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 gzipped format:
% tar xzf $GET_LOCATION/fer_dsets.tar.gz
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/
Completing the installation with Finstall
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 gzipped tar file
`fer_executables.tar.gz'. 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.
NOTE: Beginning with Ferret v6.7 the Ferret install procedures will run
under the csh or bash shell with no modification. Prior to that version, note
that the file ferret_paths_template was created using c-shell syntax. For
users of either the bash shell (bash) or the korn shell (ksh), there are
appropriate ferret_paths_template files in $FER_DIR/bin. Before running
Finstall to customize ferret_paths, be sure to copy the correct template file
for your shell to ferret_paths_template. If you are using a completely
different shell, use ferret_paths_template as a guide to creating a template
customized for your specific Unix shell.
We rrecommend that the new ferret_paths 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
Setting up your display environment
To get graphical output from Ferret at your workstation, you must have the X
Windows environment variable DISPLAY defined properly. Check whether your
DISPLAY variable is alresdy set,
% printenv DISPLAY
If you system is called anorak, then the response might be anorak:0.0 or,
depending on your environment, something like localhost:10.0. If DISLPAY is
not set, then 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
Ferret supports X Window graphical output, and PostScript is used to provide
hard copy of plots. Images can also be saved as "gif" files.
Documentation
The Ferret User's Guide and on-line release notes are available at
http://ferret.pmel.noaa.gov/Ferret/documentation
Additional on-line documents, such as FAQ's and on-line tutorials, are also
available at the URL above.
For a productive and smooth start using Ferret, review the Demonstration Files
section of the Ferret User's Guide. Tutorial scripts demonstrating Ferret data sets
and usage are documented there. We recommend trying them out first. A Ferret
beginner will want to scan the first 6 chapters of the Users Guide for introductory
information.
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.
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.
You may selectively delete some of the data files in `$FER_DSETS/data'. Others
are essential for creating land outlines and masks and climatological axes. Note
that deleting data sets from this directory will cause some of the demonstration
scripts distributed with Ferret to break. Data sets which may be removed that will
only effect the demonstration scripts, listed from minimum to maximum effect,
are esku_heat_budget, monthly_navy_winds, levitus_climatology and
coads_climatology. etopo5 may also be removed, however LAS depends on it for
making maps.
The file fer_dsets_smaller.tar.gz may be downloaded instead of
fer_dsets.tar.gz. It contains a subset of the datasets: esku_heat_budget, etopo5,
etopo40, and the dataset geo_borders_intermed.nc which is used by the script "go
land_detail" are removed from this tar file.

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, Setting up DISPLAY
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.)
The environment variable FER_EXTERNAL_FUNCTIONS by default is set to
point to $FER_DIR/ext_func/libs, where the external function sharable object
libraries that are distributed with Ferret reside. Add additional paths to this list as
needed to point to other repositories of Exernal Functions
With new releases of Ferret, functions originally developed as external functions
are linked into the Ferret executable. This makes them available to users whose
systems don't allow for the use of shared object files. If you are upgrading to a
new version of Ferret you may wish to clean out shared object files from the
FER_EXTERNAL_FUNCTIONS directory, making sure to save any functions
you have written or installed yourself.
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
Updating your Ferret installation
The Ferret system has two components, the environment -- or support -- files, and
the executables. We may add enhancements to the two parts independently. If
Ferret was installed at your site months ago, or you receive Ferret User Group
listserver email announcing an update, consider updating your installation. Here's
how you can update either or both components:
Updating the environment files
The update contains recent enhancements, usually including Ferret scripts adding
new capabilities, demonstration scripts, color palettes, and more. The latest update
to the environment files is in the distribution directory for each system we
support, and named
fer_environment.tar.gz (support files)
To install the updated versions of the environment files, please follow the
instructions above in the section Installing support files. If you have made
modifications to files such as scripts or palette files, you will want to save those to
another directory and use the environment variables FER_GO and
FER_PALETTE to point to these directories as well as the default Ferret
locations. The environment file for a Ferret release is system independent. (This is
true starting with the release of Ferret version 6.7 and higher.)
Updating the Ferret executables
The file 'fer_executables.tar.gz' in the distribution directory holds the ferret and
gksm2ps programs that you picked up when you first installed Ferret. In addition
it contains compiled external functions and font files which are specific to the
operating system. It also contains the ThreddsBrowser jar file. We update these
with enhancements and bug fixes periodically.
The Ferret Downloads page lists the version of ferret available. If the version 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 and operating system, e.g.,
FERRET v6
Linux(g77) 2.4.21-32 - 08/23/06
In addition, after Ferret starts, the symbols ferret_version, netcdf_version, and
ferret_platform are defined and contain the pertinent information about that
particular Ferret executable and the version of the netCDF library that it is linked
with.
yes? SHOW SYMBOL ferret_version
yes? SHOW SYMBOL netcdf_version
yes? SHOW SYMBOL ferret_platform
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:
Get the fer_executables.tar.gz file in binary mode.
As in your original installation, run the script
% Finstall
(it is in your directory $FER_DIR/bin)
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.gz file in. Enter the complete path to that
directory.
4. Finstall then installs the executables in $FER_DIR/bin.