|
|
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 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
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:
info 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 gzipped tar files:
All three of these files need to be placed on your system. After acquiring them, follow the steps below to install the application.
/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/
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:
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_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
').
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
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
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
':
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
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
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.
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://ferret.pmel.noaa.gov/Ferret/documentation 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.
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 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.
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
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.)
V5.0 of Ferret has added two new environment variables: FER_WEB_BROWSER and FER_EXTERNAL_FUNCTIONS. FER_WEB_BROWSER should be set to the Unix command string that will bring up a Web browser. e.g. "netscape -ncol 60". The definition will be more robust if it omits absolute path and DISPLAY definitions. 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 EFs
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.
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*
printer_name
% Fprint -P metafile.plt*
printer_name
% Fprint -P 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:
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
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:
The update contains recent enhancements, usually including Ferret scripts adding new capabilities, demonstration scripts, documentation, and more. The latest update (or "patch") to the environment files is in the distribution directory for each system we support, and named
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
The file 'fer_executables.tar.Z' in the distribution directory holds the ferret and gksm2ps programs that you picked up when you first installed Ferret. We update those with enhancements and bug fixes periodically.
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