path: root/release_docs/INSTALL

        Instructions for the Installation of HDF5 Software
        ==================================================
                         January 30, 2008

        CONTENTS
        --------
        1. Obtaining HDF5

        2. Quick installation
        2.1. Windows

        3. HDF5 dependencies
        3.1. Zlib
        3.2  Szip (optional)
        3.3. MPI and MPI-IO

        4. Full installation instructions for source distributions
        4.1. Unpacking the distribution
        4.1.1. Non-compressed tar archive (*.tar)
        4.1.2. Compressed tar archive (*.tar.Z)
        4.1.3. Gzip'd tar archive (*.tar.gz)
        4.1.4. Bzip'd tar archive (*.tar.bz2)
        4.2. Source versus build directories
        4.3. Configuring
        4.3.1. Specifying the installation directories
        4.3.2. Using an alternate C compiler
        4.3.3. Additional compilation flags
        4.3.4. Compiling HDF5 wrapper libraries
        4.3.5. Specifying other programs
        4.3.6. Specifying other libraries and headers
        4.3.7. Static versus shared linking
        4.3.8. Optimization versus symbolic debugging
        4.3.9. Parallel versus serial library
        4.3.10. Disabling high-level C APIs 
        4.3.11. Threadsafe capability
        4.3.12. Backward compatibility with HDF5 1.4* releases
        4.3.13. Network stream capability
        4.4. Building
        4.5. Testing
        4.6. Installing

        5. Using the Library
        5.1. Using the C++ API

        6. Support

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

1. Obtaining HDF5
        The latest supported public release of HDF5 is available from
        ftp://ftp.hdfgroup.org/HDF5/current/src.  It is available in tar 
        format compressed with gzip. 

        The HDF team also makes snapshots of the source code available on
        a regular basis. These snapshots are unsupported (that is, the
        HDF team will not release a bug-fix on a particular snapshot;
        rather any bug fixes will be rolled into the next snapshot).
        Furthermore, the snapshots have only been tested on a few
        machines and may not test correctly for parallel applications.
        Snapshots can be found at
        ftp://ftp.hdfgroup.uiuc.edu/pub/outgoing/hdf5/snapshots in a 
        limited number of formats.


2. Quick installation
        For those who don't like to read ;-) the following steps can be
        used to configure, build, test, and install the HDF5 Library, header
        files, and support programs. The "#" symbol in "hdf5-1.6.#" below
        stands for the release number and/or the subrelease version.  (For  
        example, use "3" for hdf5-1.6.3 or "3-snap4" for hdf5-1.6.3-snap4.)

            $ gunzip < hdf5-1.6.#.tar.gz | tar xf -
            $ cd hdf5-1.6.#
            $ ./configure <configure_flags>
            $ make
            $ make check
            $ make install

        <configure_flags> above refers to the configure flags appropriate
        to your installation.  For example, to install HDF5 with the 
        Fortran and C++ interfaces and with SZIP compression, the 
        configure line might read as follows:
        
            $ ./configure --enable-fortran --enable-cxx \
                          --with-szlib=PATH_TO_SZIP

        In this case, PATH_TO_SZIP would be replaced with the path to the 
        installed location of the SZIP library.

2.1. Windows
        Users of Microsoft Windows should see one of the INSTALL_Windows files
        for detailed instructions.


3. HDF5 dependencies
3.1. Zlib 
        The HDF5 Library includes a predefined compression filter that 
        uses the "deflate" method for chunked datasets. If zlib-1.1.2 or
        later is found, HDF5 will use it. Otherwise, HDF5's predefined
        compression method will degenerate to a no-op; the compression
        filter will succeed but the data will not be compressed.

3.2. Szip (optional)
        The HDF5 Library includes 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/doc_resource/SZIP/index.html.

        Precompiled szip binaries for each supported platform and a source tar 
        ball file can be found at ftp://ftp.hdfgroup.org/lib-external/szip/.
        
        To configure the HDF5 Library with the Szip compression filter, use 
        the '--enable-szlib=/PATH_TO_SZIP' flag. For more information, see 
        section 4.3.6, "Specifying other libraries and headers."

        Starting with release 1.6.3, Szip library binaries are distributed 
        with the encoder enabled (a license may be required to use this binary) 
        and with the encoder disabled (freely usable without a license). 
        Depending on which Szip binary is used, Szip compression is available 
        or is not available for an HDF5 application. Szip decoding is always 
        available, i.e., an HDF5 application can always read Szip compressed 
        data, if the Szip filter is present.

