Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5 2.0.0
API Reference
Building with CMake Presets

Building HDF5 with CMake

Problem
You want to build HDF5 with CMake, but there are so many options to consider.
Solution
CMake introduced presets in version 3.19. HDF Group provides a 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.
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 or 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.
See Also
See CMake documentation for details on presets:

CMake Presets Use Case: Static Library and Tools

Problem
I want to build the HDF5 library statically and include the tools.
Solution
Static libraries can be built with zlib and libaec - but cannot be built with plugins or Java.

Create a CMakeUserPresets.json file with the following content:

{
"version": 6,
"cmakeMinimumRequired": {
"major": 3,
"minor": 24,
"patch": 0
},
"configurePresets": [
{
"name": "my-Static-Tools",
"hidden": true,
"description": "Build HDF5 with static library and tools",
"inherits": ["ci-base", "ci-CompressionVars", "ci-StdExamples"],
"cacheVariables": {
"HDF_PACKAGE_NAMESPACE": {"type": "STRING", "value": "hdf5::"},
"HDF5_BUILD_SHARED_LIBS": "OFF",
"HDF5_BUILD_TOOLS": "ON",
"HDF5_ENABLE_ZLIB_SUPPORT": "ON",
"HDF5_ENABLE_LIBAEC": "ON",
"HDF5_ENABLE_PLUGIN_SUPPORT": "OFF"
}
},
{
"name": "my-Static-Tools-MSVC",
"description": "MSVC Standard Config for x64 (Release)",
"inherits": [
"ci-x64-Release-MSVC",
"ci-CPP",
"my-Static-Tools"
]
},
{
"name": "my-Static-Tools-Clang",
"description": "Clang Standard Config for x64 (Release)",
"inherits": [
"ci-x64-Release-Clang",
"ci-CPP",
"ci-Fortran",
"my-Static-Tools"
]
},
{
"name": "my-Static-Tools-GNUC",
"description": "GNUC Standard Config for x64 (Release)",
"inherits": [
"ci-x64-Release-GNUC",
"ci-CPP",
"ci-Fortran",
"my-Static-Tools"
]
},
{
"name": "my-Static-Tools-macos-GNUC",
"description": "GNUC Standard Config for macos (Release)",
"inherits": [
"ci-macos-Release-GNUC",
"ci-CPP",
"my-Static-Tools"
]
}
],
"buildPresets": [
{
"name": "my-Static-Tools-MSVC",
"description": "MSVC Standard Build for x64 (Release)",
"configurePreset": "my-Static-Tools-MSVC",
"inherits": [
"ci-x64-Release-MSVC"
]
},
{
"name": "my-Static-Tools-Clang",
"description": "Clang Standard Build for x64 (Release)",
"configurePreset": "my-Static-Tools-Clang",
"inherits": [
"ci-x64-Release-Clang"
]
},
{
"name": "my-Static-Tools-GNUC",
"description": "GNUC Standard Build for x64 (Release)",
"configurePreset": "my-Static-Tools-GNUC",
"inherits": [
"ci-x64-Release-GNUC"
]
},
{
"name": "my-Static-Tools-macos-GNUC",
"description": "GNUC Standard Build for macos (Release)",
"configurePreset": "my-Static-Tools-macos-GNUC",
"verbose": true,
"inherits": [
"ci-macos-Release-GNUC"
]
}
],
"testPresets": [
{
"name": "my-Static-Tools-MSVC",
"configurePreset": "my-Static-Tools-MSVC",
"inherits": [
"ci-x64-Release-MSVC"
]
},
{
"name": "my-Static-Tools-Clang",
"configurePreset": "my-Static-Tools-Clang",
"inherits": [
"ci-x64-Release-Clang"
]
},
{
"name": "my-Static-Tools-GNUC",
"configurePreset": "my-Static-Tools-GNUC",
"inherits": [
"ci-x64-Release-GNUC"
]
},
{
"name": "my-Static-Tools-macos-GNUC",
"configurePreset": "my-Static-Tools-macos-GNUC",
"inherits": [
"ci-macos-Release-GNUC"
]
}
],
"packagePresets": [
{
"name": "my-Static-Tools-MSVC",
"configurePreset": "my-Static-Tools-MSVC",
"inherits": "ci-x64-Release-MSVC"
},
{
"name": "my-Static-Tools-Clang",
"configurePreset": "my-Static-Tools-Clang",
"inherits": "ci-x64-Release-Clang"
},
{
"name": "my-Static-Tools-GNUC",
"configurePreset": "my-Static-Tools-GNUC",
"inherits": "ci-x64-Release-GNUC"
},
{
"name": "my-Static-Tools-macos-GNUC",
"configurePreset": "my-Static-Tools-macos-GNUC",
"inherits": "ci-macos-Release-GNUC"
}
],
"workflowPresets": [
{
"name": "my-Static-Tools-MSVC",
"steps": [
{"type": "configure", "name": "my-Static-Tools-MSVC"},
{"type": "build", "name": "my-Static-Tools-MSVC"},
{"type": "test", "name": "my-Static-Tools-MSVC"},
{"type": "package", "name": "my-Static-Tools-MSVC"}
]
},
{
"name": "my-StdShar-Clang",
"steps": [
{"type": "configure", "name": "my-Static-Tools-Clang"},
{"type": "build", "name": "my-Static-Tools-Clang"},
{"type": "test", "name": "my-Static-Tools-Clang"},
{"type": "package", "name": "my-Static-Tools-Clang"}
]
},
{
"name": "my-StdShar-GNUC",
"steps": [
{"type": "configure", "name": "my-Static-Tools-GNUC"},
{"type": "build", "name": "my-Static-Tools-GNUC"},
{"type": "test", "name": "my-Static-Tools-GNUC"},
{"type": "package", "name": "my-Static-Tools-GNUC"}
]
},
{
"name": "my-Static-Tools-macos-GNUC",
"steps": [
{"type": "configure", "name": "my-Static-Tools-macos-GNUC"},
{"type": "build", "name": "my-Static-Tools-macos-GNUC"},
{"type": "test", "name": "my-Static-Tools-macos-GNUC"},
{"type": "package", "name": "my-Static-Tools-macos-GNUC"}
]
}
]
}
Discussion
The above example shows how to build HDF5 with a static library and tools. The CMakeUserPresets.json file is located in the root directory of the HDF5 source. It is from here you execute:
  • cmake –workflow –preset my-Static-Tools-<compiler-type> –fresh
    where "<compiler-type>" is GNUC or MSVC or Clang or macos-GNUC
