#==============================================================================
# RCS Header:
#   File         [$Source: /home/fr0600/frpb/Projects/GCOM/GCOM_arch/Readme,v $]
#   Revision     [$Revision: 1.6.1.1 $]     Named [$Name: release#2_9_b5 $]
#   Last checkin [$Date: 2001/12/06 10:14:44 $]
#   Author       [$Author: frpb $]
#==============================================================================

1. Introduction
---------------

Welcome to GCOM!

GCOM stands for "General COMmunications". It is an interface library that provides a
consistent interface to a number of MPP communication libraries. At the time of writing
this is Cray SHMEM and MPI - these being the two most useful libraries for high
performance numerical codes.



2. History
----------

GCOM-GC was originally developed by SINTEF Industrial Mathematics (Norway). Thanks to
collaborative work with the Met Office (UK) an extra section was added to the library,
GCOM-GCG, which supplied extra functionality to allow processor subsets (groups) to be
used. It also added extra functionality to allow vector sums, vector shifts and all to all
communications - all of which were specifically needed by the Met Office's Unified Model.

The code has been further developed and modified at the Met Office.

3. Directory Structure
----------------------

GCOM_TOP_LEVEL_DIRECTORY
!
!- File: Copyright : Copyright information for GCOM
!- File: Readme  : This file
!- File: Release_Notes : Details of the latest changes
!- File: _version.txt : RCS release stamp
!
!- Dir: build : where all the action takes place
!  !
!  !- File: Makefile : Top level make file to compile the library
!  !
!  !- Dir:extras : extra routines required for certain platforms
!  !  !- Dir: sgi_64_mpi_fix : Contains files for SGI 64bit MPI implementation
!  !  !- Dir: sgi_64_shmem_fix : Contains files for SGI 64bit SHMEM implementation
!  !
!  !- Dir: gc : Source code for GCOM-GC and Makefile
!  !  !- File: Makefile : Makefile for GCOM-GC
!  !  !- Files: gc__*.F : Internal GCOM-GC routines (not for external use)
!  !  !- Files: gc_*.F : GCOM-GC routines (for external use)
!  !
!  !- Dir: gcg : Source code for GCOM-GCG and Makefile
!  !  !- File: Makefile : Makefile for GCOM-GCG
!  !  !- Files: gcg__*.F : Internal GCOM-GCG routines (not for external use)
!  !  !- Files: gcg_*.F : GCOM-GCG routines (for external use)
!  !
!  !- Dir: include : a number of include files for GCOM
!  !  !- Files: gc__*_common.h : Fortran COMMON blocks for GC routines
!  !  !- Files: gc_*.h : General GC include files
!  !  !- Files: gcg__*_common.h : Fortran COMMON blocks for GCG routines
!  !  !- Files: gcg_*.h : General GCG include files
!  !
!  !- Dir: make_inc : a number of include files for Makefiles
!  !  !- File: files.mk : All the files within a GCOM library
!  !  !- File: gc_depend.mk : Dependencies in GC component of GCOM
!  !  !- File: gcg_depend.mk : Dependencies in GCG component of GCOM
!  !  !- File: rules.mk : How to compile .F,.f and .c files into library
!  !  !- File: sys_inc.mk : Defines some internal variables for Makefile
!  !  !- File: user_inc.mk : All the user-definable stuff for GCOM

4. How do I build GCOM?
-----------------------

The GCOM system has been built and tested on a small number of platforms at the Met
Office, including HP (HP-UX11 using GNU make/compile environment and HP make/compile
environment) and Cray T3E (PrgEnv3.0.2.1). In the unlikely event that your local version
of make cannot cope with the Makefiles, we suggest you obtain GNU make from
ftp:ftp.gnu.org/pub/gnu/make

You will need to edit the build/make_inc/user_inc.mk file. This file contains all the
user-definable bits and pieces that will decide exactly how GCOM is built. The file
contains instructions and examples for all the different configurations possible. The
defaults set up in the file before it has been edited are for a single processor (non-MPP)
version of GCOM. If you make any changes to this file, it is recommended that you do a
"make clean" in the build directory before doing a make.

When the user_inc.mk file has been satisfactorily updated, go into the build directory
and type "make". If all goes well this will eventually produce a GCOM library file in a
directory called "lib" under the GCOM top level directory. The name of the library will
be dependent on what has been set up in the user_inc.mk file.

Each time the library is updated via make, a special file called gc__stamp.F (there is
one of these in each source directory) is updated and written to the library. This
enables GCOM when it is used (when GC_INIT is called) to print a message giving details
about which version is being run and when the library was last updated, something similar
to this:

=====================================================
GCOM Version 1.21
Non buffered MPI
Built at Wed Apr 22 11:19:10 BST 2001
=====================================================

Also a log file (file name is similar to that of the library, but without the "lib"
prefix and the ".a" extension replaced by ".log") is maintained for each version of the
library that is compiled that shows the last modification time of each library
component. These log files are written to the "log" directory.

