INSTALLATION INSTRUCTIONS  
------------------------- 
Climate Model Output Rewriter (CMOR) version 3.2.1 installation instructions.

 
DOWNLOAD 
--------
You can get the latest version of the software from the CMOR homepage on
github.
git clone http://github.com/PCMDI/CMOR
cd CMOR


INSTALLATION
------------ 
CMOR 3.2.1 requires external packages that need to be installed first. 
It can be compiled/linked against either NetCDF3 or NetCDF4. If you
decide to go with NetCDF4 be sure to build NetCDF4 with the
 --enable-netcdf-4 option! 
Also make sure to install UDUNITS version 2 and not version 1 !
NetCDF4 wil give you access to compression/chunking capabilities.
NOTE: CMIP5 REQUIRES NetCDF3 output files
These packages do NOT require to be built with the Fortran interface, cmor is only
calling their C interface.

FIRST:
 Install external dependencies: 
  Option 1: linkeng against NetCDF3
     - NetCDF3: available at: http://www.unidata.ucar.edu/downloads/netcdf/netcdf-3_6_3/index.jsp
  Option 2: NetCDF4 (if you want to use compression/chunking for other projects than CMIP5)
     - zlib (usually already present on most system), http://zlib.net
     - HDF5: available at: http://hdf.ncsa.uiuc.edu/HDF5
     - NetCDF4: available at: http://www.unidata.ucar.edu/software/netcdf/
                DOT NOT FORGET to build with --enable-netcdf-4 option
  Always:
     - udunits2: (not 1) http://www.unidata.ucar.edu/software/udunits/udunits-2/udunits2.html
     - libuuid: I used the version at http://www.ossp.org/pkg/lib/uuid,
                and you need one with a calling convention compatible with it

 NOTES: it strongly recommend to use the --disable-shared argument to the 
        ./configure when building udunits2, hdf5 and netcdf4. Otherwise make 
        sure the path to hdf5 and netcdf4 lib directory is in your search path 
        or in your LD_LIBRARY_PATH environment variable.
        Also with building NetCDF4, it is very important (although extremeley 
        counter-intuitive) to add the --enable-netcdf-4 argument, otherwise 
        support for netcdf4 will not be enabled...

 NOTES2: You only need to install the C libraries for these. Usually
	 you can turn off the fortran using --disable-fortran
 
 NOTES3: on 64bit systems make SURE both C and FORTRAN compiler are
         running in same 32/64 bit mode. This is especially true for
         users migrating their Mac OS 10.5 machines to 10.6 since
         gfortran does not come standard the old 32bit is usually
         transfered.

 NOTES4: CMOR uses the NetCDF 'nc-config' command to guess some
         options for compilation.  Once you have installed NetCDF
         check that 'nc-config --libs' and 'nc-config --cflags' give
         reasonable answers.


SECOND: Install CMOR (version 3) library
        run the configuration script, build and install

        ./configure --prefix=/path/to/where/you/want/cmor --with-netcdf=/path/to/NetCDF4 --with-udunits2=/path/to/udunits2
        make
        make install

   NOTE: at the configure stage there are some influential variables:
        CC       : C comipler to use
        CPPFLAGS : C preprocessing macros
        CFLAGS   : C compilation flags
        FC       : Fortran compiler to use
        FFLAGS   : Fortan Compilation flags
        LDFLAGS  : Linking time compilation flags
        
        CMOR will "Best-guess" your system and set these, but if you need 
        specific values for your system make sure to set these environment 
        variables first
        
*) installing the python version
        /path/to/your/python/bin/python setup.py install
        or simply
        make python 
        the later picks up whatever python is in your path

CLEANING:
    make clean
    or to completely clean (i.e. remove the built lib):
    make distclean    
    
UNINSTALLING
    make uninstall
      Note: the keyword, "uninstall", removes the library and include
              files from the location specified by "PREFIX" at configure time.

TESTING:
    multiple tests are available
        make test
        make test_python

LINKING ---------------------------------------------

        You will need to link against libcmor.a and the netcdf4 hdf5

Example of linking with a fortran comipler:
/opt/ibmcmp/xlf/8.1/bin/xlf90 -qsuffix=f=f90   $(DEBUG)  Test/test_fortran_example_00.f90 -L/lgm/cmor2/lib -L. -lcmor  -I/lgm/NetCDF4/include  -L/lgm/NetCDF4/lib -lnetcdf  -lhdf5_hl -lhdf5 -lm -lz  -ludunits2  -o test_fortran_example_00

        You can  look in the Makefile under the testipcc section for an example 
        compilation on your system.


MINI F.A.Q. is compilation

If you get an error similar to this one:
Error: Generic function 'cmor_write' at (1) is not an intrinsic function
It probably means that the argument type you passed to the fortran are wrong and that the compiler canot find a matching function in the cmor_write interface 