If you don't need cross-compiler or cross-platform support, you can remove the compiler-specific presets and use the "my-Static-Tools" preset directly.
See Also
Default CMakePresets.json Settings for details on the default settings for the StdShar presets.

CMake Presets Use Case: S3 on linux

Problem
I want to build the HDF5 library with the ros3 vfd.
Solution
Create a CMakeUserPresets.json file with the following content:
{
"version": 6,
"cmakeMinimumRequired": {
"major": 3,
"minor": 24,
"patch": 0
},
"configurePresets": [
{
"name": "my-linux-S3",
"hidden": true,
"description": "Build HDF5 with library and tools for S3",
"inherits": ["ci-base", "ci-S3", "ci-CompressionVars", "ci-StdExamples", "ci-StdPlugins"],
"cacheVariables": {
"HDF_PACKAGE_NAMESPACE": {"type": "STRING", "value": "hdf5::"},
"HDF5_BUILD_SHARED_LIBS": "ON",
"HDF5_BUILD_TOOLS": "ON",
"HDF5_ENABLE_ZLIB_SUPPORT": "ON",
"HDF5_ENABLE_LIBAEC": "ON",
"HDF5_ENABLE_PLUGIN_SUPPORT": "ON"
}
},
{
"name": "my-linux-S3-Clang",
"description": "Clang Standard Config for x64 (Release)",
"inherits": [
"ci-x64-Release-Clang",
"ci-CPP",
"ci-Fortran",
"my-linux-S3"
]
},
{
"name": "my-linux-S3-GNUC",
"description": "GNUC Standard Config for x64 (Release)",
"inherits": [
"ci-x64-Release-GNUC",
"ci-CPP",
"ci-Fortran",
"my-linux-S3"
]
}
],
"buildPresets": [
{
"name": "my-linux-S3-Clang",
"description": "Clang Standard Build for x64 (Release)",
"configurePreset": "my-linux-S3-Clang",
"inherits": [
"ci-x64-Release-Clang"
]
},
{
"name": "my-linux-S3-GNUC",
"description": "GNUC Standard Build for x64 (Release)",
"configurePreset": "my-linux-S3-GNUC",
"inherits": [
"ci-x64-Release-GNUC"
]
}
],
"testPresets": [
{
"name": "my-linux-S3-Clang",
"configurePreset": "my-linux-S3-Clang",
"inherits": [
"ci-x64-Release-Clang"
]
},
{
"name": "my-linux-S3-GNUC",
"configurePreset": "my-linux-S3-GNUC",
"inherits": [
"ci-x64-Release-GNUC"
]
}
],
"packagePresets": [
{
"name": "my-linux-S3-Clang",
"configurePreset": "my-linux-S3-Clang",
"inherits": "ci-x64-Release-Clang"
},
{
"name": "my-linux-S3-GNUC",
"configurePreset": "my-linux-S3-GNUC",
"inherits": "ci-x64-Release-GNUC"
}
],
"workflowPresets": [
{
"name": "my-linux-S3-Clang",
"steps": [
{"type": "configure", "name": "my-linux-S3-Clang"},
{"type": "build", "name": "my-linux-S3-Clang"},
{"type": "test", "name": "my-linux-S3-Clang"},
{"type": "package", "name": "my-linux-S3-Clang"}
]
},
{
"name": "my-linux-S3-GNUC",
"steps": [
{"type": "configure", "name": "my-linux-S3-GNUC"},
{"type": "build", "name": "my-linux-S3-GNUC"},
{"type": "test", "name": "my-linux-S3-GNUC"},
{"type": "package", "name": "my-linux-S3-GNUC"}
]
}
]
}
Discussion
The above example shows how to build HDF5 with a static library and tools. The CMakeUserPresets.json file is located in the root directory of the HDF5 source. It is from here you execute:
  • cmake –workflow –preset my-S3-<compiler-type> –fresh
    where "<compiler-type>" is GNUC or Clang or macos-GNUC