3.3. MPI and MPI-IO
        The parallel version of the library is built upon the foundation
        provided by MPI and MPI-IO. If these libraries are not available
        when HDF5 is configured, only a serial version of HDF5 can be built.


4. Full installation instructions for source distributions
4.1. 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.6.#' directory.

4.1.1. Non-compressed tar archive (*.tar)

            $ tar xf hdf5-1.6.#.tar

4.1.2. Compressed tar archive (*.tar.Z)

            $ uncompress -c < hdf5-1.6.#.tar.Z | tar xf -

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

            $ gunzip < hdf5-1.6.#.tar.gz | tar xf -

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

            $ bunzip2 < hdf5-1.6.#.tar.bz2 | tar xf -

4.2. Source versus build directories
        On most systems, the build can occur in a directory other than the
        source directory, allowing multiple concurrent builds and/or
        read-only source code. In order to accomplish this, one should
        create a build directory, cd into that directory, and run the
        'configure' script found in the source directory (configure
        details are below).

        Unfortunately, this does not work on recent Irix platforms (6.5
        and later) because that 'make' does not understand the VPATH
        variable. However, HDF5 also supports Irix 'pmake' which has a
        .PATH target that serves a similar purpose. Here's what the man
        pages say about VPATH, which is the facility used by HDF5
        makefiles for this feature:

                The VPATH facility is a derivation of the undocumented
                VPATH feature in the System V Release 3 version of make.
                System V Release 4 has a new VPATH implementation, much
                like the pmake(1) .PATH feature. This new feature is also
                undocumented in the standard System V Release 4 manual
                pages.  For this reason it is not available in the IRIX
                version of make. The VPATH facility should not be used
                with the new parallel make option.

4.3. Configuring
        HDF5 uses the GNU autoconf system for configuration, which
        detects various features of the host system and creates the
        Makefiles. On most systems it should be sufficient to say:

            $ ./configure
                  OR
            $ sh configure

        The configuration process can be controlled through environment
        variables, command-line switches, and host configuration files.
        For a complete list of switches, type:

            $ ./configure --help

        The host configuration files are located in the 'config'
        directory and are based on architecture name, vendor name, and/or
        operating system, which are displayed near the beginning of the
        'configure' output. The host config file influences the behavior
        of configure by setting or augmenting shell variables.

