#	Information for installing GMT 3.3.1
#
#		@(#)README	2.47 06/28/99 
#
#	Copyright (c) 1991-1999, P. Wessel & W. H. F. Smith
#
#	See COPYING file for copying and redistribution conditions.
#
#	This program is free software; you can redistribute it and/or modify
#	it under the terms of the GNU General Public License as published by
#	the Free Software Foundation; version 2 of the License.
#
#	This program is distributed in the hope that it will be useful,
#	but WITHOUT ANY WARRANTY; without even the implied warranty of
#	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#	GNU General Public License for more details.
#
#	Contact info: www.soest.hawaii.edu/gmt

Permission to use, copy, modify, and distribute (with no more than a
reasonable redistribution fee) this software and its documentation
for any purpose is hereby granted, provided that the above copyright
notice appear in all copies, that both that copyright notice and this
permission notice appear in supporting documentation, and that the name
of GMT not be used in advertising or publicity pertaining to distribution
of the software without specific, written prior permission.  The GMT
package may be included in a bundled distribution of software for which
a fee may be charged.
The University of Hawaii (UH) and the National Oceanic and Atmospheric
Administration (NOAA) make no representations about the suitability of
this software for any purpose.  It is provided "as is" without expressed
or implied warranty.  It is provided with no support and without
obligation on the part of UH or NOAA, to assist in its use, correction,
modification, or enhancement.

0. Introduction
---------------

If you obtained GMT using the install_gmt script then you have
already completed the installation unless something went wrong.
You do not need to read these instructions unless you plan to
install and make the programs manually.

[the install_gmt script is mailed to you if you send email to
listserv@soest.hawaii.edu with the single message
information gmtgroup
Or, see www.soest.hawaii.edu/gmt]

GMT 3.3.1 has been installed successfully on Sun, Silicon Graphics, Cray,
DEC, HP, Data General, IBM, Apple, and NEXT workstations.  We anticipate
few problems if you are installing the package on other UNIX platforms.
Should you need to make small modifications, e.g., not use certain
#include files, please let us know so that future releases will be even
more portable.  This is likely to mean that your platform is not
POSIX compliant.  For a non-UNIX solution, see Appendix L for options
and installation details.

Note there are several GMT tar archives available:

1. GMT3.3.1_progs.tar.gz	: Source code only, no documentation
2. GMT_lib.tar.gz		: Standard support data libraries
3. GMT3.3.1_doc.tar.gz		: Man pages, PS documentation, and tutorial
4. GMT3.3.1_web.tar.gz		: Web (HTML) version of GMT3.3.1_doc
5. GMT3.3.1_scripts.tar.gz	: Example directory with scripts and test data
6. GMT_full.tar.gz		: Full resolution coastline data
7. GMT_high.tar.gz		: High resolution coastline data
8. GMT3.3.1_suppl.tar.gz	: GMT Supplemental programs that links with GMT

You must get 1 and 2 for a minimal GMT installation.
All archives are available in gzip (*.gz) and bzip2 (*.bz2) format.
The latter format results in much smaller files for ftp.
[bzip2 is available from www.muraroa.demon.co.uk]

1. Install netCDF library
-------------------------

GMT uses several functions in the netCDF library.  Copy the file
netcdf.tar.Z from

	unidata.ucar.edu (128.117.140.3)

using anonymous ftp.  Then uncompress/tar and follow their
instructions for installation.  Make sure you have netcdf version
3 or higher.  See the file VERSION in the netcdf/src directory.

2. Install support data
-----------------------

At run-time, GMT programs will expect to find its databases
in the sub-directory lib in the directory pointed to by the
environmental variable GMTHOME.  All users must have the statement

setenv GMTHOME /full-gmtpath

in their .login or .cshrc file.  If not set, GMTHOME defaults
to /usr/local/gmt.  Thus, in the above example the databases
are expected to reside in /full-gmtpath/lib.
GMT 3.3.1 uses a 5-resolution database for coastlines, rivers, and
political borders.  The crude, low, and intermediate resolution
files are supplied with this archive.  The high and full resolution
data must be obtained separately over the net or by mail.  The
high and full resolution files are kept in the files