If you don't need cross-compiler support, you can remove the compiler-specific presets and use the "my-linux-S3" preset directly.
See Also
Default CMakePresets.json Settings for details on the default settings for the StdShar presets.

CMake Presets Use Case: Parallel Library

Problem
I want to build the HDF5 library with a parallel compiler.
Solution
Create a CMakeUserPresets.json file with the following content:
{
"version": 6,
"cmakeMinimumRequired": {
"major": 3,
"minor": 24,
"patch": 0
},
"configurePresets": [
{
"name": "my-linux-par",
"hidden": true,
"description": "Build HDF5 with library and tools using parallel compiler",
"inherits": ["ci-base", "ci-CompressionVars", "ci-StdExamples"],
"environment": {
"CC": "mpicc"
},
"cacheVariables": {
"HDF_PACKAGE_NAMESPACE": {"type": "STRING", "value": "hdf5::"},
"HDF5_BUILD_SHARED_LIBS": "ON",
"HDF5_BUILD_TOOLS": "ON",
"MPIEXEC_NUMPROC_FLAG": "-n",
"MPIEXEC_MAX_NUMPROCS": "2",
"HDF5_ENABLE_PARALLEL": "ON",
"HDF5_ENABLE_SUBFILING_VFD": "OFF",
"HDF5_ENABLE_ZLIB_SUPPORT": "ON",
"HDF5_ENABLE_LIBAEC": "ON",
"HDF5_ENABLE_PLUGIN_SUPPORT": "OFF"
}
},
{
"name": "my-linux-par-mpich",
"description": "mpich Standard Config for x64 (Release)",
"inherits": [
"ci-x64-Release-GNUC",
"my-linux-par"
]
}
],
"buildPresets": [
{
"name": "my-linux-par-mpich",
"description": "mpich Standard Build for x64 (Release)",
"configurePreset": "my-linux-par-mpich",
"inherits": [
"ci-x64-Release-GNUC"
]
}
],
"testPresets": [
{
"name": "my-linux-serial-mpich",
"configurePreset": "my-linux-par-mpich",
"inherits": [
"ci-x64-Release-GNUC"
],
"filter": {
"exclude": {
"name": "MPI_TEST"
}
}
},
{
"name": "my-linux-par-mpich",
"configurePreset": "my-linux-par-mpich",
"inherits": [
"ci-x64-Release-GNUC"
],
"filter": {
"include": {
"name": "MPI_TEST"
}
}
}
],
"packagePresets": [
{
"name": "my-linux-par-mpich",
"configurePreset": "my-linux-par-mpich",
"inherits": "ci-x64-Release-GNUC"
}
],
"workflowPresets": [
{
"name": "my-linux-par-mpich",
"steps": [
{"type": "configure", "name": "my-linux-par-mpich"},
{"type": "build", "name": "my-linux-par-mpich"},
{"type": "test", "name": "my-linux-serial-mpich"},
{"type": "test", "name": "my-linux-par-mpich"},
{"type": "package", "name": "my-linux-par-mpich"}
]
}
]
}
Discussion
The above example shows how to build HDF5 with a parallel compiler. The CMakeUserPresets.json file is located in the root directory of the HDF5 source. It is from here you execute:
  • cmake –workflow –preset my-linux-par-GNUC –fresh
