
                              Gribex library
                              --------------

   Any comments on the document or the software would be appreciated. 
   Please address comments to:

Software Services
ECMWF
Shinfield Park
Reading
Berkshire RG2 9AX
U.K.

Fax: +44 1734 869450

e-mail: software.services@ecmwf.int

The software is provided as a tar gzip file. This should be expanded using

tar -xfz gribex_version.tar.gz

Content:
Makefile        Makefile for 'everything'
build_library   Script bilding library
install         Install script
gribex          Subdirectory containing GRIB encoding/decoding software
gribtemplates   Subdirectory containing GRIB templates 
gribtables      Subdirectory containing GRIB tables
pbio            Subdirectory containing binary read/write routines
example         Subdirectory containing example program for decoding GRIB
config          Subdirectory containing configuration files for make
options         Subdirectory containing options files for make


**************************************************************

This is instruction how to build library and install:

   Run the script bilding library and answer a few questions:

 ./build_library

   After library is built, tables, land-sea mask and library should be
installed at appropriate place.

   It is recomended to do it by install script.


 ./install

   If you want to put library in /usr/local/lib directory,
you should run install script with root permission.

**************************************************************

It is strongly suggested to build the library using
shell script ./build_library  and install using ./install !!!

**************************************************************



Compilation options
-------------------

   Files are given for a variety of platforms defining the compilation options:
makefile configuration, compiler options and source file lists.

   Using SGI as an example, these files are:

1) In the working directory

   config.sgimips
   config.sgimipsR64
   options_sgimips

2) In subdirectories gribex and pbio

   sources.sgimips


Compiling the library
---------------------

   The correct configuration, options and source files can be selected using for 
make variables: ARCH, CNAME,A64 and R64.

   ARCH indicates the machine architecture on which the gribex library will be
installed. It may not necessarily have a pre-defined value. A list of possible
values could include: linux, windows, CRAY, FUJITSU, VPP5000, decalpha, hppa,
i686, ibm_power4, rs6000, sgimips and sun4.

   CNAME is used to name the compilers; it may or may not be pre-defined, depending
on the operational system you use. If you want to choose your own compilers, you
can define them in the appropriate 'config' file. For linux and sun4 systems,
CNAME=_gnu can be specified in order to compile with Gnu compilers. 

   Values of CNAME which have been tested for different machine architectures
include:

decalpha - Compaq Fortran 90 compiler
         - the C++ compiler
hppa     - HP Fortran compiler
         - C compiler
linux    - The Portland Group Compiler Technology Fortran 90 compiler,
           pgf90 and pgcc
         - GNU project C, C++ Compiler, F77 compiler
rs6000   - XL Fortran for AIX
         - C for AIX Compiler, Version 5
sgimips  - MIPSpro F77 compiler
         - MIPS C compiler
sun4     - Forte[tm] Developer 7 Fortran 95 compiler
         - SunOS/BSD Compatibility Package C compiler

   A64 determines 32 or 64 bits machine.
   R64 determines the number of bits in the representation of real numbers.
The default is 32-bit. You can choose 64-bit setting R64=R64 in order to get
64-bit real numbers.


!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

If you decide to build the library using directly make, please NOTE that
you have to specify path for gribtables, bufrtables, crextables,
land_sea_mask, gribtemplates in appropriate

config/config.$ARCH$CNAME$R64$A64

You should add -DTABLE_PATH=\'/your path\'/

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!



There are a few possible ways of carrying out the compilation:
----------------------------------------------------

1) Compile setting the ARCH variable just for the command:

   make ARCH=sgimips

   In this case, CNAME and R64 are pre-defined. 

2) Compile setting the ARCH variable and choosing 64-bit reals;

   make ARCH=sgimips R64=R64

3) On linux or SunOS, compile setting CNAME=_gnu to force the use of the Gnu
   compilers. For Windows (Cygwin), Gnu is the default compiler.

   make ARCH=linux CNAME=_gnu

4) Same as 3) and added A64 if machine is 64 bits Linux

   make ARCH=linux CNAME=_gnu A64=A64
   
Note:
   A64 option is valid only for Linux OS!!!

   The library will be created in a working directory and be named libgribex.a.

   You can install the gribex library on Windows only if you have the Cygwin
linux-like environment for Windows, and Gnu compilers.

   It is recommended that users should not change any routines in the source 
sub-directories because any changes would not be present in future ECMWF 
releases of this software.

   You can use other options for compilation. For example: selecting the working
directory; modifying the configuration files; changing the level of
optimisation; etc. The 'make' utility can be used repeatedly. It will only
cause the re-compilation of routines which have been modified since the
previous 'make'.


Environment variables
---------------------

   As an alternative to defining ARCH and R64 as parameter variables, they can 
be defined as environment variables.

ARCH - the machine architecture.

   If this is not set on your system then the following commands should be issued:

  ARCH=`arch`; export ARCH    (Bourne or Korn shell)

  setenv ARCH `arch`          (C-shell)

