User:Xaxafrad/GMT

Installing GMT for dummies? A GMT primer?

Introduction

Why do you want to run Paul and Walter's Generic Mapping Tools? (you can answer that on the talk page) I'm kind of a history buff, so when I read about some of the events that have transpired throughout history all across the planet I get some transformational visions of animated maps in my head, see Maps of Kuwait for a rudimentary glimpse. I'm currently running GMT under the Xubuntu flavor of GNU/Linux, on a Sony Vaio dual booting with Windows XP.

Preparation

This section details installation and some usage notes for the programs required by GMT. They are listed in order of depth of immersion into the UNIX environment. You can install a full blown operating system alongside Windows and choose one or the other when you turn your computer on (the Linux option). You can install an emulator and run a UNIX like a DOS box (the Cygwin option). You can install a relatively transparent layer of UNIX libraries and run BAT files (the SFU option)

Using a Linux OS

Download one of the many Linux distributions. There are as many distros as there are individual requirements; you'll find yours eventually. I went with Xubuntu because it's simple to install and fits on 1 CD; you download the image file, burn the CD, boot from the CD on the target computer, and run the install program (also keep in mind that any Linux commands I give you are coming from me using Xubuntu; I have no idea how different any other distro is). During the installation process, you'll want to take care not to inadvertantly format a pre-existing hard drive during the partitioning step (maybe that only applies to dual booters like myself). GMT relies on certain UNIX tools to perform some functions. As I haven't extensively tested GMT under Xubuntu yet, I don't know if all the necessary packages are there, but they probably are (with the exception of Mex and/or Matlab).

As part of the post-installation, I configured the bootloader to use my old Windows OS as the default option, as well as shortening the response timer from 10 to 3 seconds (it's a shared laptop). To do this (under Xubuntu, and most other distros), click on "Applications", then either "Run Program..." or "Terminal". The Terminal is a Bash shell, similar to the MS-DOS command prompt. You should get familiar with some UNIX tools and their switches and options (there's other guides and tutorials for that). Enter "gksudo mousepad /boot/grub/menu.lst". Let's examine this command: "gksudo" is program which compliments "sudo", that's short for "superuser do" (I'm not sure what the "gk" prefix signifies, but I know it's for editing text, while "sudo" is for executing other programs). These two programs allow you to perform administrative functions without switching into a full-blown superuser mode. The "mousepad" program is the only text editor I'm aware of that shipped with Xubuntu, otherwise "gedit" or "nano" were the oft-encountered examples. The final part of that command is simply the filename, using an absolute directory reference. At last, the part where I tell you to edit something: near the top you'll find few lines that don't begin with #, and only one that begins with "default", make a mental note. Now, scan near the bottom of the file to find what your boot options are. There should be several blocks of text, lines beginning with the words "title", "root", "kernel", etc. Each block, from "title" to "boot" is one option, and they begin counting with 0. So, find out which option you want as your default, and change the line at the top to match. I also changed the "timeout" line, but that's even more optional.

If you're dual booting, you may want to share files between your OS's. What I present here isn't the only method to accomplish that, but it's said to be safest due to file system incompatibilities. If you're using Windows XP, right click on "My Computer", then click on "Manage". Under "Storage", click on "Disk Management" (otherwise, you'll need to use a third party partitioning program). Don't delete anything you're not sure about: you can lose entire hard drive's worth of data from this screen! Hopefully you'll have a drive marked bright green for free space, otherwise you'll have to make room by deleting a partition. The goal is to see a "Create Partition" option when you right click on a volume, which will bring you to the partition wizard. While here, be sure to set the FAT32 filesystem option. If the computer manager tool has the ability to resize an existing partition, please let me know (because I couldn't find it); resizing is preferable to deleting. Now switch to your Linux OS and enter the following commands (copied from here):

1. Create the directory that serves as the mount point (e.g. "mkdir /osshare"). The mount point is the location in the filesystem where you want this FAT32 partition to appear.
2. Put an entry in the "/etc/fstab" file for the share partition. Be very careful in editing this file, as it's used at system startup! For an example: "/dev/hda6 /osshare vfat umask=000 0 0". You can find the proper "/dev/hdaN" number in "/boot/grub/menu.lst" file. The umask option determines the permissions for all filesystems on the partition.
3. Upon your next reboot into Linux, the share partition should get mounted automatically. If you wish to mount the FAT32 partition immediately, use the mount command, e.g.: "mount /osshare"

