FindHDF5

Finds Hierarchical Data Format (HDF5), a library for reading and writing self-describing array data:

find_package(HDF5 [<version>] [COMPONENTS <components>...] [...])

If the HDF5 library is built using its CMake-based build system, it will as of HDF5 version 1.8.15 provide its own CMake Package Configuration file (hdf5-config.cmake) for use with the find_package() command in config mode. By default, this module searches for this file and, if found, returns the results based on the found configuration.

If the upstream configuration file is not found, this module falls back to module mode and invokes the HDF5 wrapper compiler typically installed with the HDF5 library. Depending on the configuration, this wrapper compiler is named either h5cc (serial) or h5pcc (parallel). If found, the wrapper is queried with the -show argument to determine the compiler and linker flags required for building an HDF5 client application. Both serial and parallel versions of the HDF5 wrapper are considered. The first directory containing either is used. If both versions are found in the same directory, the serial version is preferred by default. To change this behavior, set the variable HDF5_PREFER_PARALLEL to TRUE.

In addition to finding the include directories and libraries needed to compile an HDF5 application, this module also attempts to find additional tools provided by the HDF5 distribution, which can be useful for regression testing or development workflows.

Components

This module supports optional components, which can be specified with the find_package() command:

find_package(HDF5 [COMPONENTS <components>...])

Supported components include:

C

Finds the HDF5 C library (C bindings).

CXX

Finds the HDF5 C++ library (C++ bindings).

Fortran

Finds the HDF5 Fortran library (Fortran bindings).

HL

This component can be used in combination with other components to find the high-level (HL) HDF5 library variants for C, CXX, and/or Fortran, which provide high-level functions.

If no components are specified, then this module will by default search for the C component.

Imported Targets

This module provides the following Imported Targets:

HDF5::HDF5

Added in version 3.19.

Target encapsulating the usage requirements for all found HDF5 binding libraries (HDF5_LIBRARIES), available if HDF5 and all required components are found.

hdf5::hdf5

Added in version 3.19.

Target encapsulating the usage requirements for the HDF5 C library, available if HDF5 library and its C component are found.

hdf5::hdf5_cpp

Added in version 3.19.

Target encapsulating the usage requirements for the HDF5 C and C++ libraries, available if HDF5 library, and its C and CXX components are found.

hdf5::hdf5_fortran

Added in version 3.19.

Target encapsulating the usage requirements for the HDF5 Fortran library, available if HDF5 library and its Fortran component are found.

hdf5::hdf5_hl

Added in version 3.19.

Target encapsulating the usage requirements for the HDF5 high-level C library, available if HDF5 library and its C, and HL components are found.

hdf5::hdf5_hl_cpp

Added in version 3.19.

High-level C++ library.

Target encapsulating the usage requirements for the HDF5 high-level C and high-level C++ libraries, available if HDF5 library and its C, CXX, and HL components are found.

hdf5::hdf5_hl_fortran

Added in version 3.19.

Target encapsulating the usage requirements for the HDF5 high-level Fortran library, available if HDF5 library and its Fortran, and HL components are found.

hdf5::h5diff

Added in version 3.19.

Imported executable target encapsulating the usage requirements for the h5diff executable, available if h5diff is found.

Result Variables

This module defines the following variables:

HDF5_FOUND

Boolean indicating whether (the requested version of) HDF5 was found.

HDF5_VERSION

Added in version 3.3.

The version of HDF5 library found.

HDF5_INCLUDE_DIRS

Include directories containing header files needed to use HDF5.

HDF5_DEFINITIONS

Required compiler definitions for using HDF5.

HDF5_LIBRARIES

Libraries of all requested bindings needed to link against to use HDF5.

HDF5_HL_LIBRARIES

Required libraries for the HDF5 high-level API for all bindings, if the HL component is enabled.

HDF5_IS_PARALLEL

Boolean indicating whether the HDF5 library has parallel IO support.

