hdf5 @1.14: configured to expose v1.10 API

[rmclaren]

The HDF5 Portfile configures HDF5 to expose the v1.10 API via the argument --with-default-api-version=v110. This is kinda unexpected, and breaks some projects which expect to see the newer API given the installed HDF5 version (example JCSDA IODA).

My suggestion is to not add this flag as default. Instead you could add some variants (+v110api and +v112api) so people can opt in to this behavior if it makes sense for their project?

Thanks for maintaining the HDF5 package and for your consideration of this ticket :)

[eborisch (Eric A. Borisch)]

Applications that want the newer interface can always use -DH5_USE_112_API when compiling. It’s always hard to say what’s the best approach for things like this, but the current approach was adopted for POLA (and reduced churn).

I’d be curious to see other deps. try compiling with the 1.12 interface.

[Dave-Allured (Dave Allured)]

It’s always hard to say what’s the best approach ...

In my opinion, best practice for HDF5 with its frequent API changes is simple. Whenever updating HDF5, never add --with-default-api-version. Always keep the default API for the new version being installed.

Therefore, please remove --with-default-api-version=v110 from HDF5 portfile, as suggested by the reporter.

Some dependent ports use only stable HDF5 functions and will not need adjustment. Those that use version-dependent HDF5 functions should declare their version dependency with -DH5_USE_XXX_API at the source. If source does not declare, then add -DH5_USE_XXX_API in Portfile and/or through patches, as appropriate.

The HDF5 library was intentionally designed to work this way. It presents multiple API versions in a single library build. However, dependent ports or "applications" must use the intended compatibility controls unless they are upgraded to the most recent API version. ​https://portal.hdfgroup.org/display/HDF5/API+Compatibility+Macros

This recommended change will require that all direct dependent ports be checked for breakage. Ports with version dependency that do not already use -DH5_USE_XXX_API somewhere, should be fixed as described above.

[Dave-Allured (Dave Allured)]

Instead you could add some variants (+v110api and +v112api) so people can opt in ...

I don't recommend this approach. HDF5 already provides working compatibility controls for both the library and application levels. These should be used as intended, rather than adding port variants.

[Dave-Allured (Dave Allured)]

On 2020 December 13, I recommended that you build the HDF5 V1.12 library with --with-default-api-version=v110 (​PR 7983).

This was useful for the short term, but had delayed consequences. My current advice contradicts this. It is time to move on and go with a new policy of never specifying a down-level default API for this library.

[eborisch (Eric A. Borisch)]

It's easy to see how it's right for yourself, isn't it! ;)

I'm fine moving to the 1.12 interface and putting a note in the commit that If this broke your port; please add -DH5_USE_110_API to your build; seem reasonable?

[Dave-Allured (Dave Allured)]

I'm fine moving to the 1.12 interface ...

A step forward would be good. However, if HDF5 is built with anything other than the default interface, then there remains no way for applications to access the current version (1.14) API. Instead, if you build as default, then all supported API versions will be available to other applications, using one of the -DH5_USE_XXX_API options when needed.

As I see it now, there are zero users asking for the 1.12 interface, and one user asking for the current-version 1.14 interface. So advancing to the default and current version interface (1.14), as suggested by the reporter, would be better than 1.12.

Also please note:
​https://github.com/HDFGroup/hdf5/blob/develop/README.md
"HDF5 1.12 is being retired early due to its incomplete and incompatible VOL layer."

[Dave-Allured (Dave Allured)]

Fixed by ​https://github.com/macports/macports-ports/pull/20321. Please close this ticket.