GMT Subversion Services

Introduction

As of July 27, 2011, the entire gmt4 package and supporting scaffolding is under version control using the subversion program. Two kinds of access are given: Read-only and read/write. Read-only lets you check out the latest GMT 4 tree, while read/write allows you to check back in your modifications. Both types will allow you to completely recreate the gmt4 directory tree that the developers are using and you may even generate the web-examples and tar archives on your own machine.

Requirements

To take full advantage of subversion access you need to have several utilities installed in your default path. While most Linux systems come with all of them preinstalled (assuming you installed all the utilities), commercial Unix workstations or Mac OS X usually do not and you must install them separately, either from source of from premade packages (Mac OS X user must first install the developer tools and X11 - the rest can be obtained via fink). The tools are:

svn. You will not get far if you do not have svn on your system.
gnumake. You will need to be using a gnu-compatible version of make. This may be called make, gnumake or gmake on your system.
ghostscript. Needed to generate bitmaps from PostScript files.
netcdf v4. Both netcdf library and include file is needed (i.e., -devel package).
GDAL GDAL is an optional but recommended package (lib and include) (i.e., -devel package).
pdflatex. Needed to generate the PDF Documentation from the GMT Latex
htlatex. Needed to generate the HTML Documentation from the GMT Latex files.
autoconf. This tools is needed to generate the configure scripts from the configure.ac templates. It requires the m4 macro pre-processor.

See links below to obtain any of these utilities.

Initiation of subversion service

The initial process of starting to use gmt4 with subversion is done by the utility cshell script newgmtguru. However, here we will go through the steps manually to indicate the process.

Make a GMTdev directory. This directory will contain all GMT development, including the main GMT directory tree (in which you can work on GMT programs) as well as previously released versions, e.g., the GMT4.5.7 release. Those directories should be treated as read-only; all your GMT-related development should take place in the GMT tree. Change directory to where you want to place GMTdev and type

mkdir GMTdev

Then cd into the GMTdev directory.
Checkout GMT 4. To check out GMT 4 via subversion, run
svn checkout svn://gmtserver.soest.hawaii.edu/gmt4/trunk gmt4
or, for gurus who wish to have access to test branches etc., run
svn checkout svn://gmtserver.soest.hawaii.edu/gmt4
which will start copying the entire gmt4 tree from the GMT server - this can take a while depending on where you are and traffic load. It is a good time to go for lunch. Barring any errors or network troubles you should have everything the GMT gurus have access to in your local directory. Note: Those who prefer to use git instead of svn can mirror gmt4 to a local git repository:
git svn clone svn://gmtserver.soest.hawaii.edu/gmt4/trunk gmt4
In the following we assume you did a "trunkless" checkout; if you did not then remember to include /trunk after gmt4 in any cd commands below.
Tune your environment. There are a few parameters that need to be set before you can run any make operations in GMT. Hopefully, this process can be simplified as more gurus come online. For now, cd into gmt4/guru and copy the guruenv.csh to yourname_env.csh and edit the latter file. The file has instructions for what you need to do. When done, add the relevant section to your .cshrc or .tcshrc files and source them so the changes will take effect. Next, copy gmtguru.macros.orig to gmtguru.macros and edit the latter file. Again, follow instructions on what to do.
Get Coastlines data sets. Because the GSHHG coastline files (*.nc) are themselves created from more primitive forms and this process is not in subversion, you must install the coastline files separately. Get the coastlines by anonymous ftp simply by running

make get_coast
in the top gmt4 directory.
Do the guru thing. If you are with me so far, you are ready to compile GMT. I recommend a full shake-down which is done by running
make prepare
This command will run svn update (in case something has changed on the server), create configure scripts, run them, compile and install gmt4, make man pages and documentation, and convert to HTML. It does everything short of creating a version link and tarring of the release. You will need to look at GNUmakefile for other things you can do. Or otherwise simply type
make

How to contribute changes

If you make any changes (e.g., fix a bug or correct a typographical error) you will want to make sure it gets updated on the GMT server. How this is done depends on your access:

Anonymous access. Since you do not have write permission you must email the patch or the fix to someone who does. Most likely you will send it to gmt@soest.hawaii.edu, and we will merge your change into the subversion database.
Write access. With write access you can upload the changes yourself. You need to know quite a bit more about subversion than the anonymous users does since when you try to commit your change there may be a conflict. Conflicts arise when somebody else has checked in an updated version of the file you are editing before you check in yours. When you do, subversion compares your submission to its current version and it if is more recent that your starting point it may find a conflict and ask you to resolve it manually. Usually this is not too hard as subversion will mark the sections in question with <<<<<<<<<<<<<<<< and >>>>>>>>>>>>> markers. Make the changes if it is obvious or submit manually to gmt@soest.hawaii.edu if in doubt. To commit changes to the subversion archive, you run (as an example)
svn commit -m "Fixed error in -G option"
If successful, the subversion repository in Hawaii is updated and any future subversion update commands from anywhere will obtain the revised grdview.c file. For more info, you need to read parts of the subversion (see references below).

References

Version Control with Subversion, 2nd ed., by C. M. Pilato, B. Collins-Sussman, B. W. Fitzpatrick, O'Reilly, available online from HERE.
You can find source, binaries, and information about autoconf at the autoconf page; it has a link to the GNU site as well. The latter has m4 if you need that too.
For ghostscript and related programs, goto the Ghostscript home page.
If you need to get pdflatex, try searching CTAN.