National Oceanic and
Atmospheric Administration
United States Department of Commerce

Ferret Installation and Update Guide

Ferret Installation and Update Guide

Installing Ferret

Updating Ferret

Welcome to the Ferret user community!

We encourage you to install PyFerret.  PyFerret runs all your Ferret scripts and does not require Python knowledge. See the PyFerret Downloads page for PyFerret installation options

 

If you really want classic Ferret, continue.

These instructions apply to the current release of classic Ferret, and to any Ferret releases v7 and higher. Any variations that apply to particular versions are noted in the instructions.

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

  • we can let you know of significant new developments and Ferret releases.
  • Ferret users can share questions and solutions.

To join, simply follow the instructions on the Email Users Group page.
 

Downloading the tar files

***
NOTE: Starting with Ferret v7.2 the tar files are available from the NOAA-PMEL Ferret GitHub releases page. The datasets are available from the NOAA-PMEL/FerretDatasets page. The tar file from GitHub consists of just one file containing the executables and environment. Put this in your desired location for FER_DIR as described below, untar the and run Finstall OPTION 2 only.
***

 

The Ferret distribution is made up of two gzipped tar files

  • The Ferret executables and utilities, e.g.  ferret-7.4-RHEL7-64.tar.gz
  • The sample datasets, e.g. FerretDatasets-7.4.tar.gz (includes data needed by demo scripts, and by the scripts that make maps and map outlines)

Download these from

https://github.com/NOAA-PMEL/Ferret/releases  or https://github.com/NOAA-PMEL/PyFerret/releases

https://github.com/NOAA-PMEL/FerretDatasets/releases

 

The tar files are named with the release and for the executables tar file the operating system version.  Below the examples use a particular name.  Substitute the names of the tar files you download.

If you have an update procedure that uses the old names fer_executables.tar.gz and fer_environment.tar.gz, note that these tar files are contained in the ferret-v.v-XXX.tar.gz file, organized in the same way as those files have always been, so you can use those as always.

Installing Ferret

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

Or, if you do not have access to /usr/local, you can install in any directory under your home directory, for instance,

% cd
% mkdir ferret_install
% cd ferret_install
% cd ferret

This guide will use the name $FER_DIR to refer to this directory (/usr/local/ferret -- or your choice, if different, for instance /home/users/myname/ferret_install/ferret).

In the $FER_DIR directory,

%tar xzf $GET_LOCATION/ferret-7.4-RHEL7-64.tar.gz

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

% ls -1F ferret-7.4.4-RHEL7-64
bin/
contrib/
examples/
ext_func/
fer_environment.tar.gz
fer_executables.tar.gz
go/
ppl/

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

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.

Download the Ferret datasets tar file from https://github.com/NOAA-PMEL/FerretDatasets/releases

in the fer_dsets directory,

% tar xzf $GET_LOCATION/FerretDatasets-7.4.tar.gz

Now, view the contents

% ls -1F FerretDatasets-7.4
data/
descr/
grids/
LICENSE
README.md

 

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.)

If you have Ferret installed and are installing a new Ferret executable, then to avoid confusion, un-set FER_DIR if this is set in your current environment. If you are updating the Ferret datasets, also un-set FER_DATA.  E.g. if you run csh:

% unsetenv FER_DIR

% unsetenv FER_DATA

 

The Finstall script is in the `bin' subdirectory of the ferret-7.4.4-RHEL7-64  directory under $FER_DIR  and can be invoked by referencing the complete path to it:

% /usr/local/ferret/ferret-7.4.4-RHEL7-64/bin/Finstall

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

    ...

 
 Enter your choice:
 (1) Install executables, (2) Customize ferret_paths files, (3,q,x) Exit
 (1, 2, 3, q, x) -->

     

    1. Install executables:
      - SKIP THIS STEP if you have downloaded the all-inclusive tar file from GitHub.  This step will already have been done.

       

    2. The executables were extracted by the untar step and placed in `$FER_DIR/ferret-7.4-RHEL7-64/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').

       

    3. 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 recommend 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, e.g. /usr/local/ferret/ferret-7.4-RHEL7-64
      3. Finstall prompts you for the directory you installed the Ferret sample data files in ($FER_DSETS). Enter the complete path to that directory, e.g. /home/data_disk/FerretDatasets-7.4
      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, which can be any directory that exists, perhaps  /usr/local/bin
      5. Finstall prompts you for the ferret_paths link option, to create a ferret_paths file symbolic link to the version of this file for the preferred shell, if desired.
      6. 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

    We encourage contributions from users. The following document was contributed, outlining the steps taken to install Ferret on an Ubuntu system.  The document has minor updates to account for simplified installation with Ferret v7.4 and higher. Note that the process for installing PyFerret is the same: it requires Python modules which are included with your Ubuntu system.

    ferret_installation_example.pdf

    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 already 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 issued 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. 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 affect the demonstration scripts, listed from minimum to maximum effect, are esku_heat_budget, etopo40, monthly_navy_winds, levitus_climatology and coads_climatology. etopo5 may also be removed, however LAS depends on it for making maps.

    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 path list 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 External 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 path lists 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.  Please see the main documentation and the FRAME command for writing gif files, and for PyFerret graphics output types.

      To make PostScript plots in Ferret, plots must first be saved on disk as "metafiles", which use the GKSM metafile format.  These metafiles are translated to PostScript in a second step using a shell script provided with the Ferret installation.  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 environment 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

        This information is relevant to versions prior to v7.3.  Starting with v7.3, just do a re-install.

        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 list server email announcing an update, consider updating your installation. Here's how you can update either or both components:

        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.

         

         

        Return to Ferret Downloads page