R64 - Choose 32- or 64-bit real values.

   If this variable is undefined then 32-bit reals will be used. On some machines,
the compiler options for 64-bit compilation are available by setting R64 as
follows:

  R64=R64; export R64          (Bourne or Korn shell)

  setenv R64 R64               (C-shell)

   The supported values for ARCH can be determined by looking at the file
names in the top directory for configuration files. These are of the
form config.${ARCH}${CNAME}${R64}


CNAME - Choose a different compiler to the default the configuration file.

   The CNAME=_gnu option is currently only supported on a Linux and SunOS systems;
it allows compilation using the Gnu compilers.

Bourne or Korn shell

  CNAME=_gnu; export CNAME     (Bourne or Korn shell)

  setenv CNAME _gnu            (C-shell)

IF YOU USE ./build_library SCRIPT YOU DON'T NEED TO SET ENVIRONMENTAL
VARIABLES BELOW THAT POINT TO THE TABLES.

   The location of GRIB tables and Gribex template files could be specified by
the environment variables Put the specification of them in your startup files
(.profile, ...) to ensure you have access to the GRIB tables and Gribex template 
files on future logins. Thus:
LOCAL_DEFINITION_TEMPLATES

Bourne or Korn shell:

  ECMWF_LOCAL_TABLE_PATH="choosen directory"/gribtables/
  export ECMWF_LOCAL_TABLE_PATH

  LOCAL_DEFINITION_TEMPLATES="choosen directory"/gribtemplates/
  export LOCAL_DEFINITION_TEMPLATES

C-shell:

  setenv ECMWF_LOCAL_TABLE_PATH "choosen directory"/gribtables/
  setenv LOCAL_DEFINITION_TEMPLATES "choosen directory"/gribtemplates/

   ECMWF_LOCAL_TABLE_PATH should be defined to point to a directory containing the
tables. The initial location of these tables is in "working directory"/gribtables.
   LOCAL_DEFINITION_TEMPLATES should be defined to point to a directory containing the
Gribex local definition templates. The initial location of these tables is in
"working directory"/gribtemplates.

   From GRIBEX version 000080 onwards, the environment variable GRIBEX_DEBUG
can be set to ON or OFF to switch on or off the debug output from GRIBEX.

   From GRIBEX version 000100 onwards, the environment variable GRIBEX_CHECK
can be set to ON or OFF to switch on or off the checking of headers in GRIBEX.

   When compiling a program, you need to specify where to find libgribex.a by
putting its full pathname in the makefile. The initial location of the library
is "working directory". An alternative is to put libgribex.a in /usr/local/lib
(this may need system priviliges) which is conventionally used on UNIX-type
systems for holding libraries and should be defined in your environment PATH
variable.

   The library name follows the normal UNIX convention (it starts with lib and ends
in .a), so the library can be specified in the compile/link command using the
standard ld convention, for example:

        cc -o program program.c  -lgribex

   You can see an example of decoding a GRIB product using make in
example directory. Invoke 'make' and start
an executable version of program agrdemo.F through:

   ./test.sh

   that temporary set env variables ECMWF_LOCAL_TABLE_PATH and LOCAL_DEFINITION_TEMPLATES
   and run 

  ./agrdemo -i ../data/latlon.grib

  for testing purpose before installation

   where latlon.grib is a file containing GRIB fields on latitude/longitude
grids.
   It can be re-run for gaussian grids and spherical harmonic fields.

   The decoding software is based on a example program (agrdemo.F) which produces
a listing of the Grib header records together with a few of the data values.


Terminology
-----------

   >From here on, any reference to SOFTWARE in file names should be interpreted
as the software you have received, i.e. GRIB, PBIO etc.

   The use of the word PLATFORM refers to the make of the computer for which the 
software is intended and substitutes for CRAY, sun etc.

   SUBPACKAGE could be any of pbio, gribex etc. and refers to a part of the
whole SOFTWARE set.


Provided for UNIX systems named above.
--------------------------------------

   This README file.
   The tar file gribex_000version.tar (version is a 3-digit number).


Other UNIX systems.
-------------------

   If you use a UNIX system other than those for which the software was prepared,
you should experiment with the configurations provided to see if any are
suitable for your system.

   If any problems are encountered, the following points are worth considering:

Is your cc compiler ANSI?
The C code in this software is ANSI conformant.

Does your FORTRAN compiler need other switches?
Look at other programs compiled on your system.

Does your system need a ranlib command performed on the libraries?
Do "man ar" or "man ranlib".

How many bytes are there in a computer word. Is the platform big-endian or
little-endian? Some of routines are dependent on the word size and on which bit
in a computer word is the most significant. These dependencies may be resolved
by choosing one or other of the files gbyte.c or gbyte_alpha.c(for a
little-endian system).

License
--------

This software is licensed under the GNU LESSER GENERAL PUBLIC LICENSE.
See LICENSE and gpl-3.0.txt for details.

