Skip to content

Latest commit

 

History

History
1525 lines (1164 loc) · 66.5 KB

INSTALL_CMake.md

File metadata and controls

1525 lines (1164 loc) · 66.5 KB

Build and Install HDF5 C, C++, Fortran, High-Level Libraries and Tools with CMake

Table of Contents

I. Preconditions

Obtaining HDF5 source code

  1. Create a directory for your development; for example, myhdfstuff.
  2. Obtain HDF5 source from Github:
  3. Obtain HDF5 plugin source from Github:
    • development branch: https://github.com/HDFGroup/hdf5_plugins
    • OR let the CMake build process download the plugins for you with the following options:
      • HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="GIT" (or "TGZ")
      • HDF5_ENABLE_PLUGIN_SUPPORT:BOOL=ON

CMake version

  1. We suggest you obtain the latest CMake from the Kitware web site. The HDF5 2."X"."Y" product requires a minimum CMake version 3.26.

Note: To change the install prefix from the platform defaults initialize the CMake variable, CMAKE_INSTALL_PREFIX. Users of build scripts will use the INSTALLDIR option.

Note: See the CMake documentation for more information on setting the logging levels: CMAKE_MESSAGE_LOG_LEVEL.

II. RECOMMENDED: Quick Start with CMake Presets

⭐ This is the RECOMMENDED method for building HDF5 2.0 and later.

Prerequisites

  • CMake 3.26 or later (required for HDF5 2.0)
  • Ninja build system (recommended, should be downloaded if not available)
  • Compiler: GCC, MSVC, or Clang

Quick Start (3 steps)

  1. Change to the HDF5 source directory: 
    cd /path/to/hdf5-2.x.y
  2. Execute a workflow preset: 
    cmake --workflow --preset ci-StdShar-GNUC --fresh       # Linux/Mac with GCC
cmake --workflow --preset ci-StdShar-MSVC --fresh       # Windows with MSVC
cmake --workflow --preset ci-StdShar-Clang --fresh      # Linux/Mac with Clang
  3. Find your build artifacts in: 
    ../build/ci-StdShar-<compiler>/

That's it! The workflow preset automatically:

  • Configures the build
  • Compiles libraries and tools
  • Runs tests
  • Creates installation packages

Available Presets

View all available presets:

cmake --list-presets

Common presets:

  • Standard Builds:
    • ci-StdShar-GNUC (Standard shared libraries - GCC)
    • ci-StdShar-MSVC (Standard shared libraries - MSVC)
    • ci-StdShar-Clang (Standard shared libraries - Clang)
    • ci-MinShar-GNUC (Minimal shared libraries - GCC)
  • Java Builds:
    • ci-StdShar-GNUC-Java-FFM (Java FFM bindings - GCC)
    • ci-StdShar-GNUC-Java-JNI (Java JNI bindings - GCC)
  • Maven Deployment (JNI default - Java 8+):
    • ci-MinShar-GNUC-Maven-Snapshot (JNI snapshots for Maven)
    • ci-MinShar-GNUC-Maven (JNI release for Maven)
  • Maven Deployment (FFM optional - Java 25+):
    • ci-MinShar-GNUC-Maven-FFM-Snapshot (FFM snapshots for Maven)
    • ci-MinShar-GNUC-Maven-FFM (FFM release for Maven)

Note: For ROS3 (S3 support), add -DHDF5_ENABLE_ROS3_VFD=ON to any preset.

See Section XI for creating custom preset configurations.

Why Use Presets?

  • ✅ Simpler - No external files to download
  • ✅ Faster - Optimized settings included
  • ✅ Consistent - Same settings across platforms
  • ✅ Modern - CMake 3.26 best practices
  • ✅ Flexible - Easy to customize via CMakeUserPresets.json

Individual Preset Commands (Advanced)

If you prefer to run preset steps individually (where <compiler-type> is GNUC, MSVC, or Clang):

cd /path/to/hdf5-source
cmake --preset ci-StdShar-<compiler-type>                 # Configure
cmake --build --preset ci-StdShar-<compiler-type>         # Build
ctest --preset ci-StdShar-<compiler-type>                 # Test
cpack --preset ci-StdShar-<compiler-type>                 # Package

The workflow preset (shown in Quick Start above) runs all these steps automatically.

Advanced Build Methods

If you cannot use presets or need more control, see:

  • Section III: Building with CMake Script Mode (requires external files, for automation/CI)
  • Section IV: Building with CMake Command Mode (manual configuration, for advanced users)

III. Advanced: Building HDF5 Libraries with CMake Script Mode

NOTE: Most users should use Section II (CMake Presets) instead. This method is provided for advanced users and automated builds.

This short set of instructions is written for users who want to quickly build the HDF5 C, C++ and Fortran shared libraries and tools from the HDF5 source code package using the CMake tools. This procedure will use the default settings in the config/cmake/cacheinit.cmake file. The HDF Group recommends using the presets process to build HDF5.

NOTE: When using the presets process, the CMakePresets.json file in the source directory will configure, build, test, and package HDF5 with the same options that are set in the cacheinit.cmake file. In addition, it will get the optional files listed below that are needed, from the appropriate repositories. See Section II: RECOMMENDED Quick Start with CMake Presets.

Individual files needed as mentioned in this document

Download from https://github.com/HDFGroup/hdf5/blob/develop/config/cmake/scripts:

  • CTestScript.cmake -- CMake build script
  • HDF5config.cmake -- CMake configuration script
  • HDF5options.cmake -- CMake configuration options script

HDF5 filter plugins:

External libraries:

Build Scripts for Windows or Linux

To build HDF5 with the SZIP and ZLIB external libraries you will need to:

  1. Change to the development directory myhdfstuff.

  2. Download/copy the individual files mentioned above to myhdfstuff. Do not uncompress the tar.gz files.

  3. Change to the source directory hdf5-2.x.y. CTestScript.cmake file should not be modified.

  4. Edit the platform configuration file, HDF5options.cmake, if you want to change the default build environment. The file is a compilation of the most used options and by commenting/uncommenting lines the options can easily be changed.

  5. From the myhdfstuff directory execute the CTest Script with the following options:

    • 32-bit Windows with Visual Studio 2022:

      ctest -S HDF5config.cmake,BUILD_GENERATOR=VS2022 -C Release -VV -O hdf5.log

    • 64-bit Windows with Visual Studio 2022:

      ctest -S HDF5config.cmake,BUILD_GENERATOR=VS202264 -C Release -VV -O hdf5.log

    • 32-bit Windows with Visual Studio 2019:

      ctest -S HDF5config.cmake,BUILD_GENERATOR=VS2019 -C Release -VV -O hdf5.log

    • 64-bit Windows with Visual Studio 2019:

      ctest -S HDF5config.cmake,BUILD_GENERATOR=VS201964 -C Release -VV -O hdf5.log

    • 32-bit Windows with Visual Studio 2017:

      ctest -S HDF5config.cmake,BUILD_GENERATOR=VS2017 -C Release -VV -O hdf5.log

    • 64-bit Windows with Visual Studio 2017:

      ctest -S HDF5config.cmake,BUILD_GENERATOR=VS201764 -C Release -VV -O hdf5.log

    • Linux and Mac:

      ctest -S HDF5config.cmake,BUILD_GENERATOR=Unix -C Release -VV -O hdf5.log

    The supplied build scripts are versions of the above.

    The command above will configure, build, test, and create an install package in the myhdfstuff folder. It will have the format: HDF5-2.X.Y-<platform>.<zip or tar.gz>.

    On Unix, <platform> will be "Linux". A similar .sh file will also be created. On Windows, <platform> will be "win64" or "win32". If you have an installer on your system, you will also see a similar file that ends in either .exe (NSIS) or .msi (WiX).

    Notes on the command line options.

    • The -S option uses the script version of ctest.

    • The value for the -C option (as shown above, -C Release) must match the setting for CTEST_CONFIGURATION_TYPE in the platform configuration file.

    • The -VV option is for most verbose; use -V for less verbose.

    • The -O hdf5.log option saves the output to a log file hdf5.log.

  6. To install, X.Y is the current release version.

    • On Windows (with WiX): Execute HDF5-2.X.Y-win32.msi or HDF5-2.X.Y-win64.msi. By default this program will install the HDF5 library into the C:\Program Files directory and will create the following directory structure:

      HDF_Group
