Open Grid Analysis and Display System Files

Supplemental Libraries (Supplibs)
=================================

Introduction
------------

As features continue to be added to GrADS with each new release, the
number of external packages needed for preparing binary distributions
has been steadly increasing. Recent efforts to package GrADS within
the major Linux distributions have benefited from the package
management inherent in these projects; see for example GrADS Package
in Fedora Extras maintained by Patrice Dumas. However, GrADS is still
primarily released in form of binary distrbutions. Creating these
distributions require careful maintenance of the external packages,
usually as a collection of static libraries, the so-called
/supplibs'. /

Up to GrADS v1.9beta4, developers have maintained pre-compiled tarballs
of the /supplibs/ for the supported platforms, along with sources for
those libraries which needed customization. This software is still
available at COLA's anonymous ftp site
<ftp://grads.iges.org/grads/Supplibs>. Preparing /supplibs/ for a new
platform was an ad-hoc time consuming task, and different platforms had
different versions of these external packages, potentially leading to
non-uniform behavior among these builds.

Starting with GrADS v1.9 an effort was made to collect the source code
for the /supplibs/ in a central repository
<http://opengrads.cvs.sourceforge.net/opengrads/supplibs/>, including a
mechanism for building all the external packages with a single command:
gmake install . Having all the packages on a single repository allows
for a more rigorous configuration management of the /supplibs/, leading
to a uniform set of libraries across the different platforms.

As pre-compiled version of the /supplibs/ become available it is our
intention to make them available on the web to facilitate the task of
building GrADS from sources by developers and end users alike. This
document, however, focus on building the /supplibs/ from sources.

Contents of the Supplibs
------------------------

Currently the following packages are maintained in the supplibs:

    * Package management:
          o Pkg-config 
    * Data format related packages:
          o NetCDF Version 3
          o Udunits Version 1
          o HDF Version 4
          o HDF Version 5
          o Grib2c: Grib 2 client library 
          o Shapelib: shapefile support
    * OPeNDAP suite:
          o libdap: core client/server libraries, in C++
          o nc-dap: NetCDF client library
          o gadap: GrADS specific library for accessing station data 
    * Basic graphics/images:
          o jpeg
          o jasper
          o libpng
          o gd 
          o tiff
          o geotiff
          o cairo
          o pixman
          o fontconfig
          o freetype
    * Graphical User Interface
          o libsx: Simple X widgets, based on the Athena Widgets 
    * Compression:
          o zlib
          o szlib: for reading HDF files only (not used for output) 
    * Miscelaneous
          o curl (needed by libdap, usually built /without/ openssl)
          o xml2 (needed by libdap)
          o sunrpc (only needed for building libdap on cygwin) 


Tested Platforms
----------------

Although these are not necessarily supported platforms for GrADS, the
/supplibs' are known to build in the following platforms:/

    * Linux
          o i686
          o x86_64
          o ia64 (Altix) 
    * Mac OS X (Darwin)
          o Intel
          o PowerPC 
    * Windows (under cygwin)
    * SGI IRIX64
    * FreeBSD 6.3 and 7.0
          o i386 
          o amd64


F A Q
-----

      Why is the top makefile called /GNUmakefile/ and not simply
      /Makefile/?

GNUmakefile is the first file GNU make uses for a default makefile. Any
POSIX makefile would not know what to do with this file. Therefore, if
mistakenly you enter make install where make is not GNU make it would
report back that there is nothing to build here --- a clue that you need
to get a hold of GNU make.


      Why is /Makefile.in/, /configure/ checked in with the packages
      sources?

It is common practice not to check these files in the repository, and
use autoreconf to regenerate them after each check out. However, this
requires that a compatible version of the GNU autotools is installed on
the build machine. This is not always the case when getting a guest
account on some platform for the sole purpose of building GrADS. There
is already enough to build, and having to build the autotools is yet
another time consuming task that bone would like to avoid. For this
reason, it is convenient to have a /turn key/ build system ready to go,
with all the files one would find in a distribution tarball. If
adjustments to the configure script is necessary, you can perform this
on a remote machine, check in the new configure, Makefile.in, etc files,
and do a cvs update on the remote build machine. So, there is no deep
reason, just convenience.


      Do I need the bin/ directory in the /supplibs/ for building GrADS?

The /supplibs/ comes with its own copy of pkg-config which resides in
the bin/ directory. If you have pkg-config already installed, you should
be able to use it, but make sure you set the environment variable
PKG_CONFIG_LIBDIR to find the /supplibs/ version of the *.pc files.
However, if you do not have pkg-config installed, you must at least keep
bin/pkg-config.

      Why is /gradsdap/ (formerly /gradsdods/) built without SSL support?

For portability and export control issues. The OPeNDAP core library
libdap depends on the cURL package which in turn depends on OpenSSL.
Building OpenSSL is technically a possibility, but we can easily get
into all sorts of export control issues; read this
<http://www.openssl.org/> and that
<http://www.openssl.org/support/faq.html#LEGAL>. Linking with a shared
OpenSSL library could get around the legal issues, but it did not prove
portable. It is not clear how many OPeNDAP sites are using the https://
protocol; probably not too many. Therefore, SSL support is not included
for the moment. For enabling it, build the /supplibs/ from sources and
comment out the --without-ssl in the curl.config target of the top
GNUmakefile.

License Information
-------------------

Consult each subdirectory for the specific licensing terms for each
package. The top GNUmakefile and fragments are here placed in the
public domain.

Arlindo da Silva <dasilva@alum.mit.edu>