Installing GMT on Cygwin
Val Schmidt
21 Feb 2003
These notes document how to install the Generic Mapping Tools on Windows XP Pro with the Cygwin Linux emulator installed. It was a trial and error process with plenty of mistakes, but I think I’ve boiled down to the nitty gritty here. If it doesn’t work smoothly for you give me a holler and if I can’t help directly I’ll give some suggestions for where to go for help.
So lets start with what I’ve got.
The System:
This is a Windows XP Pro installation with all service packs, hot-fixes, etc. installed (Feb 03). On top I have installed cygwin using their standard “setup.exe” executable. [see www.cygwin.com]. I have pretty much installed all of the available packages for cygwin, as I use it for lots of things, however I’m sure this can all be done with much less. I’m using the bash shell and run either the rxvt X terminal (which is part of the cygwin install and has been ported to Windows such that it doesn’t require a running X Windows [i.e. you can start if from a c prompt or .bat file]), or I start X-Windows with “startx” at the cygwin prompt.
To date, Window Maker is the default window manager in cygwin. I am not particularly fond of Window Maker, but I am something of a novice with regard to X-Windows and have not seen anything sufficiently “dumbed” that would allow me to change it to something else.
I have created the directory /usr/local/gmt to hold the gmt files and executables.
GMT:
The Generic Mapping Tools is a very sophisticated software package for mapping, and manipulating very large data sets. It is often used for satellite and sonar imagery to create nice looking maps and charts. The details can be found at http://gmt.soest.hawaii.edu/ .
The simplest way to install GMT is to use the automated installation script and parameter file that is generated from your answers to a handful of questions posed here: http://gmt.soest.hawaii.edu/gmt/gmt_install_form.html
Our strategy is to use the automated script as much as possible and modify parts here and there, as the script doesn’t work natively (lessons learned the hard way).
In particular:
1) The standard releases of NetCDF3.5 won’t compile under the latest c++ compiler provided with cygwin (Feb 2003). So we’ll have to go get the beta netcdf3.5.1 release manually and tweak the gmt install script so it works.
If you’re interested in the problem with netCDF…
This error has been reported. You can see it at
http://www.unidata.ucar.edu/glimpsedocs/ghnetcdf.html
Enter "friend declaration" in the search-box.
2) If your windows login name has a space (e.g. “Val Schmidt”) the automated ftp scripting will fail.
So lets get started…
NetCDF Compatibility Workaround:
Like I said before, the “current” version of netCDF (3.5) won’t compile with the latest c++ compiler provided in the cygwin package. So rather than allowing the GMT install script retrieve the netCDF files for us, we have to get them ourselves. So click below to retrieve a copy:
ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-beta.tar.Z
Save this in /usr/local/gmt (your GMTHOME).
Unfortunately, the GMT install script won’t recognize beta versions of the netcdf archive. So you have to rename the compressed tar file “netcdf.tar.Z”. That’s it for netCDF, the GMT install script will do the rest.
GMT Install Parameter File:
So now lets retrieve the GMT install script. Right click this automated installation script and select “Save Target as…”. [If this link doesn’t work, it’s probably just been moved. You can go to http://gmt.soest.hawaii.edu and look for it.]
Save the “install_gmt” file in /usr/local/gmt/ (or your GMTHOME).
NOTE: Windows will probably append “.txt” to the file name. To avoid confusion I renamed it “install_gmt.pl”.
Now go to the parameter file Q/A page and answer all the questions. The answers to these questions are key, so I’ve provided my answers below to guide you [with my comments in green]:
A. Basic Requirements:
- You have access to the Bourne shell (Bash will also work).
- You have write permissions in all directories you specify below.
- You have obtained and saved install_gmt, the GMT install script.
1. Select archive format:
gzip
format
bzip2
format
Either
one, I don't care
Note: The *.bz2 files made by bzip2 are generally much smaller than the corresponding *.gz files. Type bzip2 -h to determine if you have bzip2 installed. Source code and executables for bzip2 are available from the bzip2 site. The default option will determine if you have bzip2 or gzip and pick bzip2 if possible.
2. Select default units in
GMT:
SI
units (cm)
US units
(inch)
Note: This used to be a choice that affected the compilation of GMT. However, since version 3.3.2 this selection is a run-time selection, meaning you can reverse it at any time. The present choice is simply a convenient way to set the default units for all users of your GMT installation (see gmtdefaults man page for how to change this choice at a later time). Individual users can always override the default with gmtset MEASURE_UNIT cm|inch
3. Select default
PostScript output format for GMT:
Freeform
PostScript (PS)
Encapsulated
PostScript (EPS)
Read the note below and pick what seems best for you. PostScript is more flexible but isn’t a really common format on Windows platforms. A free version of Ghostscript and Gsview (both for Windows) can be had at http://www.ghostscript.com/. Highly recommended.
Note: GMT-produced PostScript files will by default use the printer configuration command setpagedevice to set image area (i.e., paper size) and to select specific paper trays, including the manual tray (e.g., when making overhead transparencies). Encapsulated PostScript files (EPS) are not allowed to use this command. Some older PostScript previewers (like Sun's pageview) do not understand setpagedevice, while more up-to-date previewers like GNU ghostview does. The parameter PAPER_MEDIA is used to choose between EPS and PS output and this can be changed at run-time with the gmtset command. Thus, this radio button only affects the initial default selection. Choose EPS if you do not need to worry about paper trays. Choose the default PS if you need the extra flexibility offered. Please read the gmtdefaults man page and Appendix C for more details.
4. Select POSIX Advisory
File Locking:
YES. Use file locking
NO.
Do not use file locking
Note: GMT passes information about
previous GMT command-line options to future GMT commands via a hidden file in
the current directory (.gmtcommands). To avoid that this file is updated by
more than one program at the time (e.g., when you connect two or more GMT
commands with a pipe) we use POSIX advisory file locking on the file.
Unfortunately, some versions of the Network File System (NFS) have not
implemented file locking properly. We know this to be the case with Linux
pre-2.4 kernels when mounting NFS disks from a Sun server. If this is your
case, you must turn file locking OFF, and avoid using the GMT shorthands in
commands that are piped together.
B. NetCDF Setup
1. Select the appropriate
netCDF library option:
netCDF
3.5 (or 3.4) is already installed
Please
get and install netCDF 3.5
I
already have the netcdf.tar.Z archive, just install it for me
Give full pathname to the netCDF directory: 
Here since we’ve already downloaded our “netCDF-3.5.1-beta10” version and named it “netcdf.tar.Z” we just ask the install script to install it for us and give our GMTHOME directory so it can find it. It’s important NOT to decompress the archive yourself as the install script expects the compressed archive.
Note: In either case you must fill out the directory name. If you already have netCDF then give the directory it resides in; if you need to install netCDF then give the directory you intend to install it. You can leave it blank if you have defined $NETCDFHOME to be the directory where you installed netcdf.
C. GMT Setup
1. Select the FTP site
nearest you:
Pacific
(SOEST, University of Hawaii [GMT Home], Honolulu, Hawaii, USA)
North
America (NOAA, Lab for Satellite Altimetry, Silver Springs, Maryland, USA
South
America (IAG-USP, Dept of Geophysics, University of Sao Paulo, Brazil)
Europe
(Inst for Geologi, University of Oslo, Norway)
Asia
(ISV, Hokkaido University, Sapporo, Japan)
Australia
(Charles Sturt University, Aubury, Australia)
No
FTP, archives already obtained
Note: Download times are shorter when you pick a site that is physically closer to you. If you already have downloaded the files and simply wants to use the script to reinstall, select the last option.
2. Select normal [Default]
or passive ftp transmission:
Normal ftp
passive
ftp
Note: Normal ftp from a client will make the server connect to the client. This may not work if you are behind a firewall. In that case you may want to select passive ftp mode.
3. Select the components you want (gzip/bzip2 sizes indicated):
I selected
everything but you may only want or need pieces parts. I leave that to you.
GMT
source code (0.7/0.6 Mb, the main GMT programs, required for minimal install)
GMT
support data (4.0/3.7 Mb, Crude-, low-, and intermediate-resolution coastlines)
GMT
Documentation 1 (4.2/3.1 Mb, PS versions of Cookbook and Tutorial)
GMT
Documentation 2 (6.8/6.9 Mb, PDF versions of Cookbook and Tutorial)
GMT
Documentation 3 (0.12/0.09 Mb, UNIX man pages)
GMT
Web Docs (1.9/1.8 Mb, HTML versions of all GMT Documentation)
GMT
Tutorial (1.4/1.0 Mb, Tutorial data sets)
GMT
Example Scripts & Data (4.2/3.1 Mb, required to run test examples)
GMT
Supplemental Archive (0.6/0.5 Mb, see section C.10 below for details)
GMT
High-resolution coastlines (10.7/8.6 Mb)
GMT
full-resolution coastlines (47.1/28.8 Mb)
J.
Shewchuck's fast triangulation routine (0.11/0.09 Mb, faster, but not covered by
GNU License)
Note: The first two are required for a simple GMT install (in order to run all the examples in the cookbook). Many users will also prefer to get the higher resolution coastline files for map making in smaller areas. The example scripts are required if you want to run the test suite. The tutorial component is needed to run the tutorial examples. Finally, you may want to get the optional but faster triangulation routine although it is not distributed under the GNU Public License. For-profit organizations should first inspect Shewchuck's license. Make sure you remove old GMT *.bz2 or *.gz archives from the working directory before you run the script; otherwise the script may decide that it does not need to ftp new versions of those archives.
4. Select library build
type:
Static Libraries
Shared
(dynamic) Libraries
The static libraries option is much safer with regard to incompatibilities.
Note: The GMT libraries can be made static
or shared. The main benefit of using shared (dynamic) libraries is
significantly reduced executable sizes (50-70% savings in disk space). The GMT
install procedure knows how to make shared libraries under Linux, FreeBSD,
NetBSD, SunOS, Solaris, HPUX, OSF1, and IRIX. For other systems capable of
generating shared libraries you must manually configure the makegmt.macros
file. If you have no preferences or no idea what to do on an unlisted system,
select the default static libraries.
5. Select the C compiler
you want to use:
Note: The default cc should work unless
you are on a system with several C compilers. E.g., you may run Solaris and
have purchased Sun's compiler but have also installed GNU gcc. To ensure you
get the GNU you should select gcc. If your C compiler has another name or lives
in a strange directory not in your path, please select "other" and
enter the value for CC below.
Custom C Compiler: 
6. Select the make program
you want to use:
Note: The default make should work unless
you are on a system with a weird make utility. GNU make works best, and some
Sys V makes have problems. If you have make problems, use GNU make (assuming it
is installed): Select "other" and enter the path for make below.
Custom make program:
7. Select GMT final destination directories
It looks
like I forgot to specify anything here but I didn’t. I have learned the hard
way that the default places for things are best and that trying to give specific
places each part can result in an unusable mess and a failed installation. So
I recommend leaving these blank. Just be sure to run the gmt_install script
from /usr/local/gmt (or your GMTHOME).
Place GMT executables in:
Place GMT libraries in:
Place GMT include files in:
Place GMT data resources in:
Place GMT man pages in:
Give man page section: 
Place GMT web pages in:
Note: The GMT archives will first be
uncompressed, untarred, and compiled in the current working directory where
install_gmt is run. After those steps are successful you may want to copy the
files to more traditional directories like /usr/local/bin, etc. The default
locations are subdirectories bin, lib, include, share, man, and www under
GMT3.4.2 in the current install directory. Note that the man pages will be be
placed in the man/man? subdirectory, where ? is the section specified above, e.g.
"l", giving man/manl, is the default. Do NOT specify the man dir as
man/man?; the section directory will automatically be appended based on the
chosen section unit. Only specify alternative directories if you want to place
the files elsewhere. Make sure the users' search path contains the directory
where you place the executables. The directory chosen for GMT data resources is
accessed by all GMT users via the environmental variable $GMTHOME - all users
must set this parameter in their .login file. The man utility will find the GMT
man pages if the chosen man directory is included in the users' MANPATH
environmental variable. Finally, advise users to add a browser bookmark for the
file gmt/gmt_services.html in the web directory you chose above; that page provides
links to online GMT documentation and man pages (assuming you selected the web
archive in Section C.3).
8. Select default GMTHOME
directory
Default GMTHOME directory:
Note: While the GMT data files will be
placed in the local directory indicated in the previous section (C.7), that
directory may appear with a different name to remote users if a different mount
point is used or a symbolic link is set. If so, you may want to specify a
different value for the default GMTHOME. This is the directory where GMT will
look for the share directory with coastline files if users have not set this
environmental variable explicitly. Leave blank to select the parent directory
of the data resources directory given in C.7 [Default].
9. Alternative coastline
directories
Install
all selected coastline files in $GMTHOME/share
Place
coastline files in several directories
Note: Normally, all coastline files reside in $GMT/share. However, if your disk resources are limited or you are sharing files via NFS or similar mounts, you may want to place the larger files in places separate from where the smaller files reside. The selections below are only used if you chose that way.
Place crude, low, and intermediate coastlines
in:
Place high resolution coastlines in:
Place full resolution coastlines in:
10. Select supplemental
packages to install:
DBASE:
Extracting data from NGDC DEM and other grids
GSHHS:
Global Self-consistent Hierarchical High-resolution Shoreline extractor
IMGSRC:
Extracting grids from global altimeter files (Sandwell/Smith)
MECA:
Plotting special symbols in seismology and geodesy
MEX:
Matlab interface for reading/writing GMT grdfiles (REQUIRES MATLAB*)
MGG:
Programs for making, managing, and plotting MGD77 and *.gmt data
MISC:
Make posters on laserwriters and create bit-patterns
SEGYPROGS:
Plot SEGY seismic data files
SPOTTER:
Plate tectonic backtracking and hotspotting
X2SYS:
Track intersection (crossover) tools (REQUIRES MGG)
X_SYSTEM:
MGG-specific Track intersection (crossover) tools (REQUIRES MGG)
XGRID:
An X11-based graphical editor for netCDF-based .grd files (REQUIRES OpenWin
Xlibs)
Note: The selected packages will only be
installed if you also selected the supplemental tar archive above. The x2sys
and x_system packages require the mgg package, the mex package requires Matlab
(octave users may want to modify it), and xgrid requires various Openwin/X11
libraries.
*Enter Matlab system directory if you selected mex above: 
Note: You can leave the Matlab path blank if $MATLAB is defined in your
environment and points to the correct directory.
11. Complete the operation:
Delete all archives upon
sucessful installation
Run
all example scripts (assumes scripts tar archive was chosen above)
THAT’s IT!
Now, after entering all the information and pressing “Get Parameters” a text file is created and served up to your browser as “install_gmt_form.pl”. This is an unfortunate and misleading name, as the text file created is not, strictly speaking, a perl script, but simply a data parameter file. The executable install script that will use this parameter information for installation was downloaded already, if you remember. Anyway, save this text file to your $GMTHOME, perhaps with a name like “par.d”.
An aside Regarding Two-word Usernames:
Having gotten this far after many starts and stops, I was really excited to try the install. I cranked up the install GMT install script and although it compiled netCDF correctly (Whahoo!), it failed in attempting to ftp the GMT package. The problem was that my user name on my WinXP box is two words (Val Schmidt). While Windows handles this just fine, if you ever think you’ll do anything with a Unix box, NEVER give yourself a two word username. It has caused me more headaches.
To fix this problem I searched through the “install_gmt” script and found the following:
# Set-up ftp command
echo "user anonymous $USER@" > install_gmt.ftp_list
and I edited it to read:
# Set-up ftp command
echo "user anonymous vschmidt@" > install_gmt.ftp_list
To be safe I removed all the files that had been created in the first failed attempt so that I was starting with a clean slate just as before. That is, all that is in /usr/local/gmt is “install_gmt.pl”, “par.d” and “netCDF.tar.Z”.
Installation:
So now we’re ready to get cranking. Both the install script and the parameter file have been moved to /usr/local/gmt and I have, of course, administrative privileges so there should be no permissions hassle. Executing the following will start the installation process.
./install_gmt par.d > install.log > 2>&1 &
It can be monitored with
tail –f install.log
The script will first extract the netCDF archive and compile it. Then it will grab the GMT files, check your system for lots of details, compile the code and install it. Nothing to do but pour a cup of coffee and watch – with your fingers crossed.
Along the way, with the install nearly complete, the script executes several example scripts that can be found in ~GMT3.4.2/examples/. This is quite nice, because it gives you a warm fuzzy that things are all working correctly. Here’s a screen shot of example 17:
When it’s done, the final few lines of the install.log will look like the following:
GMT installation complete. Remember to set these:
-----------------------------------------------------------------------
For csh or tcsh users:
setenv GMTHOME /usr/local/gmt/GMT3.4.2
set path=(/usr/local/gmt/GMT3.4.2/bin $path)
For sh or bash users:
export GMTHOME=/usr/local/gmt/GMT3.4.2
export PATH=/usr/local/gmt/GMT3.4.2/bin:$PATH
For all users:
Add /usr/local/gmt/GMT3.4.2/man to MANPATH
Add /usr/local/gmt/GMT3.4.2/www/gmt/gmt_services.html as browser bookmark
-----------------------------------------------------------------------
You can update your .bash_profile to append /usr/local/gmt/GMT3.4.2/bin to your path declaration. Also add:
export GMTHOME=/usr/local/gmt.
If you use a different shell you’ll know what you need to do.
Although the GMT install recommends updating your MANPATH, I have found that once my PATH is updated (e.g. I’ve either sourced the .bash_profile or on the next login) the man page algorithm is able to find the GMT man pages without my help. However if you’ve already got MANPATH declarations in your .bash_profile or .bashrc files, I think they override the algorithm and you’ll have to add a statement for GMT. Read the man manpage (man man) for more details.
The only thing left to do is to find a post script viewer. See http://www.cs.wisc.edu/~ghost/