--HDF5
----2."X"."Y"
------bin
------include
------lib
--------plugin
------cmake

    • On Linux: Change to the install destination directory (create it if doesn't exist) and execute <path-to>/myhdfstuff/HDF5-2.X.Y-Linux.sh. After accepting the license, the script will prompt:

      By default the HDF5 will be installed in:
    <current directory>/HDF5-2.X.Y-Linux
Do you want to include the subdirectory HDF5-2.X.Y-Linux?
Saying no will install in: "<current directory>" [Yn]:

      Note that the script will create the following directory structure relative to the install point:

      HDF_Group
--HDF5
----2."X"."Y"
------bin
------include
------lib
--------plugin
------share

    • On macOS: Locate HDF5-2.X.Y-Darwin.dmg file in the myhdfstuff folder. Click on the file to proceed with installation. After accepting the license, there will be a folder with the following structure:

      HDF_Group
--HDF5
----2."X"."Y"
------bin
------include
------lib
--------plugin
------share

    By default the installation will create the bin, include, lib and cmake folders in the <install destination directory>/HDF_Group/HDF5/2.X.Y. The <install destination directory> depends on the build platform:

    • Windows will set the default to C:/Program Files/HDF_Group/HDF5/2.X.Y

    • Linux will set the default to myhdfstuff/HDF_Group/HDF5/2.X.Y

    The default can be changed by adding ,INSTALLDIR=<my new dir> to the ctest -S HDF5config.cmake... command. For example on Linux: ctest -S HDF5config.cmake,INSTALLDIR=/usr/local/myhdf5,BUILD_GENERATOR=Unix -C Release -VV -O hdf5.log.

IV. Advanced: Building HDF5 Libraries with CMake Command Mode

NOTE: Most users should use Section II (CMake Presets) instead. This method is provided for advanced users who need manual control.

This short set of instructions is written for users who want to quickly build just the HDF5 C static library and tools from the HDF5 source code package using the CMake command line tools. Avoid the use of drive letters in paths on Windows.

Go through these steps:

  1. Change to the development directory myhdfstuff.

  2. Uncompress the HDF5 source file.

  3. Create a folder build in the myhdfstuff directory.

  4. Change into the build folder.

  5. Configure the C library, tools and tests with one of the following commands:

    • On Windows 32 bit 
      cmake -G "Visual Studio 16 2019" -A Win32 -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-2."X"."Y"
    • On Windows 64 bit 
      cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-2."X"."Y"
    • On Linux and Mac 
      cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ../hdf5-2."X"."Y"

    where "X"."Y" is the current release version.

  6. Build with: cmake --build . --config Release

  7. Test with: ctest . -C Release

  8. Create an install image: cpack -C Release CPackConfig.cmake

  9. To install

    • On Windows (with WiX installed), execute HDF5-2.X.Y-win32.msi or HDF5-2.X.Y-win64.msi. By default this program will install the hdf5 library into the C:\Program Files directory and will create the following directory structure:

      HDF_Group
--HDF5
----2.X.Y
------bin
------include
------lib
--------plugin
------cmake

    • On Linux, change to the install destination directory (create if doesn't exist) and execute: <path-to>/myhdfstuff/build/HDF5-2.X.Y-Linux.sh. After accepting the license, the script will prompt:

      By default the HDF5 will be installed in:
"<current directory>/HDF5-2.X.Y-Linux"
Do you want to include the subdirectory HDF5-2.X.Y-Linux?
Saying no will install in: "<current directory>" [Yn]:

      Note that the script will create the following directory structure relative to the install point:

      HDF_Group
--HDF5
----2.X.Y
------bin
------include
------lib
--------plugin
------share

    • On macOS, locate HDF5-2.X.Y-Darwin.dmg file in the build folder. Click on the file to proceed with installation. After accepting the license, there will be a folder with the following structure:

      HDF_Group
--HDF5
----2.X.Y
------bin
------include
------lib
--------plugin
------share

V. Further Considerations

  1. We suggest you obtain the latest CMake from the Kitware web site. The HDF5 2."X"."Y" product requires a minimum CMake version 3.26.

  2. If you plan to use Zlib or Szip (aka libaec):

    1. Download the binary packages and install them in a central location. For example on Windows, create a folder extlibs and install the packages there. Add the following CMake options:

      -DZLIB_LIBRARY:FILEPATH=some_location/lib/zlib.lib
-DZLIB_INCLUDE_DIR:PATH=some_location/include
-DZLIB_USE_EXTERNAL:BOOL=OFF
-DSZIP_LIBRARY:FILEPATH=some_location/lib/libszaec.lib
-DSZIP_INCLUDE_DIR:PATH=some_location/include
-Dlibaec_LIBRARY:FILEPATH=some_location/lib/libaec.lib
-Dlibaec_INCLUDE_DIR:PATH=some_location/include
-DSZIP_USE_EXTERNAL:BOOL=OFF

      where some_location is the full path to the extlibs folder. Also if the appropriate environment variable is set, the above options are not required:

      set(ENV{ZLIB_ROOT} "some_location")
set(ENV{SZIP_ROOT} "some_location")
set(ENV{libaec_ROOT} "some_location")

      Note that if there is a problem finding the libraries, try adding the CMake variable CMAKE_FIND_DEBUG_MODE:BOOL=ON to the command line.

    2. Use source packages from a GIT server by adding the following CMake options:

      HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="GIT"
      ZLIB_GIT_URL:STRING="https://some_location/zlib" or ZLIBNG_GIT_URL:STRING="https://some_location/zlibng"
      ZLIB_GIT_BRANCH="some_branch" or ZLIBNG_GIT_BRANCH="some_branch"
      SZIP_GIT_URL:STRING="https://some_location/szip"
      SZIP_GIT_BRANCH="some_branch"
      LIBAEC_GIT_URL:STRING="https://some_location/libaec"
      LIBAEC_GIT_BRANCH="some_branch"

      where some_location is the URL to the GIT repository and some_branch is a branch in the repository, usually the default. Also set CMAKE_BUILD_TYPE to the configuration type.

    3. Use source packages from a compressed file by adding the following CMake options:

      HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="TGZ"
      ZLIB_TGZ_NAME:STRING="zlib_src.ext" or ZLIBNG_TGZ_NAME:STRING="zlibng_src.ext"
      LIBAEC_TGZ_NAME:STRING="libaec_src.ext"
      TGZPATH:STRING="some_location"

      where some_location is the URL or full path to the compressed file and ext is the type of compression file. Also set CMAKE_BUILD_TYPE to the configuration type during configuration. See the settings in the config/cmake/cacheinit.cmake file used for testing.

    4. Use original source packages from a compressed file by adding the following CMake options:

      LIBAEC_TGZ_NAME:STRING="szip_src.ext"
      LIBAEC_TGZ_ORIGPATH:STRING="some_location"
      ZLIB_TGZ_NAME:STRING="zlib_src.ext" or ZLIBNG_TGZ_NAME:STRING="zlibng_src.ext"
      ZLIB_TGZ_ORIGPATH:STRING="some_location" or ZLIBNG_TGZ_ORIGPATH:STRING="some_location"
      HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="TGZ"

      where some_location is the URL and by setting

      ZLIB_USE_LOCALCONTENT:BOOL=OFF
LIBAEC_USE_LOCALCONTENT:BOOL=OFF

      or full path to the compressed file and ext is the type of compression file. Also set CMAKE_BUILD_TYPE to the configuration type during configuration. See the settings in the config/cmake/cacheinit.cmake used for testing.

      The files can also be retrieved from a local path if necessary TGZPATH:STRING="some_location" by setting

      ZLIB_USE_LOCALCONTENT:BOOL=ON
LIBAEC_USE_LOCALCONTENT:BOOL=ON

  3. If you plan to use compression plugins:

    1. Use source packages from an GIT server by adding the following CMake options:

      HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="GIT"
PLUGIN_GIT_URL:STRING="http://some_location/plugins"
PLUGIN_GIT_BRANCH="some_branch"

      where some_location is the URL to the GIT repository and some_branch is a branch in the repository, usually the default. Also set CMAKE_BUILD_TYPE to the configuration type.

    2. Use source packages from a compressed file by adding the following CMake options:

      HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="TGZ"
PLUGIN_TGZ_NAME:STRING="plugin_src.ext"
TGZPATH:STRING="some_location"

      where some_location is the URL or full path to the compressed file and ext is the type of compression file. Also set CMAKE_BUILD_TYPE to the configuration type during configuration. See the settings in the config/cmake/cacheinit.cmake file used for testing.

  4. If you are building on Apple Darwin platforms, you should add the following options:

    • Compiler choice - use Xcode by setting the CC and CXX environment variables.

    • Shared Fortran is not supported, build static with BUILD_SHARED_LIBS:BOOL=OFF.

    • Additional options:

        CMAKE_ANSI_CFLAGS:STRING=-fPIC
  CTEST_USE_LAUNCHERS:BOOL=ON

  5. Windows developers should install NSIS or WiX to create an install image with CPack. Visual Studio Express users will not be able to package HDF5 into an install image executable.

  6. Developers can copy the config/cmake/cacheinit.cmake file and alter the settings for the developers' environment. Then the only options needed on the command line are those options that are different. Example using the default cache file:

    cmake -C ../config/cmake/cacheinit.cmake ^
        -G "Visual Studio 16 2019" ^
        -DHDF5_ENABLE_SZIP_SUPPORT:BOOL=OFF ^
        -DHDF5_ENABLE_ZLIB_SUPPORT:BOOL=OFF ^
        -DCMAKE_BUILD_TYPE:STRING=Release ^
        ..

  7. CMake uses a toolchain of utilities to compile, link libraries, create archives, and other tasks to drive the build. The toolchain utilities available are determined by the languages enabled. In normal builds, CMake automatically determines the toolchain for host builds based on system introspection and defaults. In cross-compiling scenarios, a toolchain file may be specified with information about compiler and utility paths.

Variables and Properties

Several variables relate to the language components of a toolchain which are enabled. CMAKE_<LANG>_COMPILER is the full path to the compiler used for <LANG>. CMAKE_<LANG>_COMPILER_ID is the identifier used by CMake for the compiler and CMAKE_<LANG>_COMPILER_VERSION is the version of the compiler.

The CMAKE_<LANG>_FLAGS variables and the configuration-specific equivalents contain flags that will be added to the compile command when compiling a file of a particular language.

As the linker is invoked by the compiler driver, CMake needs a way to determine which compiler to use to invoke the linker. This is calculated by the LANGUAGE of source files in the target, and, in the case of static libraries, the language of the dependent libraries. The choice CMake makes may be overridden with the LINKER_LANGUAGE target property.

See the CMake help for more information on using toolchain files.

To use a toolchain file with the supplied cmake scripts, see the HDF5options.cmake file under the toolchain section.

Notes: CMake and HDF5

  • CMake support for HDF5 development should be usable on any system where CMake is supported. Please send us any comments on how CMake support can be improved on any system. Visit the Kitware site for more information about CMake.

  • Build and test results can be submitted to our HDF5 CDash server. The CDash server for community submissions of HDF5 is at https://my.cdash.org.

    We ask that all submissions include the configuration information and contact information in the CTest Notes Files upload step. See the current reports on CDash for examples.

    Please follow the convention that "NIGHTLY" submissions maintain the same configuration every time. "EXPERIMENTAL" submissions can be expected to be different for each submission.

  • See the appendix at the bottom of this file for examples of using a ctest script for building and testing. Using a

  • ctest script is preferred because of its flexibility.

Notes: CMake in General

  1. More information about using CMake can be found at the Kitware site at www.cmake.org.

  2. CMake uses the command line; however, the visual CMake tool is available for the configuration step. The steps are similar for all the operating systems supported by CMake.

  3. Setting the installation location from the command line at configure time a. Using the --install-prefix command line option, which is available since CMake version 3.21: cmake --install-prefix /my/folder/to/install/to .. b. Using -DCMAKE_INSTALL_PREFIX : cmake -DCMAKE_INSTALL_PREFIX=/my/folder/to/install/to .. c. Using the CMAKE_INSTALL_PREFIX environment variable, which is available since CMake version 3.29: CMAKE_INSTALL_PREFIX=/my/folder/to/install/to cmake ..

VI. Options for building HDF5 Libraries with CMake Command Line

To build the HDF5 Libraries with CMake, go through the five steps below:

Step 1: Run CMake

The visual CMake executable is named "cmake-gui.exe" on Windows and should be available in your Start menu. For Linux, UNIX, and macOS users the executable is named cmake-gui and can be found where CMake was installed.

Another option is to use the presets file, CMakePresets.json, to configure, build, test, and package HDF5, see Section XI for use of that file. You can create a CMakeUserPresets.json file to create a specific configuration for your environment. Note that Visual Studio and XCode can use the presets files.

Specify the source and build directories

Note: Make the build and source directories different.

For example, on Windows, if the source is at c:\MyHDFstuff\hdf5, then use c:\MyHDFstuff\hdf5\build or c:\MyHDFstuff\build\hdf5 as the build directory.

RECOMMENDED: Users can perform the configuration step without using the visual cmake-gui program. We use the file cacheinit.cmake in the config/cmake source folder for our testing. This file enables all of the basic options and we turn specific options on or off for testing using the following command line within the build directory:

cmake -C <sourcepath>/config/cmake/cacheinit.cmake -G "<generator>"  [-D<options>]  <sourcepath>

Where <generator> is (examples):

  • MinGW Makefiles
  • NMake Makefiles
  • Unix Makefiles
  • Ninja
  • Visual Studio 15 2017
  • Visual Studio 15 2017 Win64
  • Visual Studio 16 2019
  • Visual Studio 17 2022

<options> is:

  • For installed SZIP/libaec:

      SZIP_INCLUDE_DIR:PATH=<path to szip includes directory>
  SZIP_LIBRARY:FILEPATH=<path to szip/library file>
  libaec_INCLUDE_DIR:PATH=<path to libaec includes directory>
  libaec_LIBRARY:FILEPATH=<path to libaec/library file>

    or

      SZIP_ROOT:PATH=<path to szip root directory>
  libaec_ROOT:PATH=<path to libaec root directory>

  • For installed ZLIB/ZLIBNG:

      ZLIB_INCLUDE_DIR:PATH=<path to zlib includes directory>
  ZLIB_LIBRARY:FILEPATH=<path to zlib/library file>

    or

      ZLIB_ROOT:PATH=<path to zlib root directory>

  • <HDF5OPTION>:BOOL=[ON | OFF]

cacheinit.cmake highlights are:

# This is the CMakeCache file used by HDF Group for daily tests.
set (CMAKE_INSTALL_FRAMEWORK_PREFIX "Library/Frameworks" CACHE STRING "Frameworks installation directory" FORCE)
set (HDF_PACKAGE_NAMESPACE "hdf5::" CACHE STRING "Name for HDF package namespace (can be empty)" FORCE)
set (HDF5_BUILD_CPP_LIB ON CACHE BOOL "Build C++ support" FORCE)
set (HDF5_BUILD_FORTRAN ON CACHE BOOL "Build FORTRAN support" FORCE)
set (HDF5_BUILD_JAVA ON CACHE BOOL "Build JAVA support" FORCE)
set (HDF5_ENABLE_ALL_WARNINGS ON CACHE BOOL "Enable all warnings" FORCE)
set (HDF5_ALLOW_EXTERNAL_SUPPORT "TGZ" CACHE STRING "Allow External Library Building (NO GIT TGZ)" FORCE)
########################
# compression options
########################
set (ZLIB_PACKAGE_NAME "zlib" CACHE STRING "Name of ZLIB package" FORCE)
set (ZLIB_TGZ_NAME "zlib-1.3.1.tar.gz" CACHE STRING "Use HDF5_ZLib from compressed file" FORCE)
set (ZLIB_TGZ_ORIGPATH "https://github.com/madler/zlib/releases/download/v1.3.1" CACHE STRING "Use ZLIB from original location" FORCE)
set (ZLIB_USE_LOCALCONTENT ON CACHE BOOL "Use local file for ZLIB FetchContent" FORCE)
set (ZLIB_GIT_URL "https://github.com/madler/zlib.git" CACHE STRING "Use ZLIB from  GitHub repository" FORCE)
set (ZLIB_GIT_BRANCH "develop" CACHE STRING "" FORCE)
set (HDF5_USE_ZLIB_NG OFF CACHE BOOL "Use zlib-ng library as zlib library" FORCE)
set (ZLIBNG_PACKAGE_NAME "zlib-ng" CACHE STRING "Name of ZLIBNG package" FORCE)
set (ZLIBNG_TGZ_NAME "2.2.4.tar.gz" CACHE STRING "Use HDF5_ZLib from compressed file" FORCE)
set (ZLIBNG_TGZ_ORIGPATH "https://github.com/zlib-ng/zlib-ng/archive/refs/tags" CACHE STRING "Use ZLIBNG from original location" FORCE)
set (ZLIBNG_GIT_URL "https://github.com/zlib-ng/zlib-ng.git" CACHE STRING "Use ZLIBNG from  GitHub repository" FORCE)
set (ZLIBNG_GIT_BRANCH "develop" CACHE STRING "" FORCE)
set (LIBAEC_PACKAGE_NAME "libaec" CACHE STRING "Name of AEC SZIP package" FORCE)
set (LIBAEC_TGZ_NAME "libaec-1.1.3.tar.gz" CACHE STRING "Use SZip AEC from compressed file" FORCE)
set (LIBAEC_TGZ_ORIGPATH "https://github.com/MathisRosenhauer/libaec/releases/download/v1.1.3" CACHE STRING "Use LIBAEC from original location" FORCE)
set (LIBAEC_USE_LOCALCONTENT ON CACHE BOOL "Use local file for LIBAEC FetchContent" FORCE)
set (LIBAEC_GIT_URL "https://github.com/MathisRosenhauer/libaec.git" CACHE STRING "Use LIBAEC from  GitHub repository" FORCE)
set (LIBAEC_GIT_BRANCH "v1.1.3" CACHE STRING "" FORCE)
########################
# filter plugin options
########################
set (PLUGIN_TGZ_ORIGPATH "https://github.com/HDFGroup/hdf5_plugins/releases/download/snapshot" CACHE STRING "Use PLUGINS from original location" FORCE)
set (PLUGIN_TGZ_NAME "hdf5_plugins-master.tar.gz" CACHE STRING "Use PLUGINS from compressed file" FORCE)
set (PLUGIN_USE_LOCALCONTENT ON CACHE BOOL "Use local file for PLUGIN FetchContent" FORCE)
set (PLUGIN_PACKAGE_NAME "pl" CACHE STRING "Name of PLUGIN package" FORCE)
set (PLUGIN_GIT_URL "https://github.com/HDFGroup/hdf5_plugins.git" CACHE STRING "Use plugins from HDF Group repository" FORCE)
set (PLUGIN_GIT_BRANCH "master" CACHE STRING "" FORCE)

Step 2: Configure the Cache Settings

Visual CMake users, click the Configure button. If this is the first time you are running cmake-gui in this directory, you will be prompted for the generator you wish to use (for example on Windows, Visual Studio 14). CMake will read in the CMakeLists.txt files from the source directory and display options for the HDF5 project. After the first configure you can adjust the cache settings and/or specify the locations of other programs.

Any conflicts or new values will be highlighted by the configure process in red. Once you are happy with all the settings and there are no more values in red, click the Generate button to produce the appropriate build files.

On Windows, if you are using a Visual Studio generator, the solution and project files will be created in the build folder.

On Linux, if you are using the Unix Makefiles generator, the Makefiles will be created in the build folder.

Preferred command line example on Windows in c:\MyHDFstuff\hdf5\build directory:

cmake -C ../config/cmake/cacheinit.cmake -G "Visual Studio 16 2019" "-Ax64" \
      -DHDF5_ENABLE_SZIP_SUPPORT:BOOL=OFF -DHDF5_ENABLE_ZLIB_SUPPORT:BOOL=OFF \
      -DCMAKE_BUILD_TYPE:STRING=Release ..

On Windows, if you are using a Visual Studio Express version you must be sure that the following two options are correctly set/unset:

HDF5_NO_PACKAGES:BOOL=ON
HDF5_USE_FOLDERS:BOOL=OFF

Step 3: Build HDF5

On Windows, you can build HDF5 using either the Visual Studio Environment or the command line. The command line can be used on all platforms; Windows, Linux, Unix, and macOS.

To build from the command line, navigate to your build directory and execute the following:

cmake --build . --config {Debug | Release}

NOTE: --config {Debug | Release} may be optional on your platform. We recommend choosing either Debug or Release on Windows.

If you wish to use the Visual Studio environment, open the solution file in your build directory. Be sure to select either Debug or Release and build the solution.

The external libraries (zlib, szip and plugins) can be configured to allow building the libraries by downloading from a GIT repository. The option is HDF5_ALLOW_EXTERNAL_SUPPORT; by adding the following configuration option: -DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING="GIT".

The options to control the GIT parameters (config/cmake/cacheinit.cmake file) are:

ZLIB_GIT_URL:STRING="https://${git_url}/zlib"
ZLIB_GIT_BRANCH="${git_branch}"
SZIP_GIT_URL:STRING="https://${git_url}/szip"
SZIP_GIT_BRANCH="${git_branch}"
LIBAEC_GIT_URL:STRING="https://${git_url}/libaec"
LIBAEC_GIT_BRANCH="${git_branch}"
PLUGIN_GIT_URL:STRING="https://${git_url}/plugin"
PLUGIN_GIT_BRANCH="${git_branch}"

${git_url} should be changed to your location and ${git_branch} is your branch in the repository. Also define CMAKE_BUILD_TYPE to be the configuration type.

Alternatively, the external libraries (zlib, szip and plugins) can be configured to allow building the libraries by using a compressed file. The option is HDF5_ALLOW_EXTERNAL_SUPPORT and is enabled by adding the following configuration option: -DHDF5_ALLOW_EXTERNAL_SUPPORT:STRING="TGZ".

The options to control the TGZ URL (config/cmake/cacheinit.cmake file) are:

ZLIB_TGZ_NAME:STRING="zlib_src.ext"
LIBAEC_TGZ_NAME:STRING="libaec_src.ext"
PLUGIN_TGZ_NAME:STRING="plugin_src.ext"
TGZPATH:STRING="some_location"

where some_location/xxxx_src.ext is the URL or full path to the compressed file and where ext is the type of the compression file such as .bz2, .tar, .tar.gz, .tgz, or .zip. Also define CMAKE_BUILD_TYPE to be the configuration type.

NOTE: The file named by LIBAEC_TGZ_NAME is used to build SZIP.

Step 4: Test HDF5

To test the build, navigate to your build directory and execute:

ctest . -C {Debug | Release}

NOTE: -C {Debug | Release} may be optional on your platform. We recommend choosing either Debug or Release to match the build step on Windows.

Step 5: Packaging HDF5 (Create an Install Image)

To package the build into a simple installer using WiX toolset or the NullSoft installer NSIS on Windows, or into compressed files (.tar.gz, .sh, .zip), use the CPack tool.

To package the build, navigate to your build directory and execute:

cpack -C {Debug | Release} CPackConfig.cmake

NOTE: See the sections below with NSIS and WiX information below. Also, if you are using a Visual Studio Express version or want to disable the packaging components, set HDF5_NO_PACKAGES to ON (on the command line add -DHDF5_NO_PACKAGES:BOOL=ON).

Additional Information

CMake Files for Building and Testing HDF5

The files that support building HDF5 with CMake are all the files in the config/cmake folder, the CMakeLists.txt files in each source folder, and CTestConfig.cmake. CTestConfig.cmake is specific to the internal testing performed by The HDF Group. It should be altered for the user's installation and needs. The cacheinit.cmake file settings are used by The HDF Group for daily testing. It should be altered/ignored for the user's installation and needs. More information about using CMake can be found at the Kitware site, www.cmake.org.

Nullsoft Scriptable Install System

The Nullsoft Scriptable Install System (NSIS) is an open source installation system. It was created by the WinAmp authors to distribute that application, but it is now a general-purpose system which anyone might use. NSIS installers recognize /S for silent installation and /D=dir to specify the output directory, which is where the program will be installed. These options are case-sensitive, so be sure to type them in upper case.

WiX Toolset

WiX--the Windows Installer XML toolset--lets developers create installers for Windows Installer, the Windows installation engine. See http://wixtoolset.org.

Backward Compatibility

The 2.0.0 version of the HDF5 library can be configured to set all versioned functions to the version that was available in one of these HDF5_DEFAULT_API_VERSIONs

HDF5_DEFAULT_API_VERSION:STRING=v114
HDF5_DEFAULT_API_VERSION:STRING=v112
HDF5_DEFAULT_API_VERSION:STRING=v110
HDF5_DEFAULT_API_VERSION:STRING=v18
HDF5_DEFAULT_API_VERSION:STRING=v16

This allows existing code to be compiled with the v2.0 library without requiring immediate changes to the application source code. Note that because 2.0.0 is a major release, as long as the existing application code doesn't use symbols removed in 2.0.0, the code can be compiled and run with the new library.

For additional configuration options and other details, see "API Compatibility Macros": https://support.hdfgroup.org/documentation/hdf5/latest/api-compat-macros.html.

Generating Documentation with Doxygen

One can optionally build the documentation files for the HDF5 C library with Doxygen. By default, this option is disabled. To build the HTML files, set the HDF5_BUILD_DOC option.

cmake -G "<generator>" -DHDF5_BUILD_DOC:BOOL=ON  <sourcepath>

Configuration will halt if the required applications are not available. To build:

cmake --build . --config {Debug | Release}

or

make doxygen

Parallel vs Serial Library

The HDF5 library can be configured to use MPI and MPI-IO for parallelism on a distributed multi-processor system:

HDF5_ENABLE_PARALLEL:BOOL=ON

Read README_HPC.md for detailed information.

The threadsafe, C++ ,and Java interfaces are not compatible with the parallel option. Unless HDF5_ALLOW_UNSUPPORTED has been set on the configure line, the following options must be disabled: HDF5_ENABLE_THREADSAFE, HDF5_BUILD_CPP_LIB, HDF5_BUILD_JAVA.

Threadsafe Capability

The HDF5 library can be configured to be thread-safe (on a very large scale) with the HDF5_ENABLE_THREADSAFE flag to the configure script. For further information, see the "Technical Notes" category in the HDF5 library documentation: https://support.hdfgroup.org/documentation/hdf5/latest/.

The high-level, C++, Fortran and Java interfaces are not compatible with the thread-safety option because the lock is not hoisted into the higher-level API calls. Unless HDF5_ALLOW_UNSUPPORTED has been set on the configure line, the following options must be disabled: HDF5_BUILD_HL_LIB, HDF5_BUILD_FORTRAN, HDF5_BUILD_CPP_LIB, HDF5_BUILD_JAVA.

VII. CMake Option Defaults for HDF5

The config/cmake/cacheinit.cmake or CMakePresets.json file can override the following values.

General Build Options

Option Name Description Default Value
BUILD_SHARED_LIBS Build Shared Libraries ON
BUILD_STATIC_LIBS Build Static Libraries ON
BUILD_STATIC_EXECS Build Static Executables OFF
BUILD_TESTING Build HDF5 Unit Testing ON
HDF5_DISABLE_PDB_FILES Do not install PDB files (Windows only) OFF

HDF5 Build Options

Option Name Description Default Value
HDF5_BUILD_CPP_LIB Build HDF5 C++ Library OFF
HDF5_BUILD_EXAMPLES Build HDF5 Library Examples ON
HDF5_BUILD_FORTRAN Build FORTRAN support OFF
HDF5_BUILD_JAVA Build JAVA support OFF
HDF5_BUILD_HL_LIB Build HIGH Level HDF5 Library ON
HDF5_BUILD_TOOLS Build HDF5 Tools ON
HDF5_BUILD_PARALLEL_TOOLS Build Parallel HDF5 Tools OFF
HDF5_BUILD_STATIC_TOOLS Build Static Tools Not Shared Tools OFF

HDF5 Maven Integration Options

Option Name Description Default Value
HD5_ENABLE_MAVEN_DEPLOY Enable Maven repository deployment OFF
HDF5_MAVEN_SNAPSHOT Build Maven snapshot versions OFF
HDF5_ENABLE_JNI Force JNI implementation (default: auto-detect) ON

Java Implementation Selection (as of HDF5 2.0)

HDF5 Java bindings support two native interface implementations:

  • JNI (Java Native Interface). Default, works with Java 8+, production-stable.
  • FFM (Foreign Function & Memory). Optional, requires Java 25+, modern native access.

Maven Artifacts:

  • org.hdfgroup:hdf5-java-ffm is FFM implementation
  • org.hdfgroup:hdf5-java-jni is JNI implementation

Both implementations use the same hdf.hdf5lib.* package structure for seamless migration.

To build HDF5 with Maven deployment support:

cmake -DHDF5_BUILD_JAVA:BOOL=ON -DHDF5_ENABLE_MAVEN_DEPLOY:BOOL=ON ../hdf5

To build Maven snapshot versions for development:

cmake -DHDF5_BUILD_JAVA:BOOL=ON -DHDF5_ENABLE_MAVEN_DEPLOY:BOOL=ON -DHDF5_MAVEN_SNAPSHOT:BOOL=ON ../hdf5

Note: FFM is selected for Java 25+ if HDF5_ENABLE_JNI is OFF. To force JNI even with Java 25+:

cmake -DHDF5_BUILD_JAVA:BOOL=ON -DHDF5_ENABLE_MAVEN_DEPLOY:BOOL=ON -DHDF5_ENABLE_JNI:BOOL=ON ../hdf5

Or use the Maven-enabled CMake presets (recommended):

# Minimal build for Java artifacts only (recommended for Maven deployment)
# Linux (GCC) - JNI (default, Java 8+):
cmake --workflow --preset ci-MinShar-GNUC-Maven --fresh          # JNI Release
cmake --workflow --preset ci-MinShar-GNUC-Maven-Snapshot --fresh # JNI Snapshot

# Linux (GCC) - FFM (optional, Java 25+):
cmake --workflow --preset ci-MinShar-GNUC-Maven-FFM --fresh          # FFM Release
cmake --workflow --preset ci-MinShar-GNUC-Maven-FFM-Snapshot --fresh # FFM Snapshot

# Windows (MSVC) - JNI (default):
cmake --workflow --preset ci-MinShar-MSVC-Maven --fresh          # JNI Release
cmake --workflow --preset ci-MinShar-MSVC-Maven-Snapshot --fresh # JNI Snapshot

# Windows (MSVC) - FFM (optional):
cmake --workflow --preset ci-MinShar-MSVC-Maven-FFM --fresh          # FFM Release
cmake --workflow --preset ci-MinShar-MSVC-Maven-FFM-Snapshot --fresh # FFM Snapshot

# macOS (Clang) - JNI (default):
cmake --workflow --preset ci-MinShar-Clang-Maven --fresh          # JNI Release
cmake --workflow --preset ci-MinShar-Clang-Maven-Snapshot --fresh # JNI Snapshot

# macOS (Clang) - FFM (optional):
cmake --workflow --preset ci-MinShar-Clang-Maven-FFM --fresh         # FFM Release
cmake --workflow --preset ci-MinShar-Clang-Maven-FFM-Snapshot --fresh # FFM Snapshot

# ROS3 VFD (S3 cloud storage) - Add to any preset above:
cmake --workflow --preset ci-MinShar-GNUC-Maven --fresh -DHDF5_ENABLE_ROS3_VFD=ON

Note: Presets are platform-specific. Use cmake --list-presets to see available presets for your current platform. Minimal Maven presets skip examples, testing, tools, C++, and Fortran builds to optimize for Java artifact generation only.

Java Examples Maven Integration

The HDF5 Java examples are available as a separate Maven artifact: org.hdfgroup:hdf5-java-examples. It contains platform-specific dependencies to ensure compatibility with the HDF5 Java library, and complete examples with documentation for all HDF5 Java functionality. See HDF5Examples/JAVA/README-MAVEN.md for usage instructions.

Testing Java Examples with Maven Artifacts

  • Maven staging workflow validates examples against artifacts.
  • Cross-platform testing ensures compatibility on all supported platforms.
  • Native library error handling validates JAR structure in Maven-only environments.
  • Fork-based testing allows validation on repository forks before canonical deployment.
  • Dynamic repository workflows adapt to any GitHub repository automatically.

HDF5 Folder Build Options

Defaults relative to $<INSTALL_PREFIX>.

Option Name Default Value
HDF5_INSTALL_BIN_DIR bin
HDF5_INSTALL_LIB_DIR lib
HDF5_INSTALL_INCLUDE_DIR include
HDF5_INSTALL_MODULE_DIR mod
HDF5_INSTALL_CMAKE_DIR cmake
HDF5_INSTALL_DATA_DIR . when MSVC is true,
share otherwise
HDF5_INSTALL_DOC_DIR HDF5_INSTALL_DATA_DIR

HDF5_USE_GNU_DIRS=ON means use of the GNU Coding Standard install directory variables, and HDF5_USE_GNU_DIRS=OFF will use historical settings. The default value is OFF.

Defaults defined by the 'GNU Coding Standards'.

Option Name Default Value
HDF5_INSTALL_BIN_DIR bin
HDF5_INSTALL_LIB_DIR lib
HDF5_INSTALL_INCLUDE_DIR include
HDF5_INSTALL_MODULE_DIR HDF5_INSTALL_INCLUDE_DIR/mod
HDF5_INSTALL_CMAKE_DIR HDF5_INSTALL_LIB_DIR/cmake
HDF5_INSTALL_DATA_DIR share
HDF5_INSTALL_DOC_DIR HDF5_INSTALL_DATA_DIR/doc/hdf5

HDF5 Advanced Options

Option Name Description Default Value
HDF5_ONLY_SHARED_LIBS Only Build Shared Libraries OFF
HDF5_ALLOW_UNSUPPORTED Allow unsupported combinations of configure options OFF
HDF5_ENABLE_PARALLEL Enable parallel build (requires MPI) OFF
HDF5_ENABLE_THREADSAFE Enable Threadsafety OFF
HDF5_ENABLE_CONCURRENCY Enable multi-threaded concurrency OFF
HDF5_DIMENSION_SCALES_NEW_REF Use new-style references with dimension scale APIs OFF
HDF5_EXTERNAL_LIB_PREFIX Use prefix for custom library naming ""
HDF5_EXTERNAL_LIB_SUFFIX Use suffix for custom library naming ""
HDF5_DISABLE_COMPILER_WARNINGS Disable compiler warnings OFF
HDF5_ENABLE_ALL_WARNINGS Enable all warnings OFF
HDF5_SHOW_ALL_WARNINGS Show all warnings (i.e. not suppress "noisy" ones internally) OFF
HDF5_ENABLE_COVERAGE Enable code coverage for Libraries and Programs OFF
HDF5_ENABLE_DEBUG_APIS Turn on extra debug output in all packages OFF
HDF5_ENABLE_DEPRECATED_SYMBOLS Enable deprecated public API symbols ON
HDF5_ENABLE_EMBEDDED_LIBINFO embed library info into executables ON
HDF5_ENABLE_PREADWRITE Use pread/pwrite in sec2/log/core VFDs in place of read/write (when available) ON
HDF5_ENABLE_TRACE Enable API tracing capability OFF
HDF5_ENABLE_USING_MEMCHECKER Indicate that a memory checker is used OFF
HDF5_ENABLE_MAP_API Build the map API OFF
HDF5_GENERATE_HEADERS Rebuild Generated Files OFF
HDF5_JAVA_PACK_JRE Package a JRE installer directory OFF
HDF5_NO_PACKAGES Do not include CPack Packaging OFF
HDF5_PACK_EXAMPLES Package the HDF5 Library Examples Compressed File OFF
HDF5_PACK_MACOSX_FRAMEWORK Package the HDF5 Library in a Frameworks OFF
HDF5_BUILD_FRAMEWORKS TRUE to build as frameworks libraries, FALSE to build according to BUILD_SHARED_LIBS FALSE
HDF5_PACKAGE_EXTLIBS CPACK - include external libraries OFF
HDF5_STRICT_FORMAT_CHECKS Whether to perform strict file format checks OFF
HDF5_WANT_DATA_ACCURACY IF data accuracy is guaranteed during data conversions ON
HDF5_WANT_DCONV_EXCEPTION exception handling functions is checked during data conversions ON
HDF5_DEFAULT_API_VERSION Enable default API (v16, v18, v110, v112, v114, v200) "v200"
HDF5_USE_FOLDERS Enable folder grouping of projects in IDEs ON
HDF5_MSVC_NAMING_CONVENTION Use MSVC Naming conventions for Shared Libraries OFF
HDF5_MINGW_STATIC_GCC_LIBS Statically link libgcc/libstdc++ OFF
HDF5_BUILD_WITH_INSTALL_NAME Build with library install_name set to the installation path (if APPLE true) OFF
HDF5_ENABLE_INSTRUMENT Instrument the library (if CMAKE_BUILD_TYPE MATCHES Debug) OFF
HDF5_ENABLE_ANALYZER_TOOLS enable the use of Clang tools OFF
HDF5_ENABLE_SANITIZERS execute the Clang sanitizer OFF
HDF5_ENABLE_FORMATTERS format source files OFF
HDF5_BUILD_DOC Build documentation OFF
HDF5_ENABLE_DOXY_WARNINGS Enable fail if doxygen parsing has warnings OFF
HDF5_H5CC_C_COMPILER C compiler to use in h5cc ${CMAKE_C_COMPILER}
HDF5_H5CC_CXX_COMPILER C++ compiler to use in h5cc ${CMAKE_CXX_COMPILER}
HDF5_H5CC_Fortran_COMPILER Fortran compiler to use in h5cc ${CMAKE_Fortran_COMPILER} 
if (HDF5_BUILD_FORTRAN)
    HDF5_INSTALL_MOD_FORTRAN "Copy FORTRAN mod files to include directory (NO SHARED STATIC)"    SHARED
    if (BUILD_SHARED_LIBS AND BUILD_STATIC_LIBS)          default HDF5_INSTALL_MOD_FORTRAN is    SHARED
    if (BUILD_SHARED_LIBS AND NOT BUILD_STATIC_LIBS)      default HDF5_INSTALL_MOD_FORTRAN is    SHARED
    if (NOT BUILD_SHARED_LIBS AND BUILD_STATIC_LIBS)      default HDF5_INSTALL_MOD_FORTRAN is    STATIC
    if (NOT BUILD_SHARED_LIBS AND NOT BUILD_STATIC_LIBS)  default HDF5_INSTALL_MOD_FORTRAN is    SHARED

HDF5 VFD Options

Option Name Description Default Value
HDF5_ENABLE_DIRECT_VFD Build the Direct I/O Virtual File Driver OFF
HDF5_ENABLE_MIRROR_VFD Build the Mirror Virtual File Driver OFF
HDF5_ENABLE_ROS3_VFD Build the ROS3 Virtual File Driver OFF
HDF5_ENABLE_HDFS Enable HDFS OFF
HDF5_ENABLE_SUBFILING_VFD Build Parallel HDF5 Subfiling VFD OFF

HDF5 Advanced Test Options

If BUILD_TESTING is true:

Option Name Description Default Value
HDF5_TEST_SERIAL Execute non-parallel tests ON
HDF5_TEST_TOOLS Execute tools tests ON
HDF5_TEST_EXAMPLES Execute tests on examples ON
HDF5_TEST_SWMR Execute SWMR tests ON
HDF5_TEST_PARALLEL Execute parallel tests ON
HDF5_TEST_FORTRAN Execute fortran tests ON
HDF5_TEST_CPP Execute cpp tests ON
HDF5_TEST_JAVA Execute java tests ON
HDF_TEST_EXPRESS Control testing framework (0-3) "3"
HDF5_TEST_PASSTHROUGH_VOL Execute tests with different passthrough VOL connectors OFF
HDF5_TEST_FHEAP_PASSTHROUGH_VOL Execute fheap test with different passthrough VOL connectors ON
HDF5_TEST_VFD Execute tests with different VFDs OFF
HDF5_TEST_FHEAP_VFD Execute fheap test with different VFDs ON
HDF5_TEST_SHELL_SCRIPTS Enable shell script tests ON
HDF5_DISABLE_TESTS_REGEX Regex pattern to set execution of specific tests to DISABLED ""
HDF5_USING_ANALYSIS_TOOL Indicate that an analysis checker is used ON

External Library Options

Option Name Description Default Value
HDF5_ALLOW_EXTERNAL_SUPPORT Allow External Library Building (NO GIT TGZ) "NO"
HDF5_ENABLE_PLUGIN_SUPPORT Enable PLUGIN Filters OFF
HDF5_ENABLE_SZIP_SUPPORT Use SZip Filter OFF
HDF5_MODULE_MODE_ZLIB Prefer module mode to find ZLIB ON
HDF5_ENABLE_ZLIB_SUPPORT Enable Zlib Filters OFF
ZLIB_USE_LOCALCONTENT Use local file for ZLIB FetchContent OFF
HDF5_USE_ZLIB_STATIC Find static zlib library OFF
ZLIB_USE_EXTERNAL Use External Library Building for ZLIB OFF
ZLIB_TGZ_ORIGPATH Use ZLIB from original location "https://github.com/madler/zlib/releases/download/v1.3.1"
ZLIB_TGZ_NAME Use ZLIB from original compressed file "zlib-1.3.1.tar.gz"
HDF5_USE_ZLIB_NG Use zlib-ng library as zlib library OFF
ZLIBNG_USE_EXTERNAL Use External Library Building for ZLIBNG OFF
ZLIBNG_TGZ_ORIGPATH Use ZLIBNG from original location "https://github.com/zlib-ng/zlib-ng/releases/tag/2.2.4"
ZLIBNG_TGZ_NAME Use ZLIBNG from original compressed file "2.2.4.tar.gz"
SZIP_USE_EXTERNAL Use External Library Building for SZIP else search OFF
HDF5_ENABLE_SZIP_ENCODING Use SZip Encoding (if HDF5_ENABLE_SZIP_SUPPORT set) ON
LIBAEC_TGZ_ORIGPATH Use LIBAEC from original location "https://github.com/MathisRosenhauer/libaec/releases/download/v1.1.3"
LIBAEC_TGZ_NAME Use LIBAEC from original compressed file "libaec-1.1.3.tar.gz"
LIBAEC_USE_LOCALCONTENT Use local file for LIBAEC FetchContent OFF
HDF5_USE_LIBAEC_STATIC Find static AEC library OFF
PLUGIN_USE_EXTERNAL Use External Library Building for PLUGINS else search OFF
PLUGIN_TGZ_ORIGPATH Use PLUGIN from original location "https://github.com/HDFGroup/hdf5_plugins/releases/download/snapshot"
PLUGIN_TGZ_NAME Use PLUGIN from original compressed file "hdf5_plugins-master.tar.gz"
PLUGIN_USE_LOCALCONTENT Use local file for PLUGIN FetchContent OFF
H5_DEFAULT_PLUGINDIR Default library search folder for filter plugins "%ALLUSERSPROFILE%/hdf5/lib/plugin" (Windows)
"/usr/local/hdf5/lib/plugin"

NOTE: The BUILD_STATIC_EXECS ("Build Static Executables") option is only valid on some UNIX operating systems. It adds the -static flag to cflags. This flag is not available on Windows and some modern Linux systems will ignore the flag.

NOTE: The HDF5_USE_GNU_DIRS option is usually recommended for Linux platforms, but may be useful on other platforms. See the CMake documentation for more details.

Unsupported Library Options

The threadsafe, C++ and Java interfaces are not compatible with the HDF5_ENABLE_PARALLEL option. Unless HDF5_ALLOW_UNSUPPORTED has been specified, the following options must be disabled: HDF5_ENABLE_THREADSAFE, HDF5_BUILD_CPP_LIB, HDF5_BUILD_JAVA.

The high-level, C++, Fortran and Java interfaces are not compatible with the HDF5_ENABLE_THREADSAFE option because the lock is not hoisted into the higher-level API calls. Unless HDF5_ALLOW_UNSUPPORTED has been specified, the following options must be disabled: HDF5_BUILD_HL_LIB, HDF5_BUILD_CPP_LIB, HDF5_BUILD_FORTRAN, HDF5_BUILD_JAVA.

The multi-threaded concurrency and threadsafe options are mutually exclusive, only one or the other may be enabled.

The multi-threaded concurrency, C++, and Java interfaces are not compatible with the HDF5_ENABLE_PARALLEL option. Unless HDF5_ALLOW_UNSUPPORTED has been specified, the following options must be disabled: HDF5_ENABLE_CONCURRENCY, HDF5_BUILD_CPP_LIB, HDF5_BUILD_JAVA.

The high-level, C++, Fortran, and Java interfaces are not compatible with the HDF5_ENABLE_CONCURRENCY option because the lock is not hoisted into the higher-level API calls. Unless HDF5_ALLOW_UNSUPPORTED has been specified, the following options must be disabled: HDF5_BUILD_HL_LIB, HDF5_BUILD_CPP_LIB, HDF5_BUILD_FORTRAN, HDF5_BUILD_JAVA.

VIII. User Defined Options for HDF5 Libraries with CMake

Support for User Defined macros and options has been added. The file UserMacros.cmake has an example of the technique. Replace the template code with your macro in the UserMacros.cmake file. Then enable the option to the CMake configuration, build and test process.

IX. User Defined Compile Flags for HDF5 Libraries with CMake

Custom compiler flags can be added by defining the CMAKE_C_FLAGS and CMAKE_CXX_FLAGS variables.

Using a cmake script:

set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O2")

Defined on the configure line:

cmake -G "Visual Studio 17 2019" -DCMAKE_C_FLAGS:STRING=-O2 ..

Debug symbols are enabled with configuration selections Debug or RelWithDebInfo. The difference between Debug and RelWithDebInfo configurations is that RelWithDebInfo optimizes the code similar to Release. It produces fully optimized code, but also creates the symbol table and the debug metadata to give the debugger input to map the execution back to the original code. RelwithDebInfo configuration should not affect the performance when the code is run without a debugger attached.

The HDF5_ENABLE_COVERAGE option will add -g -O0 -fprofile-arcs -ftest-coverage to CMAKE_C_FLAGS.

X. Considerations for Cross-Compiling

Cross-compiling has several consequences for CMake:

  • CMake cannot automatically detect the target platform.
  • CMake cannot find libraries and headers in the default system directories.
  • Executables built during cross compiling cannot be executed.

Cross-compiling support means that CMake separates information about the build platform and target platform and gives the user mechanisms to solve cross-compiling issues without additional requirements such as running virtual machines, etc.

CMake uses a toolchain of utilities to compile, link libraries, create archives, and other tasks to drive the build. The toolchain utilities available are determined by the languages enabled.

CMake stores info about the current toolchain in the variables CMAKE_C_COMPILER, CMAKE_CXX_COMPILER. They contain paths to the C and C++ compilers respectively. This is usually enough on desktop platforms. In the case of embedded systems, a custom linker and assembler setting may be needed. In more complex projects you may need to additionally specify binaries to other parts of the toolchain (size, ranlib, objcopy…). All these tools should be set in the corresponding variables: CMAKE_AR, CMAKE_ASM_COMPILER, CMAKE_LINKER, CMAKE_OBJCOPY, and CMAKE_RANLIB.

As for the host and target operating systems, CMake stores their names in the following variables:

  • CMAKE_HOST_SYSTEM_NAME – name of the platform, on which CMake is running (host platform). On major operating systems this is set to the Linux, Windows or Darwin (macOS) value.

  • CMAKE_SYSTEM_NAME – name of the platform, for which we are building (target platform). By default, this value is the same as CMAKE_HOST_SYSTEM_NAME, which means that we are building for the local platform (no cross-compilation).

Put the toolchain variables into a separate file (e.g. <toolchain_name>.cmake) and set CMAKE_TOOLCHAIN_FILE variable to the path of that file. If cmake is invoked with the command line parameter --toolchain path/to/file or -DCMAKE_TOOLCHAIN_FILE=path/to/file the file will be loaded early to set values for the compilers. The CMAKE_CROSSCOMPILING variable is set to true when CMake is cross-compiling.

Structure of the toolchain file

In fact, the toolchain file doesn’t have any structure. You can put anything you want there. But the best practice is to define at least these settings: path to the toolchain binaries (C compiler, C++ compiler, linker, etc.), name of the target platform (and optionally target processor architecture), required compilation and linking flags on that particular platform, and toolchain sysroot settings.

It is recommended that you set the CMAKE_FIND_ROOT_PATH variable to a path where you have an exact copy of the root filesystem you have on your target device (with libraries and binaries pre-compiled for the target processor).

References:

https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html
https://gitlab.com/embeddedlinux/libs/platform
https://discourse.cmake.org/t/cross-compile-for-aarch64-on-ubuntu/2161/10
https://stackoverflow.com/questions/54539682/how-to-set-up-cmake-to-cross-compile-with-clang-for-arm-embedded-on-windows?rq=1
https://developer.android.com/ndk/guides/cmake

XI. Creating Custom Preset Configurations

The quickest way to customize your build is to create a CMakeUserPresets.json file in the HDF5 source directory.

Basic Customization Steps:

  1. Copy CMakePresets.json to CMakeUserPresets.json.
  2. Edit CMakeUserPresets.json. Change configuration names from ci-* to my-* and modify the fields as needed.

Example: Using Local Support Files

To change external support files to use a local directory:

{
  "name": "my-base-tgz",
  "hidden": true,
  "inherits": "ci-base",
  "cacheVariables": {
    "HDF5_ALLOW_EXTERNAL_SUPPORT": {"type": "STRING", "value": "TGZ"},
    "TGZPATH": {"type": "PATH", "value": "${sourceParentDir}/temp"}
  }
},
{
  "name": "my-StdCompression",
  "hidden": true,
  "inherits": "my-base-tgz",
  "cacheVariables": {
    ...
  }
},
{
  "name": "my-StdShar",
  "hidden": true,
  "inherits": "my-StdCompression",
  "cacheVariables": {
    ...
  }
},
{
  "name": "my-StdShar-GNUC",
  "description": "My Custom GNUC Standard Config for x64 (Release)",
  "inherits": [
    "ci-x64-Release-GNUC",
    "ci-CPP",
    "ci-Fortran",
    "ci-Java",
    "my-StdShar",
    "my-StdExamples"
  ]
}

Then you can change or add options for your specific case.

Example: Maven Deployment Preset

For Maven deployment with custom repository URL:

{
  "name": "my-maven-custom",
  "inherits": "ci-MinShar-GNUC-Maven-Snapshot",
  "cacheVariables": {
    "MAVEN_REPOSITORY_URL": {
      "type": "STRING",
      "value": "https://your-repo.com/maven"
    },
    "HDF5_ENABLE_ROS3_VFD": {
      "type": "BOOL",
      "value": "ON"
    }
  }
}

Build with:

cmake --workflow --preset my-maven-custom --fresh

Note: This example uses JNI (default). For FFM, inherit from ci-MinShar-GNUC-Maven-FFM-Snapshot.

Preset File Details

CMakePresets.json and CMakeUserPresets.json:

  • Live in the project's root directory.
  • Both have the same format.
  • CMakePresets.json is for project-wide build details (don't modify).
  • CMakeUserPresets.json is for local build customizations (modify to your heart's content).

The HDF Group presets require CMake 3.26 and use the Ninja build system. Ninja may need to be installed separately on some platforms.

Hidden presets (marked "hidden": true) are used for inheritance and cannot be used directly. They are defined in config/cmake-presets/hidden-presets.json.

For more information: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html

XII. Using the Library

For information on using HDF5 see the documentation, tutorials and examples found at https://support.hdfgroup.org/documentation/hdf5/latest/.

A summary of the features included in the built HDF5 installation can be found in the libhdf5.settings file in the same directory as the static and/or shared HDF5 libraries. However CMake provides a programmable method to determine the features of the library. The CMake installation will provide a CMake package configuration file, located in the installation folder, cmake/hdf5-config.cmake, and can be used to determine the features of the library. The file is accessed by using the find_package command in your CMakeLists.txt file.

Set the HDF5_ROOT CMake variable -DHDF5_ROOT=<install_path> or environment variable, set(ENV{HDF5_ROOT} "<install_path>") to the installed location of HDF5. Examples:

  • On Windows: HDF5_ROOT=C:/Program Files/HDF_Group/HDF5/z.y.x/
  • On UNIX and alike: HDF5_ROOT=<install root folder>/HDF_Group/HDF5/z.y.x/

If you are using shared libraries, you may need to add to the path environment variable. Set the path environment variable to the installed location of the library files for HDF5. Examples:

  • On Windows (*.dll): PATH=%PATH%;C:/Program Files/HDF_Group/HDF5/z.y.x/bin
  • On UNIX and alike (*.so): LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<install root folder>/HDF_Group/HDF5/z.y.x/lib

(Note there are no quote characters used on Windows and all platforms use forward slashes)

Add the following to your CMakeLists.txt file:

find_package (HDF5 NAMES hdf5 COMPONENTS C shared)

The components are optional and can be omitted if not needed. The components are: shared, static, C, CXX, Fortran, HL, Java, Tools, and VOL.

XIII. Using CMake Regex Options for Testing

CMake provides a way to use regular expressions to control which tests are executed. The HDF5 CMake build system provides labels for each test that can be used to select tests. The labels are defined in the CMakeTests.cmake files.

Some of the labels are:

PARALLEL

  • MPI_TEST for parallel tests.
  • MPI_TEST_FORT for just parallel Fortran tests.

SERIAL

  • CPP for C++ tests.
  • HL_CPP for high-level C++ tests.
  • FORTRAN for Fortran tests.
  • HL_FORTRAN for high-level Fortran tests.
  • HL for high-level tests.
  • JUnit for Java tests.
  • H5WATCH for tests that use the h5watch SWMR program.
  • SWMR for tests that use the SWMR feature.
  • h5_api for the API tests.
  • VOL for tests that use the VOL feature.
  • VFD for tests that use the VFD feature.
  • H5TEST for the library tests.
  • EX for examples
  • H5CLEAR for the h5clear tool tests.
  • H5COPY for the h5copy tool tests.
  • H5DIFF for the h5diff tool tests.
  • H5DUMP for the h5dump tool tests.
  • H5FC for the h5fc tool tests.
  • H5IMPORT for the h5import tool tests.
  • H5JAM for the h5jam tool tests.
  • H5LS for the h5ls tool tests.
  • H5MKGRP for the h5mkgrp tool tests.
  • H5REPACK for the h5repack tool tests.
  • H5REPART for the h5repart tool tests.
  • H5STAT for the h5stat tool tests.
  • PERFORM for performance tests.

To run tests with a specific label, use the --tests-regex (or -R) option with ctest. For example, to run only the C++ tests, use:

ctest . --tests-regex "CPP"

To run tests with multiple labels, use the | operator to separate the labels. To run tests with the MPI_TEST and FORTRAN labels, use:

ctest . --tests-regex "MPI_TEST|FORTRAN"

To exclude tests with a specific label, use the --exclude-regex (or -E) option with ctest.

For more information on using regular expressions with ctest, see the CMake documentation: https://cmake.org/cmake/help/latest/manual/ctest.1.html#regular-expressions.

XIV. Java FFM Testing

HDF5 2.0 includes comprehensive Foreign Function & Memory (FFM) API tests for Java 25+.

FFM Test Organization

Tests are organized by HDF5 module in java/jtest/:

Module Test Files:

  • TestH5ffm.java - General library operations H5open, H5close, memory management, version info
  • TestH5Affm.java - Attribute operations
  • TestH5Dffm.java - Dataset operations
  • TestH5Effm.java - Error handling
  • TestH5Fffm.java - File operations
  • TestH5FDffm.java - File drivers
  • TestH5Gffm.java - Group operations
  • TestH5Iffm.java - Identifier management
  • TestH5Lffm.java - Link operations
  • TestH5Offm.java - Object operations
  • TestH5Pffm.java - Property lists
  • TestH5PLffm.java - Plugin management
  • TestH5Rffm.java - References
  • TestH5Sffm.java - Dataspace operations
  • TestH5Tffm.java - Datatype operations
  • TestH5VLffm.java - VOL connector
  • TestH5Zffm.java - Filter operations

Running FFM Tests

To run all FFM tests:

ctest -R "JUnitFFM" -V

To run specific module tests:

ctest -R "JUnit-TestH5Affm" -V    # Attributes
ctest -R "JUnit-TestH5Pffm" -V    # Properties
ctest -R "JUnit-TestH5Tffm" -V    # Datatypes
ctest -R "JUnit-TestH5Sffm" -V    # Dataspaces

Test Requirements:

  • Java 25+ with --enable-native-access=ALL-UNNAMED
  • FFM bindings JAR (javahdf5-*.jar)
  • JUnit 4.x test framework
  • HDF5 native libraries in LD_LIBRARY_PATH

FFM Test Patterns:

  • All tests use Arena.ofConfined() for memory management
  • Proper cleanup in try-with-resources blocks
  • Return value checking with isSuccess() / isValidId()
  • See java/jtest/FfmTestSupport.java for utility methods

ROS3 VFD (S3 Object Storage):

  • Tests are compatible with both plain and ROS3-enabled builds
  • Use -DHDF5_ENABLE_ROS3_VFD=ON with any Maven CMake preset for ROS3 builds
  • Example: cmake --preset ci-MinShar-GNUC-Maven -DHDF5_ENABLE_ROS3_VFD=ON
  • Same test suite validates both feature sets

For further assistance, send email to help@hdfgroup.org