************************************************************************
         CGNS Build and Install Instructions for Cygwin
************************************************************************

This document is a instruction on how to build, test and install CGNS with HDF5
support on Cygwin. 

Preconditions:
--------------

1. Installed Cygwin 1.7.25 or higher

   To install the Cygwin net release, go to http://www.cygwin.com and 
   click on "setup-x86.exe" (32-bit installation) or "setup-x86_64.exe" 
   (64-bit installation) at https://cygwin.com/install.html. This will 
   download a GUI installer called setup-x86.exe or setup-x86_64,exe 
   which can be run to download a complete Cygwin installation via the 
   internet. Then follow the instructions on each screen to install Cygwin.

   Cygwin uses packages to manage installing various software. Users can 
   choose to install or uninstall certain packages by running setup.exe.
   http://www.cygwin.com/packages/ provides detailed information about 
   Cygwin packages.

   Most required dependencies can be satisfied by installing all packages in
   the "Devel" category.

2. Compilers, Libraries and Utilities Installed

   2.1 Compilers Supported
    
    The following compilers are supported by CGNS/HDF5 and included in the Cygwin
    package system:
       gcc (4.7.3 and 4.9.2), which includes:
            gcc4-core    : C compiler
            gcc4-g++     : C++ compiler
            gcc4-fortran : fortran compiler
            

   2.1.1 Using Compilers Not Supported
       
       By default the current configuration uses vendor compilers; to use
        another compiler run the following commands before running
        configure: 
 
        setenv CC   "foo -flags"
        setenv FC  "fffoo -flags"

       For example, if users want to use pgf90 as fortran compiler, then 

            setenv FC pgf90

        See the configure help page (configure --help) for a list of
        environment variables that have an affect on building the
        library.
        
    2.2 HDF5 External Library Dependencies

    2.2.1 Zlib

         zlib-1.2.5 or later is supported and tested on Cygwin.

    2.2.2 Szip
       The HDF5 library has a predefined compression filter that uses
       the extended-Rice lossless compression algorithm for chunked
       datasets. For more information about Szip compression and 
       license terms see 
       http://hdfgroup.org/HDF5/doc_resource/SZIP/index.html.
      
       The latest supported public release of SZIP is available from
       ftp://ftp.hdfgroup.org/lib-external/szip/2.1.
    
    2.3 Additional Utilities
    
    The following standard utilities are also required to build and test HDF5:
        
        bison           : yacc implementation
        flex            : flex utility
        make            : make utility
    

Build, Test and Install HDF5 on Cygwin
--------------------------------------

1. Get HDF5 source code package
   Users can download HDF5 source code package from HDF website
   (http://hdfgroup.org). 
     
2. Unpacking the distribution

   The HDF5 source code is distributed in a variety of formats which
   can be unpacked with the following commands, each of which creates 
   an `hdf5-1.8.x' directory.

   2.1 Non-compressed tar archive (*.tar)

            $ tar xf hdf5-1.8.x.tar

   2.2 Gzip'd tar archive (*.tar.gz)

            $ gunzip < hdf5-1.8.x.tar.gz | tar xf -

   2.3 Bzip'd tar archive (*.tar.bz2)

            $ bunzip2 < hdf5-1.8.x.tar.bz2 | tar xf - 

3. Setup Environment

    In Cygwin, most compilers and setting are automatically detected during
    the configure script.  However, if you are building Fortran we recommend 
    that you explicitly set the "FC" variable in your environment to use the 
    gfortran compiler.  For example, issue the command:
    
            $ export FC=gfortran

4. Configuring 
     
   To build HDF5 for use with CGNS it is recommended to disable Fortran
   and the high level library.

       $ ./configure --disable-fortran --disable-hl


   To configure HDF5 C without Zlib,
     
       To disable zlib, using

           $ ./configure --without-zlib
           
   Two ways to configure HDF5 C with specified Zlib
     
      Using

           $ ./configure --with-zlib=INCDIR,LIBDIR

       For example, if the zlib library is installed in
       /cygdrive/c/usr, which is the parent directory of directories
       "include" and "lib", 

 $ ./configure --with-zlib=/cygdrive/c/usr/include,/cygdrive/c/usr/lib

      Through the CPPFLAGS and LDFLAGS Variables
           
       For example, if zlib was installed in the directory 
       /cygdrive/c/usr then using the following command to configure 
       HDF5 with zib

           $ CPPFLAGS=-I/cygdrive/c/usr/include \
           $ LDFLAGS=-L/cygdrive/c/usr/lib \
           $ ./configure

    To specify the installation directories, using 

            $ ./configure --prefix="path for installation"
                 
       By default, HDF5 library, header files, examples, and 
       support programs will be installed in /usr/local/lib,
       /usr/local/include, /usr/local/doc/hdf5/examples, and
       /usr/local/bin. To use a path other than /usr/local specify 
       the path with the `--prefix=PATH' switch as in the above
       command.

  
                          
5. Make and Make Check

   After configuration is done successfully, run the following series of
   commands to build, test and install HDF5
    
            $ make          > "output file name"
            $ make check    > "output file name"
            
   Before run "make install", check output file for "make check", there
   should be no failures at all.

6. Make Install

            $ make install  > "output file name"
   
     
7. Check installed HDF5 library

   After step 6, go to your installation directory, there should be 
   three subdirectories: "bin" "include" and "lib".

8. Known Problems 
   
   dt_arith tests may fail due to the use of fork. This is a known issue
   with cygwin on Windows.

   "make check" fails when building shared lib files is enabled.  The default
   on Cygwin has been changed to disable shared.  It can be enabled with
   the --enable-shared configure option but is likely to fail "make check" 
   with GCC compilers.


Build, Test and Install HDF5 on Cygwin
--------------------------------------

 1.  Download the current stable release from:

       https://github.com/CGNS/CGNS/releases

 2.  You may need to specify the compilers in the environment:

      $ export CC="gcc"
      $ export FC="gfortran"

 3.  Specify the configure options, below is an example configure line:

     $ ./configure \
     --prefix=<path to install cgns> \
     --with-fortran \
     --with-hdf5=<path to hdf5 install> \
     --enable-lfs \
     --disable-shared \
     --enable-debug \
     --disable-cgnstools \
     --with-zlib=<path to libz.a> \
     --enable-64bit

  4. Build the CGNS library using

     $ make
     $ make install
     $ make test

-----------------------------------------------------------------------

Submit bug reports at:

 https://cgnsorg.atlassian.net/secure/Dashboard.jspa