NAME

       gmtswitch - Switching between different GMT versions

SYNOPSIS

       gmtswitch [ D | version ]

INTRODUCTION

       gmtswitch  helps  you  modify  your  environment to allow for the switching back and forth
       between several installed GMT versions. It works by maintaining a list of  directories  to
       GMT  installations  in  a file in your home directory, then manipulates a symbolic link to
       point to the GMT directory whose executables we wish to use [The Windows version  works  a
       bit differently; see WINDOWS below].

REQUIRED ARGUMENTS

       None.  If  no  arguments are given you are presented with a menu of installed GMT versions
       from 1 to n and you specify which one you wish to switch to.

OPTIONAL ARGUMENTS

       D      Select the default GMT version. This is the first entry in the ~/.gmtversions file

       version
              Search for a unique match in the ~/.gmtversions file. If  one  match  is  found  we
              switch to that entry; otherwise an error is generated.  where module is the name of
              a GMT program and the options are those that pertain to that particular program.

SETUP

       If you have official versions installed then running gmtswitch the very  first  time  will
       examine  your  hard  disk starting at / and look for directories with GMT4, GMT5, etc., in
       the names. This will fail to find the subversion directories and possibly others you  have
       placed elsewhere.  The fastest way to get up and running is this:

       1.

          Edit/Create ~/.gmtversions and add the paths to all GMT installations
                 you have or care to consider. Each path goes on separate lines and points to the
                 top          dir          of          each          distribution,          e.g.,
                 /Users/pwessel/UH/RESEARCH/PROJECTS/GMTdev/GMT4.5.7

       2.

          In your .bashrc or .[t]csrh or wherever you are maintaining your PATH
                 or  path  variable,  remove any directories you have added that contain GMT, and
                 add the new path $HOME/this_gmt/bin (might be $home for csh users).   Make  sure
                 this  path appears before any others that might contain a GMT installation, such
                 as those used by package managers (e.g., /sw/bin for  fink,  /opt/local/bin  for
                 Macports, etc.).

       3. Make the new path take effect (quit/restart terminal, logout/login, etc).

       4.

          cd to the most recent GMT directory where a gmtswitch version lives,
                 and run gmtswitch with no argument. Select one of the version from the menu.

       5. If in csh you may have to say rehash afterwards.

       6.

          Type “plot -” and the synopsis should tell you that you got the
                 correct  version.  You  can now run gmtswitch from anywhere; try it out and make
                 sure that you can switch between the versions.

EXAMPLES

       Note: Below are some examples of valid syntax for this  module.   The  examples  that  use
       remote  files  (file  names  starting with @) can be cut and pasted into your terminal for
       testing.  Other commands requiring input files are just dummy examples  of  the  types  of
       uses that are common but cannot be run verbatim as written.

       To  switch  to  GMT version 4.5.7 (assuming it was installed as such and not via a package
       manager), try

              gmtswitch GMT4.5.7

       To switch to the default (your top choice), do

              gmtswitch D

       Finally, to select from the menu, just run

              gmtswitch

       and pick the one you want.

BEWARE

       GMT remembers where it was installed the first time and uses that dir to find the  default
       GMT  share  directory.  If you move entire GMT installation after compilation then you may
       have to set GMT_SHAREDIR to point to the top dir in order for things to work. It  is  best
       not to move things after installation.

WINDOWS

       Under  Windows  use  gmtswitch.bat  which  is a batch script that changes the Windows PATH
       variable so that the BIN directory of the preferred version always comes first. To do that
       the batch works in two alternative modes:

       1 - Permanent mode

       2 - Temporary mode

       The  permanent mode makes use of the free executable program “EditPath” to change the user
       path in the registry. It’s called permanent because  the  changes  remains  until  …  next
       change. See

       http://www.softpedia.com/get/Tweak/Registry-Tweak/EditPath.shtml

       Of  course  the  editpath.exe  binary must be in your system’s path as well.  WARNING: The
       path change will not be visible on the shell cmd where it was executed. For the change  to
       be active you will need to open a new cmd window.

       The  second mode is temporary because the path to the selected GMT binary dir is prepended
       to the previous path via a shell command line. This modification disappears when the shell
       cmd window where it was executes is deleted.

       It  is  the  user responsibility to set the contents of the G32_32 to G5_64 below to valid
       paths where the binaries of the different GMT versions are installed Note that it  is  not
       mandatory  to have all four of them in you computer. For the ones you do not have just let
       them pointing to nothing e.g.,

       set G4_64=

       The permanent mode is the default one (but this can be changed. See edit section)  To  run
       in the temporary mode just give a second argument (doesn’t matter what)

       Example usage to set a GMT5 64 bits permanent

       gmtswitch g5_64

       To temporary set a GMT4 32 bits do

       gmtswitch g4_32 1

       Run without arguments to get a “Usage” (for permanent mode)

COPYRIGHT

       2019, The GMT Team.