build, robust HDF5 discovery — honor HDF Group installs, expose ccmake options

[steven-varga]

Summary

h5cpp's HDF5 discovery is silently shadowed by h5cc on PATH, producing a downgraded HDF5 selection without warning. Make discovery robust, deterministic, and inspectable — including via ccmake.

Reproducer

On a system with multiple HDF5 installs:

$ ls -d /usr/local/HDF_Group/HDF5/*/
/usr/local/HDF_Group/HDF5/1.12.3/

$ /usr/local/bin/h5cc -showconfig | grep "HDF5 Version"
                   HDF5 Version: 1.10.9

$ cmake -S . -B build 2>&1 | grep "Found HDF5"
-- Found HDF5: /usr/local/lib/libhdf5.so ... (found version "1.10.9") found components: C

Expected: 1.12.3 from /usr/local/HDF_Group/HDF5/1.12.3/ is chosen (newer, has cmake/hdf5-config.cmake).
Actual: 1.10.9 from /usr/local/lib is chosen because /usr/local/bin/h5cc is on PATH.

Root cause

CMakeLists.txt:96-103 globs /usr/local/HDF_Group/HDF5/[0-9]* and sets HDF5_ROOT:

file(GLOB _hdf5_custom_roots LIST_DIRECTORIES true "/usr/local/HDF_Group/HDF5/[0-9]*")
list(SORT _hdf5_custom_roots ORDER DESCENDING)
set(HDF5_ROOT ${_hdf5_custom_roots} "/usr/local" "/usr")

This is module-mode discovery (FindHDF5.cmake shipped with CMake). The module prefers h5cc on PATH over HDF5_ROOT — if any h5cc is found, it introspects it and uses the install point reported by h5cc -showconfig, bypassing the GLOB.

Proposed fix

1. Prefer config-mode discovery when an HDF Group install exposes hdf5-config.cmake

When the GLOB finds a directory containing cmake/hdf5-config.cmake, set HDF5_DIR instead of HDF5_ROOT:

if(NOT DEFINED HDF5_DIR AND NOT DEFINED HDF5_ROOT)
    file(GLOB _hdf5_custom_roots LIST_DIRECTORIES true "/usr/local/HDF_Group/HDF5/[0-9]*")
    list(SORT _hdf5_custom_roots ORDER DESCENDING)
    foreach(_root IN LISTS _hdf5_custom_roots)
        if(EXISTS "${_root}/cmake/hdf5-config.cmake")
            set(HDF5_DIR "${_root}/cmake" CACHE PATH "Path to HDF5 CMake config")
            break()
        endif()
    endforeach()
endif()

Config mode (HDF5_DIR → hdf5-config.cmake) is authoritative; it points at one specific install and bypasses the h5cc precedence.

2. Expose HDF5_DIR as a ccmake-friendly STRINGS dropdown

Discover all installs at configure time and offer them as a selectable list:

file(GLOB _hdf5_candidates LIST_DIRECTORIES true
    "/usr/local/HDF_Group/HDF5/*/cmake"
    "/opt/HDF_Group/HDF5/*/cmake"
    "/opt/hdf5*/cmake"
    "$ENV{HOME}/.local/HDF_Group/HDF5/*/cmake"
)
if(_hdf5_candidates)
    set_property(CACHE HDF5_DIR PROPERTY STRINGS ${_hdf5_candidates})
endif()

In ccmake, HDF5_DIR then shows as a dropdown of discovered installs — user picks one, hits c, done.

3. Print the chosen install and the discovery method

message(STATUS "H5CPP HDF5: version=${HDF5_VERSION} via ${_h5_discovery_method} from ${HDF5_INCLUDE_DIRS}")

Where _h5_discovery_method is one of config, module/h5cc, module/HDF5_ROOT, system. Makes silent shadowing impossible to miss.

4. Honor explicit user override above all else

Order of precedence (highest first):

1. -DHDF5_DIR=... on command line
2. HDF5_DIR env var
3. -DHDF5_ROOT=... on command line
4. HDF5_ROOT env var
5. GLOB of HDF Group install dirs (sets HDF5_DIR if hdf5-config.cmake present)
6. GLOB of HDF Group install dirs (sets HDF5_ROOT otherwise)
7. CMake's default FindHDF5 (h5cc on PATH → system paths)

Document this list in cmake/ README or at the top of the HDF5 block.

Acceptance Criteria

• Discovery picks newest HDF Group install when one exists, even with older h5cc on PATH
• -DHDF5_DIR=<path> always wins
• ccmake shows HDF5_DIR as a dropdown of discovered installs
• Configure log prints chosen version + discovery method
• README documents precedence order
• CI matrix unaffected (existing single-install runners still find HDF5 correctly)
• Test on multi-install box: confirm 1.12.3 wins over 1.10.9 h5cc

Out of scope

• Vendoring HDF5 into thirdparty/ (separate discussion)
• Parallel HDF5 / PHDF5 discovery (already handled separately)
• Windows HDF Group install paths (C:\Program Files\HDF_Group\...) — happy to include but lower priority

Background

Discovered while leasing #267 (SWMR). The SWMR feature requires HDF5 ≥ 1.12.3, but the lease build silently picked up 1.10.9 from /usr/local/bin/h5cc and tripped the floor check. Workaround documented in the lease manifest: pass -DHDF5_DIR=/usr/local/HDF_Group/HDF5/1.12.3/cmake. This issue makes the workaround unnecessary.