For each enabled language binding component, a corresponding HDF5_<LANG>_LIBRARIES variable, and potentially HDF5_<LANG>_DEFINITIONS, will be defined. If the HL component is enabled, then HDF5_<LANG>_HL_LIBRARIES variables will also be defined:

HDF5_C_DEFINITIONS

Required compiler definitions for HDF5 C bindings.

HDF5_CXX_DEFINITIONS

Required compiler definitions for HDF5 C++ bindings.

HDF5_Fortran_DEFINITIONS

Required compiler definitions for HDF5 Fortran bindings.

HDF5_C_INCLUDE_DIRS

Required include directories for HDF5 C bindings.

HDF5_CXX_INCLUDE_DIRS

Required include directories for HDF5 C++ bindings.

HDF5_Fortran_INCLUDE_DIRS

Required include directories for HDF5 Fortran bindings.

HDF5_C_LIBRARIES

Required libraries for the HDF5 C bindings.

HDF5_CXX_LIBRARIES

Required libraries for the HDF5 C++ bindings.

HDF5_Fortran_LIBRARIES

Required libraries for the HDF5 Fortran bindings.

HDF5_C_HL_LIBRARIES

Required libraries for the high-level C bindings, if the HL component is enabled.

HDF5_CXX_HL_LIBRARIES

Required libraries for the high-level C++ bindings, if the HL component is enabled.

HDF5_Fortran_HL_LIBRARIES

Required libraries for the high-level Fortran bindings, if the HL component is enabled.

Cache Variables

The following cache variables may also be set:

HDF5_C_COMPILER_EXECUTABLE

The path to the HDF5 C wrapper compiler.

HDF5_CXX_COMPILER_EXECUTABLE

The path to the HDF5 C++ wrapper compiler.

HDF5_Fortran_COMPILER_EXECUTABLE

The path to the HDF5 Fortran wrapper compiler.

HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE

Added in version 3.6.

The path to the primary C compiler which is also the HDF5 wrapper. This variable is used only in module mode.

HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE

Added in version 3.6.

The path to the primary C++ compiler which is also the HDF5 wrapper. This variable is used only in module mode.

HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE

Added in version 3.6.

The path to the primary Fortran compiler which is also the HDF5 wrapper. This variable is used only in module mode.

HDF5_DIFF_EXECUTABLE

The path to the HDF5 dataset comparison tool (h5diff).

Hints

The following variables can be set before calling the find_package(HDF5) to guide the search for HDF5 library:

HDF5_PREFER_PARALLEL

Added in version 3.4.

Set this to boolean true to prefer parallel HDF5 (by default, serial is preferred). This variable is used only in module mode.

HDF5_FIND_DEBUG

Added in version 3.9.

Set this to boolean true to get extra debugging output by this module.

HDF5_NO_FIND_PACKAGE_CONFIG_FILE

Added in version 3.8.

Set this to boolean true to skip finding and using CMake package configuration file (hdf5-config.cmake).

HDF5_USE_STATIC_LIBRARIES

Set this to boolean value to determine whether or not to prefer a static link to a dynamic link for HDF5 and all of its dependencies.

Added in version 3.10: Support for HDF5_USE_STATIC_LIBRARIES on Windows.

Examples

Examples: Finding HDF5

Finding HDF5:

find_package(HDF5)

Specifying a minimum required version of HDF5 to find:

find_package(HDF5 1.8.15)

Finding HDF5 and making it required (if HDF5 is not found, processing stops with an error message):

find_package(HDF5 1.8.15 REQUIRED)

Searching for static HDF5 libraries:

set(HDF5_USE_STATIC_LIBRARIES TRUE)
find_package(HDF5)

Specifying components to find high-level C and C++ functions:

find_package(HDF5 COMPONENTS C CXX HL)

Examples: Using HDF5

Finding HDF5 and linking it to a project target:

find_package(HDF5)
target_link_libraries(project_target PRIVATE HDF5::HDF5)

Using Fortran HDF5 and HDF5-HL functions:

find_package(HDF5 COMPONENTS Fortran HL)
target_link_libraries(project_target PRIVATE HDF5::HDF5)