Introduction
------------

Thank you for your interest in Ferret and in compiling Ferret.  This
document is designed to assist in getting Ferret compiled and linked
on your system.  NOTE: These procedures have only be confirmed to work
on the following systems:

	Digital Unix v4.0
	Sun Solaris v2.4
	RedHat Linux v5.0

These are the only systems we have access to, and therefore the only
systems we have compiled and linked Ferret (recently) on.  Part of the
reason for distributing source code is to draw upon the expertise of
the Ferret users in order to help port Ferret to other operating
systems.  If you link Ferret on an operating system other than the
above, please let us know.  If you have one of the above operating
systems, Ferret can be picked up in binary from anonymous ftp at:

	http://ferret.wrc.noaa.gov/Ferret/

What is needed
--------------

Besides Fortran and C compilers, the follwing libraries are necessary
to compile and link Ferret:

	Motif Libraries (in order to compile/link GUI)
        HDF libraries (version 3.2)
        Netcdf libraries (version 2.4.2)
        Xgks libraries (source included)
        linked list library v2.1 (source included)
	Readline library (source included)

As mentioned below, the Ferret Makefiles reference an area called
TMAP_LOCAL.  This area is assumed to be the place where include files
and libraries not inherent to the operating system, yet necessary to
compile and link Ferret, reside.


SOURCE DIRECTORY OVERVIEW
-------------------------

			|-- fer
			|
			|-- fmt
			|
			|-- gksm2ps
			|
	|-FERRET_ROOT-|	|-- lib
			|
			|-- ppl
			|
			|-- xgks
			|
			|-- list-2.1
			|
			|-- readline-4.1
			|
			|-- bench
			|
			|-- external_functions


where:

	fer  	  is the main Ferret compilation directory.  This is 
		  where the Makefiles and platform-specific files reside
	
	fmt 	  is the area of source for basic Ferret functions, including
		  I/O, readline, etc.

	gksm2ps   is the metafile translator source

	lib	  is where the Ferret-created libraries will be stored after 
		  compilation

	ppl 	  is the PlotPlus source code
	
	xgks 	  is the Xgks graphics package source code
	
	list-2.1  is the linked list utilites source package
	
	readline-4.1 is the readline source package
	
	bench     contains the benchmark suite for testing the Ferret
		  executable once it has been linked
	
	external_functions  contains the code which describes and gives
			    examples of Ferret external function 
			    framework 

To compile
----------

1a) compile Linked list library
	> cd $FERRET_ROOT/list-2.1
	> make
	
   move created library to $TMAP_LOCAL/lib and the file list.h to 
   $TMAP_LOCAL/include.

1b) compile Readline source library
	> cd $FERRET_ROOT/readline-4.1
	> ./configure
	> make

2) compile xgks (If Xgks is already installed, you may skip this step)
	a) create a CUSTOMIZE.YOUR_HOSTYYPE file, ie CUSTOMIZE.solaris
		- this contains the location in which the xgks items
		  will be installed
	b) run configure
		> ./configure
	c) compile sources
		> make

	d) install 
		> make install
	

3)Compile and link Ferret
	> cd $FERRET_ROOT/fer
	a) first a file called 
		platform_specific_flags_flags.mk.YOUR_HOSTTYPE 
	   needs to be created.  this file contains fortran and c flags,as well
	   as pointers to system libraries, etc.  Look at one of the existing 
	   files for an example of what should be included.   In addition to 
           platform specific files for the OS's we use, I've also
           included platform specific files for SGI Irix v5 and IBM AIX OS's.
           These are meant only as a guide, and are undoubtably out of date.

	> make update
		This will create two files, which contain the current
		version of the ferret build and the build date, in the 
		special directory and compile the files in that directory

	> make gui_nodebug
		this will compile sources in the fmt, ppl and fer directories
		and will also link Ferret with the Graphical User Interface.

	  ***OR**
	
	> make
		this will compile sources in the fmt, ppl and fer directories
		but will not compile or link the GUI.

4) Create External_functions .so files  (optional)
	> cd $FERRET_ROOT/external_functions
	> make
	
	This will compile the suite of external_function utility routines.  To
	access these files w/in ferret, make sure to set the environment 
	variable FER_EXTERNAL_FUNCTIONS to $FERRET_ROOT/external_functions
		
5) Run Benchmark suite
	> cd $FERRET_ROOT/bench
	> run_all

	The run_all script will ask a few questions (such as where the 
	executable to test resides) and then launch into the benchmark
	routines.  When the test suite completes, you can compare the 
	results found in newly create all* files w/ the official* log 
	files.  One of the benchmark tests is concerned with the
	External Functions mentioned above.  If the External Functions
	aren't compiled, there will be a large chunk of output found in
	the official* log files that won't be in the newly created ones.


NOTES
-----

Included in the main directory ($FERRET_ROOT) is a file called

	IFDEF_DESCRIPTION

which details the usage of the different ifdef/preprocessor directives
used in the Ferret code.  This is meant to assist in choosing the
correct options for your system.

This package, including the documentation, represents the initial
attempt at source distribution for Ferret.  A crucial aspect of making
this source distribution more complete and usable will be feedback
from those who have attempted compiling and linking Ferret.

Also, If you plan any modifications to the functionality of Ferret, please 
consider contacting us first.  We may be able to save you some time and
frustration with our in-depth knowledge of the code.

Questions, problems or suggestions can be directed to:

	kobrien@pmel.noaa.gov

Good luck, and happy Ferreting!

