*************************************************************************
*          Installation Instructions for HDF5                           *
*************************************************************************

Instructions for the Installation of HDF5 Software
==================================================

This file provides instructions for installing the HDF5 software.

For help with installing, questions can be posted to the HDF Forum or sent to the HDF Helpdesk:

   HDF Forum:     https://forum.hdfgroup.org/
   HDF Helpdesk:  https://help.hdfgroup.org/

CONTENTS
--------
        1. Obtaining HDF5
        2. Third-party Software Requirements
        2.1 zlib
        2.2 Szip (optional)
        2.3 compression plugins
        2.4 MPI and MPI-IO
        3. HDF5 Source Code and Precompiled Binaries
        3.1. Build and Install HDF5 Libraries and Tools with CMake
        4. Quick Start Presets

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

1. Obtaining HDF5
        The latest supported public releases of HDF5 are available on
        https://github.com/HDFGroup/hdf5.

2. Third-party Software Requirements
        To see what compression was configured into a built HDF5 library,
        check the "I/O filters (external):" line in the libhdf5.settings file.
        Also, the hdf5-config.cmake file contains the list of configuration
        options used to build the library.

2.1. zlib
        The HDF5 library includes a predefined compression filter that
        uses the "deflate" method for chunked datasets.

2.2. szip
        The HDF5 library includes a predefined compression filter that
        uses the extended-Rice lossless compression algorithm for chunked
        datasets.

2.3. compression plugins
        The HDF5 plugins project, https://github.com/HDFGroup/hdf5_plugins, provides
        compression libraries that can be used at runtime with the hdf5 shared
        library.

2.4. 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.

3. HDF5 Source Code and Precompiled Binaries
        The HDF Group provides source code and pre-compiled binaries from the
        HDF5 GitHub releases page:

        https://github.com/HDFGroup/hdf5/releases

3.1. Build and Install HDF5 Libraries and Tools with CMake
        see the release_docs/INSTALL_CMake.txt file.

4. Quick Start Presets
        You want to build HDF5 with CMake or use an installed HDF5 binary with CMake,
        but there are so many options to consider.

4.1. Solution
        CMake introduced presets in version 3.19. HDF Group provides a file in the source,
        CMakePresets.json, requiring CMake 3.26 or higher. This file is in the HDF5 library
        source as well as the HDF5Examples source of the installed binary.
          The library source file will build HDF5 with the options for building a typical
        shared library with the common languages for a platform. The features include building
        the tools, examples, plugins, and the shared and static libraries.
          The HDF5Examples source file will build the examples with the components that were
        enabled by the options selected when the install HDF5 library was built. The typical
        library built by HDF5 and available from the HDF5 Releases page includes C, Java, and Fortran
        compilers along with the tools, examples, plugins, and the shared and static libraries.

4.2. Discussion
        The CMakePresets.json file is located in the root directory of the HDF5 source and
        the HDF5Examples source of the installed binary.
        It is from here you will execute the cmake command to build HDF5. The following
        example shows how to build HDF5 or examples with the CMakePresets.json file:
          - change directory to the source folder
          - execute "cmake --workflow --preset ci-StdShar-<compiler-type> --fresh"
                where "<compiler-type>" is GNUC, MSVC, Clang

        The above example will create a "build" folder in the source parent directory, which
        will contain the results of the build, including installation package files when the
        library is built.

4.3. Customization
        See the HDF5 documentation for more on presets, especially the presets section in:
          - release_docs/INSTALL_CMake.txt file

4.4. See Also
        See CMake documentation for details on presets:
          - https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html

