*************************************************************************
*          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 MPI and MPI-IO
        3. HDF5 Source Code and Precompiled Binaries
        4. Build and Install HDF5 Libraries and Tools with CMake
        5. 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. 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

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

5. Quick Start Presets
        You want to build HDF5 with CMake, but there are so many options to consider.

5.1. Solution
        CMake introduced presets in version 3.19. HDF Group provides a file in the source,
        CMakePresets.json, requiring CMake 3.24 or higher, that 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.

5.2. Discussion
        The CMakePresets.json file is located in the root directory of the HDF5 source.
        It is from here you will execute the cmake command to build HDF5. The following
        example shows how to build HDF5 with the CMakePresets.json file:
          - change directory to the hdf5 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.

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

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