4.3.1. Specifying the installation directories
        Typing 'make install' will install the HDF5 Library, header files, 
        examples, and support programs in hdf5/lib, hdf5/include, 
        hdf5/examples, and hdf5/bin under the directory where it was built 
        (hdf5-1.6.# or the build directory mentioned in section 4.2, "Source 
        versus build directories").  To use a path other than hdf5/, specify 
        the path with the '--prefix=PATH' switch:

            $ ./configure --prefix=$HOME

        If shared libraries are being built (the default), the final
        home of the shared library must be specified with this switch
        before the library and executables are built.

4.3.2. Using an alternate C compiler
        By default, configure will look for the C compiler specified
        in the host configuration file in the config directory or by trying
        'gcc' and 'cc'. However, if the environment variable "CC" is set,
        then its value is used as the C compiler (users of csh and
        derivatives will need to prefix the commands below with 'env').
        For instance, to use the native C compiler on a system which also
        has the GNU gcc compiler:

            $ CC=cc ./configure

        A parallel version of HDF5 can be built by specifying a parallel 
        compiler, usually 'mpicc', as the C compiler (the '--enable-parallel' 
        flag documented below is optional in this case).  Using the 'mpicc' 
        compiler will insure that the correct MPI and MPI-IO header files and
        libraries are used.

            $ CC=/usr/local/mpi/bin/mpicc ./configure

        On Irix64, the default compiler is 'cc'. To use an alternate
        compiler, specify it with the CC variable:

            $ CC='cc -n32' ./configure

        Similarly, users compiling on a Solaris machine and desiring to
        build the distribution with 64-bit support should specify the
        correct flags with the CC variable:

            $ CC='cc -xarch=v9' ./configure

        To configure AIX 64-bit, including the Fortran and C++ APIs, set the
        compilation flags as follows (note the requirement to hardset $AR to
        'ar -X 64') and run configure with the appropriate flags as follows:

            Serial:
                $ CFLAGS=-q64 FFLAGS=-q64 CXXFLAGS=-q64 AR='ar -X 64'\
                $ ./configure --enable-fortran

            Parallel:
                $ CFLAGS=-q64 FFLAGS=-q64 AR='ar -X 64'\
                $ ./configure --enable-fortran --enable-parallel

4.3.3. Additional compilation flags
        If additional flags must be passed to the compilation commands,
        specify those flags with the CFLAGS variable. For instance,
        to enable symbolic debugging of a production version of HDF5 one
        might say:

            $ CFLAGS=-g ./configure --enable-production

4.3.4. Compiling HDF5 wrapper libraries
        One can optionally build the Fortran and/or C++ interface to the HDF5
        C library. By default, both options are disabled. To build one or 
        both, specify '--enable-fortran' and/or '--enable-cxx', respectively.

            $ ./configure --enable-fortran
            $ ./configure --enable-cxx
            $ ./configure --enable-fortran --enable-cxx
        
        Configure uses the Fortran compiler specified in the host configuration
        file in the fortran/config directory and the C++ compiler specified in 
        the host configuration file under the c++/config directory. 
        Configuration will halt if a working Fortran 90 or 95 compiler or 
        C++ compiler is not found. Currently, the Fortran configure tests
        for these compilers in order: f90, pgf90, f95. To use an
        alternate Fortran compiler, specify it with the F9X variable.
        For example:

            $ F9X=/mycompiler/bin/g95 ./configure --enable-fortran

        To use an alternate C++ compiler, specify it with the CXX variable:

            $ CXX=/mycompiler/bin/c++ ./configure --enable-cxx 

        Note: The Fortran interface supports parallel HDF5 while the 
              C++ interface does not.
          
4.3.5. Specifying other programs
        The build system has been tuned for use with GNU make but works
        also with other versions of make.  If the 'make' command runs a
        non-GNU version but a GNU version is available under a different
        name (perhaps 'gmake'), then HDF5 can be configured to use it by
        setting the MAKE variable. Note that whatever value is used for
        MAKE must also be used as the make command when building the
        library:

            $ MAKE=gmake ./configure
            $ gmake

        The 'AR' and 'RANLIB' variables can also be set to the names of
        the 'ar' and 'ranlib' (or ':') commands to override values
        detected by configure.

        The HDF5 Library, include files, and utilities are installed
        during 'make install' (described below) with a BSD-compatible
        install program detected automatically by configure. If none is
        found, the shell script bin/install-sh is used. Configure
        does NOT check that the install program actually works; if a
        bad install is detected on your system, you have two choices: 

            1. Copy the bin/install-sh program to your $HOME/bin
               directory, name it 'install', and make sure that $HOME/bin
               is searched before the system bin directories.

            2. Specify the full path name of the 'install-sh' program
               as the value of the INSTALL environment variable. 
               Note: Do not use 'cp' or some other program in place of install
               because the HDF5 makefiles also use the install program to
               change file ownership and/or access permissions.

4.3.6. Specifying other libraries and headers
        Configure searches the standard places (those places known by the
        system compiler) for include files and header files. However,
        additional directories can be specified by using the CPPFLAGS
        and/or LDFLAGS variables:

            $ CPPFLAGS=-I/home/robb/include \
              LDFLAGS=-L/home/robb/lib \
              ./configure

        HDF5 uses the zlib library to support the HDF5 deflate data 
        compression filter.  Configure searches the standard places (plus 
        those specified above with CPPFLAGS and LDFLAGS variables) for the 
        zlib headers and library. The search can be disabled by specifying
        '--without-zlib' or alternate directories can be specified with
        '--with-zlib=/PATH_TO_ZLIB' or through the CPPFLAGS and LDFLAGS
        variables:

            $ ./configure --with-zlib=/PATH_TO_ZLIB

            $ CPPFLAGS=-I/PATH_TO_ZLIB/include \
              LDFLAGS=-L/PATH_TO_ZLIB/lib \
              ./configure

        HDF5 also provides a predefined Szip compression method (see section
        3.2, "Szip").  To enable Szip compression, the HDF5 Library has to 
        be configured and built using the Szip Library:

            $ ./configure --with-szlib=/PATH_TO_SZIP

4.3.7. Static versus shared linking
        The build process will create static libraries on all systems and
        shared libraries on systems that support dynamic linking to a
        sufficient degree. Either form of the library may be suppressed by
        saying '--disable-static' or '--disable-shared'.

            $ ./configure --disable-shared

        To build only statically linked executables on platforms that
        support shared libraries, use the '--enable-static-exec' flag.

            $ ./configure --enable-static-exec

4.3.8. Optimization versus symbolic debugging
        The library can be compiled to provide symbolic debugging support
        so it can be debugged with gdb, dbx, ddd, etc., or it can be
        compiled with various optimizations. To compile for symbolic
        debugging (the default for snapshots), say '--disable-production';
        to compile with optimizations (the default for supported public
        releases), say '--enable-production'. On some systems, the library
        can also be compiled for profiling with gprof by saying
        '--enable-production=profile'.

            $ ./configure --disable-production         #symbolic debugging
            $ ./configure --enable-production          #optimized code
            $ ./configure --enable-production=profile  #for use with gprof

        Regardless of whether support for symbolic debugging is enabled,
        the library can also perform runtime debugging of certain packages 
        (such as type conversion execution times and extensive invariant 
        condition checking). To enable this debugging, supply a
        comma-separated list of package names to the '--enable-debug'
        switch.  (See "Debugging HDF5 Applications" for a list of package 
        names.  In the documentation distributed with this release, that
        document is in doc/html/Debugging.html.  In the HDF5 documentation 
        at http://hdfgroup.org/HDF5/doc1.6/, select "HDF5 User's Guide from 
        Release 1.4.5," then select "Debugging.")

        Debugging can be disabled by saying '--disable-debug'. The
        default debugging level for snapshots is a subset of the
        available packages; the default for supported releases is no
        debugging (debugging can incur a significant runtime penalty).

            $ ./configure --enable-debug=s,t   #debug only H5S and H5T
            $ ./configure --enable-debug       #debug normal packages
            $ ./configure --enable-debug=all   #debug all packages
            $ ./configure --disable-debug      #no debugging

        HDF5 is also able to print a trace of all API function calls,
        their arguments, and the return values. To enable or disable the
        ability to trace the API, say '--enable-trace' (the default for
        snapthots) or '--disable-trace' (the default for public releases). 
        The tracing must also be enabled at runtime to see any output 
        (see Debugging.html).


4.3.9. Parallel versus serial library
        The HDF5 Library can be configured to use MPI and MPI-IO for
        parallelism on a distributed multi-processor system.  Read the
        file INSTALL_parallel for detailed explanations.

4.3.10. Disabling high-level C APIs
        By default, the HDF5 Library is configured to build the high-level 
        C APIs.  If this feature is not desired, use the '--disable-hl' 
        configuration flag to bypass building and testing high-level C APIs.

4.3.11. Threadsafe capability
        The HDF5 Library can be configured to be thread-safe (on a very
        large scale) with the '--enable-threadsafe' flag to the configure 
        script.  Some platforms may also require the '-with-pthread=INC,LIB' 
        flag (or '--with-pthread=DIR') to the configure script.  
        (For further details, see "Thread Safe HDF5 Library Implementation" 
        in the "HDF5 Technical Notes."  This document is included in the 
        HDF5 documentation set distributed with this release and posted at
        http://hdfgroup.org/HDF5/doc1.6/.)

4.3.12. Backward compatibility with HDF5 1.4* releases
        The 1.6 version of the HDF5 Library can be configured to operate
        identically to the v1.4 library with the '--enable-hdf5v1_4'
        configure flag. This allows existing code to be compiled with the
        v1.6 library without requiring immediate changes to the
        application source code. This flag will only be supported in the
        v1.6 branch of the library; it will not be available in v1.8+.

4.3.13. Network stream capability
        By default, the HDF5 Library is configured with a network stream file
        driver. See the documentation on the Virtual File Layer for more 
        details about the use of this driver. Use the '--disable-stream-vfd' 
        configuration flag to turn it OFF.

4.4. Building
        The library, confidence tests, and programs can be built by
        saying just:

            $ make

        Note that if you supplied some other make command via the MAKE
        variable during the configuration step, that same command must
        be used here.

        When using GNU make you can add '-j -l6' to the make command to
        compile in parallel on SMP machines. Do not give a number after
        the '-j' since GNU make will turn it off for recursive invocations
        of make.

            $ make -j -l6

4.5. Testing
        HDF5 comes with various test suites, all of which can be run by
        saying

            $ make check

        To run only the tests for the library, change to the 'test'
        directory before issuing the command. Similarly, tests for the
        parallel aspects of the library are in 'testpar' and tests for
        the support programs are in 'tools'.

        Temporary files will be deleted by each test when it completes
        but may continue to exist in an incomplete state if the test fails.
        To prevent deletion of the files, define the HDF5_NOCLEANUP
        environment variable.

4.6. Installing
        The HDF5 Library, include files, and support programs can be
        installed in a (semi-)public place by saying 'make install'. The
        files are installed under the directory specified with '--prefix=DIR' 
        (or under 'hdf5/' in the build directory) in directories named 'lib', 
        'include', 'doc', and 'bin'. The prefix directory DIR must exist 
        prior to 'make install', but its subdirectories are created 
        automatically.  If no prefix is defined, an 'hdf5' directory is 
        automatically created under the build directory.

        If 'make install' fails because the install command at your site
        somehow fails, you may use the install-sh script that comes with the
        source. You need to run ./configure again:

            $ INSTALL="$PWD/bin/install-sh -c" ./configure ...
            $ make install

        The library can be used without installing it by pointing the
        compiler at the 'src' and 'src/.libs' directory for include files and
        libraries. However, the minimum which must be installed to make
        the library publicly available is:

            The library:
                ./src/.libs/libhdf5.a

            The public header files:
                ./src/H5*public.h, ./src/H5public.h
                ./src/H5FD*.h except ./src/H5FDprivate.h,
                ./src/H5api_adpt.h

            The main header file:
                ./src/hdf5.h

            The configuration information:
                ./src/H5pubconf.h
        
        The support programs that are useful are:
            ./tools/h5ls/h5ls          (lists file contents)
            ./tools/h5dump/h5dump      (dumps file contents)
            ./tools/h5repack/h5repack  (repacks HDF5 file)
            ./tools/h5jam/h5jam(unjam) (adds/removes user block to/from 
                                           HDF5 file)
            ./tools/misc/h5repart      (repartitions file families)
            ./tools/misc/h5debug       (low-level file debugging)
            ./tools/h5import/h5import  (imports data to HDF5 file)
            ./tools/h5diff/h5diff      (compares two HDF5 files)
            ./hl//tools/h52gif/h52gif  (HDF5 to GIF converter) 
            ./hl//tools/gif2h5/gif2h5  (GIF to HDF5 converter)


5. Using the Library
        Please see the HDF5 User's Guide and the HDF5 Reference Manual 
        in the HDF5 documentation.

        C programs must include <hdf5.h> and link with the HDF5 Libraries.
        Additional libraries may also be necessary depending on whether
        support for compression, etc., was compiled into the HDF5 Library.

        A summary of the current HDF5 installation can be found in the
        libhdf5.settings and libhdf5_fortran.settings files in the bin
        subdirectory. 

        Users are encouraged to use the helper compiler scripts h5cc, h5fc, 
        and h5c++ to build HDF5 C, Fortran, and C++ applications, 
        respectively.  Those scripts are installed under the bin subdirectory 
        when 'make install' is run.

        Scripts inherit flags used during library compilation.  Users may 
        examine these and other flags used by a script by typing the script 
        name with the '-echo' option:
            <script> -echo
        The script may then be edited as needed.


5.1. Using the C++ API
        To use the C++ API, one must include the header file H5Cpp.h
        in the application.  Please refer to the examples in c++/examples
        for sample code.

        A Doxygen-generated Reference Manual for the C++ API is provided 
        in the HDF5 documentation.  If an updated version or a different 
        format is desired, users can re-generate this document with Doxygen.

        When running in c++/src, Doxygen will put the generated html 
        files in doc/html/cpplus_RM.  Users may specify a different
        location by editing the field OUTPUT_DIRECTORY in the configuration
        file c++/src/cpp_doc_config.  The field HTML_STYLESHEET specifies
        the stylesheet that can be used to change the document layout.


6. Support
        Support is described in the README file.