Skip to content

Publish hdf5-native Maven artifacts (bundled libhdf5 for classpath loading) #6355

@matteodg

Description

@matteodg

Is your feature request related to a problem? Please describe.

HDF5 already publishes Java API JARs (jarhdf5 / hdf5-java-jni, hdf5-java-ffm, etc.) and, for JNI, hdf5-jni-native so the JNI bridge can be delivered via Maven. Even so, running the bindings still requires a separate, correctly versioned libhdf5 on the machine. Users often hit UnsatisfiedLinkError or linker issues until they install HDF5 or fix LD_LIBRARY_PATH / PATH / DYLD_LIBRARY_PATH. That blocks “Maven resolves what I need to run” in CI, containers, and other minimal environments, and encourages version skew between Java artifacts and the C library.

Example documentation still states that Maven does not supply system-level libraries—for instance HDF5Examples/JAVA/README-MAVEN.md emphasizes manual native setup for libhdf5.


Describe the solution you'd like

Add org.hdfgroup:hdf5-native (platform classifiers, e.g. linux-x86_64): a Maven JAR that bundles libhdf5 built by the same CMake tree, using the SciJava native-lib-loader layout under natives/<platform>/.

CMake should produce hdf5-native-*.jar and matching POMs when Maven deployment is enabled; published POMs should integrate with the existing Java artifacts so resolution can place libhdf5 on the classpath together with the API and (where used) hdf5-jni-native. Runtime loading should continue to use hdf.hdf5lib.Hdf5NativeLoader (or equivalent) so bundled hdf5 loads before the JNI bridge when both are present, with escape hatches (-Dhdf.hdf5lib.NativeLibraryBootstrap.skip=true, existing H5 properties) for system installs.

CI should validate and stage/deploy hdf5-native alongside existing JARs.

This work is scoped to the new native bundle and wiring; it does not introduce jarhdf5 or hdf5-jni-native—those remain as today.


Describe alternatives you've considered

  1. Status quo — Keep requiring a system or custom-path libhdf5 for all Maven consumers.
  2. Document heavier — More README for OS packages only; does not fix headless/CI scenarios.
  3. Fat / multi-platform JAR — One artifact for all platforms; awkward versus Maven classifiers and download size.
  4. Custom extraction — Prefer native-lib-loader’s standard layout over bespoke code.

Additional context

  • Licensing / redistribution: Bundled libhdf5 may depend on other vendors’ DLLs/.so files (e.g. zlib on some Windows builds); release notes should mention that when applicable (docs/INSTALL_CMake.md).
  • Branch scope (for reviewers): CMake targets and POMs for hdf5-native, loader/bootstrap integration with existing artifacts, native-lib-loader vendoring path if needed, test/CI classpaths, staging/deploy workflow updates for hdf5-native-*.jar and pom-hdf5-native.xml (exact paths as in the PR).

Metadata

Metadata

Assignees

Labels

No fields configured for Enhancement.

Projects

Status

Planning

Relationships

None yet

Development

No branches or pull requests

Issue actions