GMT_high.tar.gz	(or .bz2)
GMT_full.tar.gz	(or .bz2)

Note that these two files are not necessary in order to use GMT,
only if you want to make higher-resolution coastline plots.
You may ftp these from pub/gmt on any of the following sites.  Try
the site that is closest to you to minimize transmission times:

	Site				FTP address
--------------------------------------------------------------
SOEST, U. of Hawaii			kiawe.soest.hawaii.edu
Lab for Satellite Altimetry, NOAA	raptor.grdl.noaa.gov
IAG-USP, U. of Sao Paulo, BRAZIL	ftp.iag.usp.br
Dep. Geology, U. in Oslo, Norway	ftp.geologi.uio.no
ISV, Hokkaido U, Sapporo, JAPAN		ftp.eos.hokudai.ac.jp
Charles Sturt U., Albury, Australia	life.csu.edu.au

Extract the files and put them in the directory pointed to by
GMTHOME (see above).

If your connection is such that you are unable to obtain these files
you may request a CD-ROM or 4-mm or 8-mm tape from us.  See section 15
below for details and charges.

3. Makefile preparation
--------------------------

	Copy makegmt.macros.orig to makegmt.macros first,
then edit the file makegmt.macros before compiling.  You will need
to modify a few parameters like where to put the executables,
where the netCDF library has been installed, etc.
Also decide if you want to let the macro SI be defined;  This will
make cm the default unit, otherwise it is inch.  European users
may want to set the SI macro while US users may want to turn this
off to minimize PostScript header size (which is bigger with SI
due to re-encoding of accented characters).
Note that you can alway override these defaults during runtime by
editing your .gmtdefaults file.
The makegmt.macros has several other specifications listed as comments.
Pay particular attention to the CC_OPT declaration.  If an unlisted
set of options is required on your platform - please tell us.
By default, GMT will use Jonathan Shewchuck's Delauney triangulation
routine.  If you work for a for-profit organization you should read
his copyright statement (in src/README.TRIANGLE) first.  If you cannot
use his routine you must comment out the TRIANGLE_D and TRIANGLE_O
macros in makegmt.macros as well and use the older Delauney routine
by Dave Watson.
GMT supports the sincos function (simultaneous calculation of both sine
and cosine) since this can significantly speed up map projections.
However, most platforms do not have sincos (Sun Solaris is one exception
that we are aware of).  If the -DSINCOS flag is added to CC_OPT then GMT
will compile in calls to sincos instead of sin and cos when they occur
in pairs.  You will also need to add the specific library that has sincos
to the MATH parameter in makegmt.macros (unless your sincos is in the -lm
library).  For Solaris users this means adding -lsunmath.  Note that GMT
_ASSUMUES_ that extern void sincos (double a, double *s, double *c) is
the function prototype.  If this differs on your platform you should make
a macro that looks like the above but calls your function instead.
The GMT makefile supports shared libraries, but static is default.
If you want to prepare shared GMT and PSL libraries you must select
the proper values for LD_OPT, LD, LDFLAGS and SL, set LIB to $(SHARED_LIB),
and set either LD_LIBRARY_PATH, LD_RUN_PATH, or SHLIB_PATH (HP) to
$GMTHOME/bin (which one depends on your system.  With morons in charge,
the various linkers are often incompatible).  If is pretty easy to make
netcdf a shared library after the fact.  cd to where libnetcdf.a is and do

	$(AR) x libnetcdf.a
	$(LD) $(LD_OPT) *.o -o libnetcdf.$(SL)
	\rm -f *.o

(substitute the macros with actual values for your system).  This directory
must then also be added to the colon-separated *_PATH variable just described.

4. Customize GMT-system defaults
--------------------------------

All GMT-system defaults are contained in the file gmt_defaults.h which
is included by the library files during compilation.  If you want to
make permanent changes to some of the defaults.  See the gmtdefaults
man page for a description of all defaults.

5. Compile/link
----------------

Cd into the src subdirectory where all program code is stored.
First initialize hardware-specific include files by saying

	make init

