Instructions for building and installing sigio on Unix
******************************************************

$Revision: 28345 $
nceplibs support email: ncep.list.emc.nceplibs.support@noaa.gov


         Contents
         ========
  A. The easy (I hope) way...
  B. The more flexible way
    1. Configuration
    2. Building the library
    3. Testing the library
    4. Installing the library
       - NCO Install
       - GNU Install
       - Uninstalling the library
    5. Cleaning up



A. The easy (I hope) way...
===========================

To build the sigio library, you can use the "make_sigio_lib.sh" script
specifying the build configuration. The available build configurations are:

  gfortran-debug.setup  ifort-debug.setup  pgf95-debug.setup  xlf2003-debug.setup
  gfortran.setup        ifort.setup        pgf95.setup        xlf2003.setup


So, on WCOSS/tide you would type:

  $ make_sigio_lib.sh ifort.setup


On the CCS you would type

  $ make_sigio_lib.sh xlf2003.setup


Some additional points:
- Only the NCO-type install is performed.
- The library is installed relative to the current directory. After
  running the script you should see a new directory containing the
  library.
- See section B.4 below for information about the installation directory
  structure

You can tailor the build process using this "make_sigio_lib.sh" script by
modifying the relevant build configuration setup file in the "config-setup/"
subdirectory.

Or, if you are going to be testing library builds multiple times, you can
create your own configuration setup file.




B. The more flexible way
========================

1. Configuration
----------------

If you need more flexibility in the library build you can specify the necessary
information directly to the configure script that generates the makefiles. For
example, on WCOSS/tide:

  $ ./configure --prefix=${PWD} \
                FC="ifort" \
                FCFLAGS="-O3 -g -traceback"

The --prefix switch sets the installation directory and defaults to /usr/local so
make sure you set it to a directory in which you have write access.

The definition of the "FC" enviroment variables is not strictly necessary as it defaults
to "ifort" on linux systems if available (followed by "gfortran" and "pgf95" if not), and
"xlf2003" on AIX systems.




2. Building the library
-----------------------

To start the library build for a particular configuration, simply type

  $ make




3. Testing the library
----------------------

We don't have any package-level tests for sigio yet. Sorry! They're coming...




4. Installing the library
-------------------------

Installation of the library *always* occurs into its own directory within the
directory specified by the --prefix switch. The name of the installation
directory follows the convention:

  <library name>_<version>

So, if the a library version (say, v1.1.0) build was configured with --prefix=$PWD,
then the installation directory will be

  ${PWD}/sigio_v1.1.0



NCO Install
...........

To install the library conforming to the NCO organisation and naming conventions,
type:

  $ make nco_install

For a library version (say, v1.1.0), this will create a directory called "sigio_v1.1.0".
That directory is organised according to the current NCO structure on CCS and WCOSS
in /nwprod/lib, as shown below:

  sigio_v1.1.0/
    |
    |--libsigio_v1.1.0.a
    |
    `--incmod/
         |
         `--sigio_v1.1.0/
              |
              `--sigio_module.mod

The contents of the "sigio_v1.1.0" directory can then be moved into the official
/nwprod/lib location as needed.

Let's assume the above install was moved into "/usrx/local/nceplibs", to use the
library in this structure in your own application, the usual environment variables
would be modified something like:

  libroot="/usrx/local/nceplibs"
  FCFLAGS="-I${libroot}/incmod/sigio_v1.1.0 ${FCFLAGS}"
  LDFLAGS="-L${libroot} ${LDFLAGS}"
  LIBS="-lsigio_v1.1.0"



GNU Install
...........

To perform a GNU-type install, type:

  $ make install

For a library version (say, v1.1.0), this will createa directory called "sigio_v1.1.0".
That directory structure is shown below:

  sigio_v1.1.0/
    |
    |--include/
    |    |
    |    `--sigio_module.mod
    |
    `--lib/
         |
         `--libsigio.a

Note that the only versioned item in this type of install is the name of the
installation directory itself.

Let's assume the above install was moved into "/usrx/local/nceplibs", to use the
library in this structure in your own application, the usual environment variables
would be modified something like:

  libroot="/usrx/local/nceplibs"
  FCFLAGS="-I${libroot}/sigio_v1.1.0/include ${FCFLAGS}"
  LDFLAGS="-L${libroot}/sigio_v1.1.0/lib ${LDFLAGS}"
  LIBS="-lsigio"



Uninstalling the library
........................

To uninstall the library (assuming you haven't moved the installation directory
contents somewhere else) you can type:

  $ make uninstall

This will delete the created installation directory. So, for a library version
(say, v1.1.0), if your configure script invocation was something like

  $ ./configure --prefix=${PWD} ...other command line arguments...

then the "uninstall" target will delete the "${PWD}/sigio_v1.1.0" directory.




5. Cleaning up
--------------

Two targets are provided for cleaning up after the build. To remove all the
build products type

  $ make clean

To also remove all the configuration products (i.e. the makefiles) type

  $ make distclean
