      Generic Mapping Tools (GMT) V. 3.4 for OS/2
                     12 December 2001

NOTES ON PORTING
~~~~~~~~~~~~~~~~
Many of the earlier ports of GMT to OS/2 produced staticly-linked
executables. These ports were robust and required few changes to the
Makefiles and associated files supplied with the source distribution.
However, these staticly-linked ports were HUGE; the executables alone,
even after compression with LXLITE, took up over 10Mb of disk space.

Starting with version 3.3.4, I produced a port that relied on the
construction of DLL versions of the main GMT libraries (gmt.lib and
psl.lib). This port is much, much smaller in size: all the DLLs and
the executables take up only 1.2 Mb.

Therefore, I have built version 3.4 only using the DLL versions of
the GMT libraries. The tools provided with EMX, however, are not
especially conducive to the production of the DLLs, primarily due
to the fact that one must provide a module definition file for each
DLL. The names of the external variables and functions that must be
exported from the DLLs created are not easily available, or at
least I don't know of an easy way to create an accurate list of all that
are needed. Therefore, I used the following approach to building the
DLLs.

1. First, I built static (OMF-style) libaries of the two libraries
   required: GMT.LIB and PSL.LIB. The library PSL.LIB is the Postscript
   plotting library; the library GMT.LIB (which depends upon PSL.LIB)
   provides most of the functionality of GMT.

2. Next, I used the ILIB tool from IBM's VisualAge C++ to create listings
   of all the external variables and functions residing in the two static
   libraries. Then, I hand-edited these listings to remove duplications
   and functions that were external to the main library (for example,
   the C run-time functions). This step is laborious; if someone knows of
   a good way to automate such work, I would love to hear about it.

3. Once the list of externals is constructed, it is easy to create a
   module definition file. This file is used as input to the EMX tool
   `emximp' to create import libraries for the DLLs. Once the import
   libraries are created, building the executables is quite straightforward.

I wrote a special version of the GMT Makefile to automate some of the steps
in producing the port. Because of item (2) above, however, the Makefile
cannot create all the files needed for building GMT. Here are the main
steps, using the Makefile (named Makefile.os2). Note that I use Gnu Make
rather than NMAKE to process the Makefile.

4. `make -f Makefile.os2 libs' (creates GMT.IB and PSL.LIB).

5. Use ILIB, etc [as described in (2) above] to produce module definition
   files gmt.def and psl.def.

6. `make -f Makefile.os2 dlls' (makes the DLLs, namely gmt.dll and psl.dll).

7. `make -f Makefile.os2' (makes all the executables).

8. `make -f Makefile.os2 install' (installs the executables).

At the moment, you must manually copy gmt.dll and psl.dll into a location
in your LIBPATH.

I provide the following files, which are needed in order to rebuild from
sources:

    netcdf_import.lib  -  Import library for the netcdf DLL.
    fdlibm_import.lib  -  Import library for the fdlibm DLL.
    gmt_import.lib     -  Import library for the main GMT dll (gmt.dll).
                          (Can be reconstructed using emximp and gmt.def)
    psl_import.lib     -  Import library for the Postscript dll (psl.dll)
                          (Can be reconstructed using emximp and psl.def)
    Makefile.os2       -  Makefile referenced above.
    makegmt.macros.os2 -  Macro definitions used by Makefile.os2
    psl.def            -  Module definiton file for the Postscript library.
    gmt.def            -  Module definiton file for the mail GMT library.
    AddOrdinals.pl     -  Simple Perl script to add ordinals to a list
                          of externals; the output of AddOrdinals.pl is
                          used as the list of exported names in the module
                          definition files.
    gmt_notposix.h     -  Header file used for non-posix complying platforms
                          (such as Win32 or OS/2).
    gmt_nan.h          -  Header file needed for building. This file can also
                          be created directly from Makefile.os2.



Allen Cogbill
Geophysics Group
Los Alamos National Laboratory
ahc@lanl.gov
