Migrating from an Earlier Version

Many longtime GMT users have older scripts written in GMT 4 and even in GMT 5 that may not work immediately in GMT 6. This reason is not that the syntax of the commands cannot be recognized (“GMT 6 shall be compatible with GMT 4 and GMT 5 syntax”), but because the old scripts do not call the GMT module via the only installed program called gmt. Because of problems with “namespace pollution” (there are many open source programs called surface and triangulate and it is not possible to place them all in /usr/local/bin, for instance) the Linux distributions usually will only build the gmt executable and we access all modules via this single program, using the syntax gmt module [options].

There are several ways to address the lack of using the gmt program:

  1. If you are building GMT from source (either from a checked-out GitHub repo or the source distributed via the tarballs, you can edit a parameter in the file cmake/ConfigUser.cmake and set GMT_INSTALL_MODULE_LINKS true. This will add symbolic links called blockmean, pscoast, grdimage, etc. that all point to the gmt executable. Your old scripts will now work without the leading gmt program for each module command.

  2. You can run the script gmt_links.sh which lives in the share/tools directory (run gmt --show-sharedir to find the path to share, then look in tools). If your GMT installation was installed outside your user directory you will need to run the script as root. It will create all the module links to allow users to run modules directly. You can run the link-building script this way:

    $(gmt --show-sharedir)/tools/gmt_links.sh

    which will report the status of any existing links. Add the argument create or delete to make actual changes.

  3. If your default shell is bash or similar then you can call another share/tools script called gmt_functions.sh this way:

    source $(gmt --show-sharedir)/tools/gmt_functions.sh

    It will instead create bash functions with the names of the modules and thus let you run blockmean, etc. without a leading gmt invocation.

  4. If your default shell is csh or similar then you must instead call gmt_aliases.csh which works similarly to the gmt_functions.sh but for csh:

    source `gmt --show-sharedir`/tools/gmt_aliases.csh

    Both of these two solutions can be implemented via your login setup so they are always set once you log in to your computer or open a new terminal window.

  5. Finally, if the old script is important and is expected to be used in the future, maybe it is worth the effort to migrate the script code to the stricter default GMT 6 syntax by starting each GMT command with gmt. If so, also consider to simplify the script (assuming if is a plotting script) by rewriting it in GMT modern mode.

If your script is particularly old (GMT 3) it may also use a deprecated syntax that GMT no longer recognizes. If that is the case then you should consult the documentation for the old version (if you have access to it) and compare with the new documentation to determine the required changes. Error messages issued by GMT may help in that regard. Also note that GMT may issue compatibility warnings or errors when it detects deprecated syntax, provided GMT_COMPATIBILITY is set to the later major version number and GMT_VERBOSE is set to compatibility. If the compatibility level is low enough (e.g., 4) then the obsolete syntax will be correctly parsed, but you may wish to take the opportunity and update the syntax when these issues are reported.