# 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/](https://forum.hdfgroup.org/)
* **HDF Helpdesk:** [https://help.hdfgroup.org/](https://help.hdfgroup.org/)

---

## Table of Contents

* [1. Obtaining HDF5](#1-obtaining-hdf5)
* [2. Third-party Software Requirements](#2-third-party-software-requirements)
    * [2.1. zlib](#21-zlib)
    * [2.2. Szip (optional)](#22-szip-optional)
    * [2.3. Compression Plugins](#23-compression-plugins)
    * [2.4. MPI and MPI-IO](#24-mpi-and-mpi-io)
* [3. HDF5 Source Code and Precompiled Binaries](#3-hdf5-source-code-and-precompiled-binaries)
    * [3.1. Build and Install HDF5 Libraries and Tools with CMake](#31-build-and-install-hdf5-libraries-and-tools-with-cmake)
* [4. Quick Start Presets](#4-quick-start-presets)
    * [4.1. Solution](#41-solution)
    * [4.2. Discussion](#42-discussion)
    * [4.3. Customization](#43-customization)
    * [4.4. See Also](#44-see-also)

---

## 1. Obtaining HDF5

The latest supported public releases of HDF5 are available on the [HDF5 GitHub repository](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 (optional)

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](https://github.com/HDFGroup/hdf5/releases)

### 3.1. Build and Install HDF5 Libraries and Tools with CMake

See the [INSTALL_CMake.md](./INSTALL_CMake.md) file for detailed instructions.

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

* **Library Source File:** Builds 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.

* **HDF5Examples Source File:** Builds 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:

```bash
# Change directory to the source folder
$ cd <source-folder>

# Execute the workflow
$ cmake --workflow --preset ci-StdShar-<compiler-type> --fresh
```
> **Note:** `<compiler-type>` should be replaced with `GNUC`, `MSVC`, or `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 the [INSTALL_CMake.md](./INSTALL_CMake.md) file.

### 4.4. See Also

See CMake documentation for details on presets:
[https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html)