This step will create gmt_nan.h and gmt_math.h.  The former file
contains macros for creating NaN's (Not-A-Number) on your machine.
These macros are automatically generated by reading the supplied
GMT_nan.cdf file which contains both a single and double precision
NaN stored in netCDF format. gmt_math.h, on the other hand, is
created by snooping around trying to find if your system supports
a handful of non-POSIX functions that GMT uses.  While GMT can
(and in fact will) make macro substitutions if one or more of these
functions are not found, better execution is expected if we could
find native functions; this is what make attempts to do.
If make says that it failed to find 1 or more of the external symbols
copysign, log1p, hypot, acosh, asinh, atanh, isnan you may want to
double-check that those symbols _really_ are not availble on your
workstation.  If you, unlike make, are able to find them, please
see the instructions in gmt_math_init.csh on what to do.
[Note: For PCs running WIN?? or DOS you must copy the file
gmt_math_win32.h to gmt_math.h instead; see Appendix L]

If make init is successfully accomplished you may move on.
You make all programs by saying

	make all
	
which will compile/link all the programs.  After a succesful
compilation you may install the executables in the designated
bin directory with the command

	make install
	
After a successfull install you can have *.o files and the local
executables removed by saying

	make clean
	
6. Man pages
------------

GMT comes with both SI and US formatted man pages.  They are stored
in the US and SI subdirectories in src, respectively.  You can either
copy the appropriate set of man page to /usr/man/manl or set the
environment variable MANPATH in your .login file to include the man
directory that holds the desired gmt man pages.

7. WWW Documentation
____________________

In the directory www/gmt you will find html files for online
browsing of GMT documentation (Cookbook) and manual pages.
While these are available from the main GMT home page in
Hawaii, users may find it convenient to install these
pages locally for added speed.  The subdirectories
contain both HTML and PS versions of the cookbook, and
HTML versions of the manual pages.  All users need to do
is to add a browser bookmark to the top-level file
www/gmt/gmt_services.html.  Since both SI and US html
pages are distributed the installer MUST cd into the
www/gmt/doc/html directory and delete the directory
not wanted and move all files in the other directory up
one level.  E.g., if US web manpages are desired, do