See Also
Default CMakePresets.json Settings for details on the default settings for the StdShar presets.

CMake Presets

Presets are a way to store a set of CMake cache variables in a file. This allows you to save and load a set of variables that you use frequently. Presets can be used to save the configuration of a project for different build configurations, such as Debug and Release.

CMake supports two main files, CMakePresets.json and CMakeUserPresets.json, that allow users to specify common configure options and share them with others. CMake also supports files included with the include field.

CMakePresets.json

HDF Group provides a CMakePresets.json file, used by the github workflows, that includes the following StdShar presets:

  • ci-StdShar-MSVC - use MSVC compiler
  • ci-StdShar-Clang - use Clang compiler
  • ci-StdShar-macos-Clang -Apple Clang compiler
  • ci-StdShar-GNUC - use GNU compiler
  • ci-StdShar-macos-GNUC - use Apple GNU compiler
  • ci-StdShar-GNUC-S3 - use GNU compiler with S3 support
  • ci-StdShar-Intel - use Intel OneAPI compiler
  • ci-StdShar-win-Intel - use Intel OneAPI compiler on Windows

The StdShar presets are used by the GitHub workflows to build and test the HDF5 library on different platforms and compilers. The CMakePresets.json file is located in the root directory of the HDF5 repository. The StdShar presets inherit the following settings:

  • ci-CPP - enables C++ support
  • ci-Fortran - enables Fortran support, except on macOS
  • ci-Java - enables Java support
  • ci-StdShar - described below

The ci-StdShar preset inherits the following settings:

  • ci-StdCompression
  • ci-StdExamples
  • ci-StdPlugins

See the CMakePresets.json file for the complete list of presets and settings. The Default CMakePresets.json Settings section provides an overview of the default settings for the StdShar presets.

Default CMakePresets.json Settings

The ci-StdShar preset sets the following cache variables:

  • "HDF_PACKAGE_NAMESPACE": {"type": "STRING", "value": "hdf5::"}
  • "HDF5_INSTALL_MOD_FORTRAN": "NO"
  • "HDF5_BUILD_GENERATORS": "ON"
  • "HDF5_ENABLE_ALL_WARNINGS": "ON"
  • "HDF5_MINGW_STATIC_GCC_LIBS": "ON"
  • "HDF_TEST_EXPRESS": "2"

The ci-StdExamples preset inherits the following settings:

  • ci-base
  • ci-base-tgz

The ci-StdExamples preset sets the following cache variables:

  • "HDF5_PACK_EXAMPLES": "ON"
  • "EXAMPLES_DOWNLOAD": "ON"

The ci-StdPlugins preset inherits the following settings:

  • ci-base-plugins
  • ci-PluginsVars
  • ci-base-tgz

The ci-StdPlugins preset sets the following cache variables:

  • "PLUGIN_USE_LOCALCONTENT": "OFF"

The ci-PluginsVars preset sets the following cache variables:

  • "HDF5_ENABLE_PLUGIN_SUPPORT": "ON"
  • "H5PL_ALLOW_EXTERNAL_SUPPORT": {"type": "STRING", "value": "TGZ"}
  • "PLUGIN_PACKAGE_NAME": {"type": "STRING", "value": "pl"}
  • "PLUGIN_TGZ_ORIGPATH": {"type": "STRING", "value": "https://github.com/HDFGroup/hdf5_plugins/releases/download/snapshot"}
  • "PLUGIN_TGZ_NAME": {"type": "STRING", "value": "hdf5_plugins-master.tar.gz"}