(Note: I had to add "gksudo" and "sudo" in front of those commands: "gksudo mousepad /etc/fstab", "sudo mount /osshare", etc) (More notes: UNIX is case sensitive. Don't create directory names with spaces in them, some programs will barf errors at you if you do that.)

If you're going to be doing any compiling, you'll need to explicitly install a compiler. Under the Applications menu, select System, then Synaptic Package Manager. You can find "gcc" and "make" in the Development section. Finally, click on Apply. If you can't find either program, you'll have to add a repository from under the Settings menu (the original install CD also acts as a repository if, like me, your Linux OS doesn't have internet access).

Using the Cygwin shell

To use Cygwin, it's recommended that you be running Windows NT, 2000, XP, or Server 2003, but limited success has been reported with Windows 95 and 98. Further, any UNIX based programs you'd like to run should be compiled first, although I've been told pre-compiled options are available. That said, head to cygwin.com and click on the "Install Cygwin Now" button. You'll begin downloading a tiny setup program which, when run, will ask how you want to proceed. You'll probably want to install from the internet. Most of the default options will work fine. I was told to be sure the UNIX text option was selected. Also, you may have to try more than one ftp server. When you get to the package selection screen, I would also suggest going into the "Editors" category and installing an extra text editor or two (the default, "ed", just gave me a question mark at whenever I typed anything at it, maybe I invoked it improperly), "nano" was the most intuitive of the ones I tested. If you're going to compile things yourself, you'll also need the "make" package from the "Devel" category. When it's done downloading and installing, you should have a working UNIX shell available to you.

Using Microsoft's Windows Services for UNIX

Go to Microsoft's homepage, download, and follow their directions. You should now be able to use the pre-compiled files and DOS-based commands to generate maps (currently untested by myself).

Installing netCDF

netCDF is used by GMT as a basis for interacting with file formats. This gives GMT an enormous range of data sources to use for plotting a map. Always install this before installing GMT. They have fairly concise install instructions, but I'll paraphrase them here for completeness' sake (although I still recommend reading any and all instructions that come with anything; after all, you don't know what I may or may not be leaving out).

If you want to try the precompiled binaries for netCDF, just select the one that matches your OS, download, extract, and place the files in the proper directory. Xubuntu uses the Linux 2.6 kernel, while WinXP would want the Windows DLL. For Windows, the proper directory would be either C:\Windows\System or C:\Windows\System32. netCDF can be installed anywhere under Linux, though you have to do the equivalent of editing the autoexec.bat file. I think these two pages do a good job explaining the nuances of the Bash start-up process and how to set environment variables. Under Xubuntu, it's as simple as entering the command "gksudo mousepad /etc/bash.bashrc" and adding the line "NETCDFHOME=/path/to/netcdf; export NETCDFHOME" near the bottom (to do this in Cygwin, enter "nano /etc/bash.bashrc" and add the line).

To compile netCDF yourself, grab one of their tar files (or the netCDF archive provided on the GMT mirrors) and extract the contents wherever you want it installed (you may want to scan through the README file at this point). Open up a terminal and cd to the newly created netCDF /src directory, then enter "./configure", then "make check", and finally "make install". You also have to set the variable NETCDFHOME as described above. Please tell me if you have problems compiling netCDF; in all my trials, it has so far gone off without a glitch, though I could probably only refer you to [www.google.com Google] if you have a setup markedly different from mine.

Installing GMT in UNIX

Now, keep in mind I didn't have internet access on the machine I was installing GMT on under a UNIX OS, otherwise I'd have instructions for using the interactive install script around this spot.

To do-it-yourself, grab the files from the following list from a GMT mirror:

Required:

• GMT_src.tar.bz2 Source code only, no documentation
• GMT_share.tar.bz2 Shared run-time support files
• GMT_coast.tar.bz2 Standard resolution coastline data
• install_gmt Bourne shell install script (located in root directory on mirror)

Optional:

• GMT_tut.tar.bz2 Tutorial data sets
• GMT_scripts.tar.bz2 Example directory with scripts and test data
• GMT_full.tar.bz2 Full resolution coastline data
• GMT_high.tar.bz2 High resolution coastline data
• GMT_suppl.tar.bz2 GMT Supplemental programs that link with GMT

Documentation:

• GMT_pdf.tar.bz2 PDF version of cookbook, tutorial, and man pages
• GMT_man.tar.bz2 UNIX man pages for GMT
• GMT_web.tar.bz2 Web (HTML) version of docs and man pages

Before anything else, it's advised to set the GMTHOME variable in the /etc/bash.bashrc file at this point (GMTHOME=/path/to/GMT4.1.4). Then extract all the contents into the common directory (except the three coastline archives, which need to be extracted directly to /GMT4.1.4 rather than whatever your install directory is). This is the part where you read the README file that came with the GMT files. When you're ready, open a terminal, cd to the /GMT4.1.4 directory and enter "./configure", "make" (or "make all", I'm still not sure what the difference is), "make install", "make install-data", "make install-wrapper", "make clean", "make install-man", "make install-www". Finally, enter "gksudo mousepad /etc/bash.bashrc" and add the line "PATH=$PATH:/path/to/GMT4.1.4/bin; export PATH". After saving and opening a new terminal, you should be able to call any of the Generic Mapping Tools. The supplemental programs can be installed by typing "make suppl" followed by "make install-suppl" in the GMT4.1.4 directory. You can run the example scripts by cd'ing to /GMT4.1.4/examples and entering "bash do_examples.sh". To see the results, look in each example directory for example_NN.ps. (I'll bet there's a grep-like command with a couple pipes and maybe a 2 or 3 line for loop that could copy all the *.ps files from sub-directories into a single location, but I would have to read at least 5 or 6 tutorials over the next 2-3 hours to figure out what it is.)

Installing GMT in Cygwin

To compile GMT from the source files, make sure /etc/bash.bashrc has GMTHOME set properly, then follow the regular UNIX instructions.

Alternately, these files contain the precompiled executables: Required:

• GMT_exe.zip All executables
• GMT_share.zip Support run-time files (patterns, cpt)
• GMT_coast.zip Basic GSHHS coastlines

Optional:

• GMT_high.zip High resolution coastline files
• GMT_full.zip Full resolution coastline files
• GMT_tut.zip Tutorial data sets
• GMT_scripts.zip Example scripts and data
• GMT_suppl_exe.zip Supplemental executables

Documentation and source code:

• GMT_web.zip HTML versions of all documentation
• GMT_ps.zip PS version of documentation
• GMT_pdf.zip PDF documentation and Unix man pages
• GMT_man.zip Unix man pages for GMT
• GMT_src.zip All source code
• GMT_suppl.zip Supplemental program source and docs

Once you have what you need, you'll need to extract all the contents into a common directory. If asked to overwrite anything, always say yes.