\rm -f -r SI
\mv -f US/* .
rmdir US

All the PostScript files in www/gmt/doc/ps are formatted for
A4 papersize.  To convert them to US Letter papersize,
pls cd into www/gmt/doc/ps and type sh papersize.sh Letter.
(You can later change your mind with sh papersize.sh A4).

8. GMT Tutorial
_______________

The Documentation also contains the GMT_Tutorial.ps
files which is a short course in how to use GMT.  It can be
followed individually or in a lab setting by a group of users.
The tutorial directory contains a few support files for the
lab exercises.  The tutorial is also available in HTML form
under the www/gmt/doc directory (See 7).

9. Set path
-----------

Make sure users set their PATH to include the directory containing
the gmt executables (BINDIR) if this is not a standard directory
like /usr/local/bin.  You should now be able to run gmt programs.

10. GMT supplemental Code
------------------------

GMT users elsewhere have developed programs that utilize the GMT
libraries and produce PostScript code compatible with the rest of
GMT or simply perform data manipulation.  In addition, misc.
code developed by us depend on GMT libraries.  Such code is available
in the file GMT3.3.1_suppl.tar.gz (or .bz2).  Note that these programs
are not part of the official GMT package and were not all developed by
us.  Please DO NOT send us bug reports or other inquieries
regarding these programs.  The README files in the tar archive
indicate where to direct such requests (if applicable).
Currently, the supplemental archive include the directories:

	cps	- Compaction of plot, scripts, and data sets
		  into a Complete PostScript file.
	dbase	- Data extractor for global gridded data sets such
		  as those on CD-ROM from NGDC.
	imgsrc	- Data extractor for Smith/Sandwell altimetry grids.
	meca 	- Plotting of focal mechanisms, velocity arrows,
		  and error ellipses on maps.
	mex	- Matlab mex files for grdfile i/o.
	mgg	- Programs for handling and plotting of MGD-77 data.
	misc	- psmegaplot and makepattern.
	spotter	- Plate tectonic application (hotspotter & backtracker).
	x2sys	- Track intersection (crossover) tools.
	xgrid	- X11 editor for grdfiles.

Place the GMT3.3.1_suppl.tar.gz (or .bz2) file in the GMT main directory
and gunzip/tar out the contents.  You may have to modify
makefiles or start scripts.  Each subdirectory will contain *.man files
(Unix man files) and *.html files (HTML-version of man pages).  You must
manually place these in the same directories as that of the main GMT
distribution.

11. Example Scripts
------------------

	A complete set of the example scripts used to create the
20 example plots, including all necessary data files can be
found in the GMT3.3.1_scripts.tar.gz (or .bz2) archive.
Copy this to your gmt directory and install there if you would like
these scripts.

12. Misc
--------

Before running programs, there are a few things you should do/know:

  - Read carefully the documentation for the gmt system.  This can be
    found as both PostScript and HTML files in the www/gmt/doc directory.
    The successful operation of gmt-programs depends directly on your
    understanding of how gmt "works", its option lists, I/O, and composite
    plot mechanisms.  Then, before running individual gmt programs, read
    the associated man page.
    
  - Do not confuse the GMT-system with the GMT-database that was
    initiated at Lamont-Doherty Earth Observatory.  These
    marine geophysical data files (Gravity, Magnetics, Topography)
    are NOT distributed with the GMT-system!  [However, programs that
    deal with gmt-files can be found in the supplemental tar archive.

13. A reminder
--------------

   If you think it is appropriate, you may consider paying us back
by including our latest EOS article (Wessel, P. and W. H. F. Smith,
New, improved version of the Generic Mapping Tools released, EOS Trans.
AGU, 79, 579, 1998, and our Geophysics article on the gridding algorithm
in surface (Smith, W. H. F. and P. Wessel, Gridding with continuous
curvature splines in tension, Geophysics, 55, 293-305, 1990) in the
reference list of your future publications that will benefit from the availability of GMT.

14. Software support
--------------------

   You haven't bought anything so you cannot expect full service.
However, if you find a bug in any of the programs, please report
it to us (gmt@soest.hawaii.edu) rather than trying to fix it yourself
so that we, and through us, other users may benefit from your find.
Make sure you provide us with enough information so that we can recreate
the problem.
	Please fill out and mail us on of the registration licences which you
can find as PostScript files in the doc directory.  Alternatively,
pleas register via the GMT web page (www.soest.hawaii.edu/gmt).
	Two mailing lists of interrest to GMT users are available:
gmtgroup@soest allows us to notify registrered users in the event of bugfixes
and/or new releases.  A separate mailing list (gmthelp@soest.hawaii.edu) exists
for GMT users who have questions about GMT intallation and usage.  If you want
to subscribe to one or both of these mailinglists, send a message to
listserver@soest.hawaii.edu that contains one or both of the commands

subscribe gmthelp <yourname, not email address>
subscribe gmtgroup <yourname, not email address>

You may post messages to gmthelp while gmtgroup is more of a one-way street
for us to inform users of bug fixes and upgrades.

15. Ordering the GMT package
----------------------------

Should you or someone you know without net-access need to obtain GMT:  We charge
a fee of $100 for this service which includes everything (media, handling,
postage).  The reason we charge money is that we really have no spare
time to do this job ourselves.  That's why we prefer you obtain the code
over the network.  Send requests for media to:

	Paul Wessel
	School of Ocean and Earth Science and Technology
	University of Hawaii
	1680 East-West Road
	Honolulu, HI 96822 USA

Include return address, check for US $100 payable to: "University of
Hawaii" and drawn on a US bank to cover cost of tape, handling, and
postage, and specify one of:
	
		- CD-ROM (CD-R or CD-RW only, please specify)
		- 4 mm cassette
		- "Exabyte" (8 mm) cassette

See http://www.soest.hawaii.edu/gmt.html for available ftp sites

Good luck!

Paul Wessel, SOEST/UH
Walter H. F. Smith, NOAA/NODC