The ci-base-plugins preset sets the following cache variables:

  • "BSHUF_TGZ_NAME": {"type": "STRING", "value": "bitshuffle-0.5.2.tar.gz"}
  • "BSHUF_PACKAGE_NAME": {"type": "STRING", "value": "bshuf"}
  • "BLOSC_TGZ_NAME": {"type": "STRING", "value": "c-blosc-1.21.6.tar.gz"}
  • "BLOSC_PACKAGE_NAME": {"type": "STRING", "value": "blosc"}
  • "BLOSC_ZLIB_TGZ_NAME": {"type": "STRING", "value": "zlib-1.3.1.tar.gz"}
  • "BLOSC_ZLIB_PACKAGE_NAME": {"type": "STRING", "value": "zlib"}
  • "BLOSC2_TGZ_NAME": {"type": "STRING", "value": "c-blosc2-2.15.2.tar.gz"}
  • "BLOSC2_PACKAGE_NAME": {"type": "STRING", "value": "blosc2"}
  • "BLOSC2_ZLIB_TGZ_NAME": {"type": "STRING", "value": "zlib-1.3.1.tar.gz"}
  • "BLOSC2_ZLIB_PACKAGE_NAME": {"type": "STRING", "value": "zlib"}
  • "BZ2_TGZ_NAME": {"type": "STRING", "value": "bzip2-bzip2-1.0.8.tar.gz"}
  • "BZ2_PACKAGE_NAME": {"type": "STRING", "value": "bz2"}
  • "FPZIP_TGZ_NAME": {"type": "STRING", "value": "fpzip-1.3.0.tar.gz"}
  • "FPZIP_PACKAGE_NAME": {"type": "STRING", "value": "fpzip"}
  • "JPEG_TGZ_NAME": {"type": "STRING", "value": "jpegsrc.v9e.tar.gz"}
  • "JPEG_PACKAGE_NAME": {"type": "STRING", "value": "jpeg"}
  • "BUILD_LZ4_LIBRARY_SOURCE": "ON"
  • "LZ4_TGZ_NAME": {"type": "STRING", "value": "lz4-1.10.0.tar.gz"}
  • "LZ4_PACKAGE_NAME": {"type": "STRING", "value": "lz4"}
  • "LZF_TGZ_NAME": {"type": "STRING", "value": "liblzf-3.6.tar.gz"}
  • "LZF_PACKAGE_NAME": {"type": "STRING", "value": "lzf"}
  • "SZ_TGZ_NAME": {"type": "STRING", "value": "SZ-2.1.12.5.tar.gz"}
  • "SZ_PACKAGE_NAME": {"type": "STRING", "value": "SZ"}
  • "ZFP_TGZ_NAME": {"type": "STRING", "value": "zfp-1.0.1.tar.gz"}
  • "ZFP_PACKAGE_NAME": {"type": "STRING", "value": "zfp"}
  • "ZSTD_TGZ_NAME": {"type": "STRING", "value": "zstd-1.5.6.tar.gz"}
  • "ZSTD_PACKAGE_NAME": {"type": "STRING", "value": "zstd"}

The ci-StdCompression preset inherits the following settings:

  • ci-base-tgz
  • ci-CompressionVars

The ci-StdCompression preset sets the following cache variables:

  • "HDF5_PACKAGE_EXTLIBS": "ON"
  • "HDF5_USE_ZLIB_NG": "OFF"
  • "ZLIB_USE_LOCALCONTENT": "OFF"
  • "LIBAEC_USE_LOCALCONTENT": "OFF"
  • "HDF5_USE_ZLIB_STATIC": "ON"
  • "HDF5_USE_LIBAEC_STATIC": "ON"

The ci-CompressionVars preset sets the following cache variables:

  • "ZLIB_PACKAGE_NAME": {"type": "STRING", "value": "zlib"}
  • "ZLIB_TGZ_ORIGPATH": {"type": "STRING", "value": "https://github.com/madler/zlib/releases/download/v1.3.1"}
  • "ZLIB_TGZ_NAME": {"type": "STRING", "value": "zlib-1.3.1.tar.gz"}
  • "ZLIBNG_PACKAGE_NAME": {"type": "STRING", "value": "zlib-ng"}
  • "ZLIBNG_TGZ_ORIGPATH": {"type": "STRING", "value": "https://github.com/zlib-ng/zlib-ng/archive/refs/tags"}
  • "ZLIBNG_TGZ_NAME": {"type": "STRING", "value": "2.2.2.tar.gz"}
  • "LIBAEC_PACKAGE_NAME": {"type": "STRING", "value": "libaec"}
  • "LIBAEC_TGZ_ORIGPATH": {"type": "STRING", "value": "https://github.com/MathisRosenhauer/libaec/releases/download/v1.1.3"}
  • "LIBAEC_TGZ_NAME": {"type": "STRING", "value": "libaec-1.1.3.tar.gz"}

The ci-base-tgz preset inherits the following settings:

  • ci-base

The ci-base-tgz preset sets the following cache variables:

  • "HDF5_ALLOW_EXTERNAL_SUPPORT": {"type": "STRING", "value": "TGZ"}
  • "TGZPATH": {"type": "PATH", "value": "${sourceParentDir}/temp"}

The ci-base preset sets the following CMake variables:

  • "name": "ci-base"
  • "displayName": "Basic Config"
  • "description": "Basic build using Ninja generator"
  • "generator": "Ninja"
  • "binaryDir": "${sourceParentDir}/build/${presetName}"
  • "installDir": "${sourceParentDir}/install/${presetName}"